Gap Analysis & Roadmap

This document identifies 15 capabilities that a Super Admin AI agent would need but cannot fully perform today, along with a phased implementation roadmap.

Gap Summary

#	Gap	Severity	What Exists Today	What's Missing
1	Agent Self-Registration	HIGH	POST /api/agents (user-scoped)	No agent-initiated registration flow
2	Config Self-Update	HIGH	PATCH /api/agents/:name (user-scoped)	No /agents/me endpoint for self-service
3	API Key Self-Rotation	HIGH	POST /api/settings/api-key/regenerate	No agent-scoped key rotation
4	Task Dependency Orchestration	HIGH	depends_on column in kanban_tasks	No dependency validation or auto-advance
5	Audit Trail Access	MED	immutable_audit_log table exists	No agent-facing query endpoint
6	Bi-directional Agent Messaging	MED	POST /api/agent-messages (one-way)	No reply/ack, no delivery status
7	Agent-Scoped Memory	MED	POST/GET /api/memories	No agent_id isolation, no TTL
8	Agent-Initiated Scheduling	HIGH	/api/cron-jobs (user-scoped)	No agent self-scheduling
9	Bulk File Operations	MED	Document CRUD exists	No batch upload, no versioning
10	Agent Quota Monitoring	MED	/api/health (system-wide)	No per-agent rate limit/token budget query
11	Agent Webhook Self-Subscription	MED	POST /api/webhooks/register (user-scoped)	No agent-initiated subscription
12	Secret Management	HIGH	Integration credentials exist	No agent-scoped secret vault
13	Capability Self-Inspection	LOW	POST /api/agent-capabilities/resolve	No /agents/me/capabilities shorthand
14	Agent Worker Spawning	MED	POST /api/agents/:name/clone	No parent-child tracking, not agent-initiated
15	Task Checkpointing	HIGH	agent_executions table exists	No checkpoint/resume mechanism

Detailed Gap Descriptions

Gap 1: Agent Self-Registration

Problem: An external AI agent (e.g., Gemini) cannot register itself as a Cortex agent. It must be pre-created by a human user.

Suggested Endpoint: POST /api/agents/self-register

• Agent provides its own definition, capabilities, and callback URL
• Returns a scoped API key
• Requires pre-authorized registration token from the org admin

Gap 2: Config Self-Update

Problem: Agents cannot update their own configuration. PATCH /api/agents/:name requires the user who created the agent.

Suggested Endpoint: PATCH /api/agents/me

• Agent updates its own systemPrompt, model, capabilities
• Scoped to fields the agent is allowed to modify
• Requires agent.update capability at write level

Gap 3: API Key Self-Rotation

Problem: API key rotation is user-scoped. An autonomous agent cannot rotate its own credentials.

Suggested Endpoint: POST /api/agents/me/rotate-key

• Returns new sk-ctx-* key, invalidates old one
• Grace period (5 min) where both old and new keys work
• Audit logged

Gap 4: Task Dependency Orchestration

Problem: The depends_on column exists in kanban_tasks but there's no validation or automatic status progression when dependencies complete.

Suggested Implementation:

• Validate dependency graph on task creation (reject cycles)
• Auto-advance blocked tasks when all dependencies reach done
• GET /api/kanban-tasks/:id/dependencies — view dependency tree
• Broadcast task.unblocked event when dependencies clear

Gap 5: Audit Trail Access

Problem: The immutable_audit_log table exists but has no agent-facing query endpoint.

Suggested Endpoint: GET /api/audit-log

• Query by: action, actor, target, dateRange
• Paginated, scope-aware
• Read-only (immutable by design)

Gap 6: Bi-directional Agent Messaging

Problem: POST /api/agent-messages exists but is one-way. No reply mechanism, no delivery confirmation.

Suggested Extensions:

• POST /api/agent-messages/:id/reply — threaded replies
• PATCH /api/agent-messages/:id/ack — delivery acknowledgment
• GET /api/agent-messages/inbox — unread messages for current agent
• Delivery status: sent, delivered, read, failed

Gap 7: Agent-Scoped Memory

Problem: Memory entries are user-scoped, not agent-scoped. No TTL for automatic cleanup.

Suggested Extensions:

• Add agent_id column to memories table
• GET /api/memories?agent=my-agent — agent-scoped queries
• ttl field on memory creation (auto-delete after expiry)
• Memory quotas per agent

Gap 8: Agent-Initiated Scheduling

Problem: Cron jobs are user-created. An agent cannot schedule its own recurring tasks.

Suggested Endpoint: POST /api/agents/me/schedules

• Agent creates a cron job that invokes itself
• Limited to schedule.create capability
• Max schedules per agent (configurable)

Gap 9: Bulk File Operations

Problem: Documents support only single-file CRUD. No batch upload or versioning.

Suggested Extensions:

• POST /api/documents/bulk — upload multiple documents
• GET /api/documents/:id/versions — version history
• POST /api/documents/:id/revert/:versionId — revert to version

Gap 10: Agent Quota Monitoring

Problem: Agents cannot query their own rate limits or token budget.

Suggested Endpoint: GET /api/agents/me/quota

• Current rate limit remaining
• Token budget used/remaining (if configured)
• Execution count today
• Next reset timestamp

Gap 11: Agent Webhook Self-Subscription

Problem: Webhook registration is user-scoped. Agents cannot subscribe to events for themselves.

Suggested Endpoint: POST /api/agents/me/webhooks

• Agent registers its own callback URL for specific events
• Scoped to events the agent has read access to
• Auto-cleaned when agent is deactivated

Gap 12: Secret Management

Problem: Integration credentials exist but there's no agent-scoped secret vault.

Suggested Endpoints:

• POST /api/agents/me/secrets — store encrypted secret
• GET /api/agents/me/secrets/:key — retrieve (returns masked or via secure channel)
• DELETE /api/agents/me/secrets/:key — remove
• AES-GCM-256 encryption, same as LLM provider keys

Gap 13: Capability Self-Inspection

Problem: Agents must call POST /api/agent-capabilities/resolve with their own name. No shorthand.

Suggested Endpoint: GET /api/agents/me/capabilities

• Returns resolved capabilities for the calling agent
• No request body needed
• Simplest gap to close

Gap 14: Agent Worker Spawning

Problem: POST /api/agents/:name/clone exists but doesn't track parent-child relationships and isn't agent-initiated.

Suggested Extensions:

• POST /api/agents/me/spawn — create child agent
• parent_agent_id field in agent definition
• GET /api/agents/me/children — list spawned agents
• Auto-cleanup: children deactivated when parent completes

Gap 15: Task Checkpointing

Problem: agent_executions tracks start/end but not intermediate progress. Long-running tasks can't resume after failure.

Suggested Endpoints:

• POST /api/agents/me/checkpoint — save progress snapshot
• GET /api/agents/me/checkpoint/:taskId — retrieve last checkpoint
• Checkpoint data stored in R2 (large payloads) or Turso (small)
• Agent resumes from last checkpoint on retry

Phased Roadmap

Phase 1 — Foundation (Weeks 1-3)

Low-effort, high-value gaps that unblock basic agent autonomy.

Gap	Effort	Impact
#13 Capability Self-Inspection	1 day	Agents can discover their own permissions
#3 API Key Self-Rotation	2 days	Agents can manage their own credentials
#5 Audit Trail Access	2 days	Agents can query platform audit log
#10 Quota Monitoring	2 days	Agents can self-regulate resource usage
#11 Webhook Self-Subscription	3 days	Agents can subscribe to events autonomously

Phase 2 — Autonomy (Weeks 4-6)

Agent self-service capabilities for independent operation.

Gap	Effort	Impact
#1 Agent Self-Registration	3 days	External AI agents can onboard themselves
#2 Config Self-Update	2 days	Agents can evolve their own configuration
#4 Task Dependencies	5 days	Automated workflow progression
#12 Secret Management	3 days	Agents can securely store credentials

Phase 3 — Scale (Weeks 7-10)

Inter-agent coordination and communication.

Gap	Effort	Impact
#6 Bi-directional Messaging	5 days	Agents can converse and coordinate
#7 Agent-Scoped Memory	3 days	Isolated memory per agent with TTL
#8 Agent Scheduling	3 days	Agents create their own recurring tasks
#14 Worker Spawning	4 days	Agents can create child agents

Phase 4 — Resilience (Weeks 11-14)

Fault tolerance and bulk operations.

Gap	Effort	Impact
#9 Bulk File Operations	4 days	Efficient multi-document workflows
#15 Task Checkpointing	5 days	Resumable long-running tasks
Confirmation Flow (from Capability Control)	5 days	Human-in-the-loop for dangerous ops