Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
20 KiB
status, system, requirements, created, owners
| status | system | requirements | created | owners | ||
|---|---|---|---|---|---|---|
| draft | office |
|
2026-04-25 |
|
Office: Agents System Design Part 3
Purpose and boundaries
This design preserves the technical source detail for REQ-OFFICE-AGENTS-001 during migration.
Requirement mapping
| Requirement | Design section |
|---|---|
REQ-OFFICE-AGENTS-001 |
Migrated source detail |
Migrated source detail
Persistence guarantees
What survives a kandev backend restart:
- Agent identity persists in
agent_profiles(Office rows:workspace_id != '' AND deleted_at IS NULL). Name, role, icon,reports_to, Office permissions, budget, concurrency/cooldown settings, skills, instructions, executor preference, and failure policy are durable on the stable identity. Startup profile reconciliation must not replace an Office agent's name with a generated model label. - Execution configuration is referenced, not copied, for Office launches. The resolved
execution_profile_idsupplies the provider CLI, account environment, model, mode, ACP config options, CLI flags and permissions, passthrough behavior, and MCP configuration. Route attempts and sessions retain that ID for audit and restart recovery. - Runtime status persists in
office_agent_runtime(PKagent_id). On restart apausedagent stayspaused,pause_reason(e.g."budget") is preserved, andlast_run_finished_atis retained so the cooldown guard works across restarts. - Reconciliation at startup:
infra.Reconciler.ReconcileAll(called once during boot) dropsoffice_agent_runtimerows whoseagent_idno longer exists inagent_profiles, deletesoffice_channelsandoffice_budget_policiesrows that reference removed agents/projects, and seeds default routine triggers for routines without one. Reconciliation is best-effort: any sub-step that errors is logged but does not block boot. - Hire requests persist as
pending_approvalagent rows plus an approval entry in the inbox. A restart mid-hire leaves the approval visible; the user can still approve or reject and the same activation/deletion paths run. - Instructions (
AGENTS.md,HEARTBEAT.md,SOUL.md,TOOLS.mdand any custom files) live in the office DB (office_agent_instructions) as the source of truth. The exported copy under~/.kandev/runtime/<workspace-slug>/instructions/<agentId>/is regenerated from DB on every session preparation — losing or wiping this directory between runs has no observable effect. - Skills persist in the workspace
skilltable (DB is the source of truth for inline skills; git-sourced skills cache theirfile_inventoryin DB and re-clone on demand). Skill content materialized into<worktree>/<ProjectSkillDir>/<DirName(slug)>/is ephemeral: it is rewritten at the start of every session and thekandev-*patterns added to the common git dir'sinfo/excludeare idempotent. - System skills are re-synced from the embedded
//go:embedset on every boot viaoffice.service.SystemSkills.Sync. Removed slugs are deleted, content is upserted, and per-agentdesired_skillsreferences are preserved across content updates. - Run history (
office_runs,office_run_events,office_activity_log,office_cost_events) is fully durable. Per-run lookups (tasks_touched, costs, events) survive restarts because each row carriesrun_id/session_id. - Filesystem config (
workspace/agents/<name>.yml,workspace/skills/,workspace/routines/) is a separate snapshot used byconfig.ScanFilesystemfor the Sync UI. It is not authoritative: the DB is, and a missing or stale on-disk config never breaks the runtime — at most the Incoming/Outgoing diff is empty or noisy until the user re-syncs.
What does NOT survive a restart:
- In-flight agent sessions: the agent subprocess and its agentctl HTTP server are owned by the kandev process; both die when the backend exits. The
TaskSession.ACPSessionIDandoffice_runsrow are retained, so the orchestrator'sRecoverInstancespath can resume the session — but the partially-streamed turn at the moment of shutdown is lost unless the underlying CLI itself supports replay. - Queued wakeups for capacity-saturated agents: wakeups that were already persisted survive (they live in the same DB tables as the rest). Wakeups that were only held in memory at the time of shutdown are lost; the originating event (task assign, comment, routine fire) must re-emit to re-queue.
- Per-run JWTs (
KANDEV_API_KEY) and the rest of the agent's environment block are minted fresh per session. Old JWTs are not honoured after restart. - Worktrees on disk belong to the task environment's repository rows. They survive backend restart and deletion of every session; physical cleanup begins only from task/environment lifecycle operations. The worktree GC treats the task-environment inventory as authoritative. Injected
kandev-*skill directories under a surviving worktree are stale until the next session rewrites them (the clean-slate step at session start handles this).
There are no TTLs on agent rows, runtime rows, instructions, skills, run history, or activity logs. Retention is by user action only.
Scenarios
Agent lifecycle
-
GIVEN a workspace with no agent instances, WHEN the user creates a CEO instance (selecting a profile, role=ceo), THEN the instance appears in the agents list with status
idleand the sidebar shows it under "Agents". -
GIVEN an existing CLI profile with a custom mode, permission behavior, flags, config options, environment variables, and MCP setup, WHEN routing selects it for an Office launch, THEN that complete execution profile is used while the Office name, role, instructions, skills, permissions, budget, and history remain unchanged.
-
GIVEN the same Office agent later resolves from a Codex execution profile to a Claude execution profile, WHEN the new route launches, THEN the task and Office identity remain stable, Claude receives its own complete runtime configuration, and no Codex-native resume token is sent to Claude.
-
GIVEN an Office task assigned directly to an Office agent and no existing task session, WHEN the task session is prepared, THEN the assignee's stable
agent_profile_idis used before the workspace default so the session can start. -
GIVEN a running CEO instance, WHEN the CEO determines a task requires a frontend specialist and no suitable worker exists, THEN the CEO submits a hire request for a new worker with appropriate skills, and the request appears in the user's inbox as a pending approval.
-
GIVEN a pending hire approval, WHEN the user approves it, THEN the new agent activates (status=idle), appears in the org tree under the CEO, and the CEO receives a wakeup notification.
-
GIVEN a worker instance with
can_create_tasks=true, WHEN the worker creates a subtask exceedingmax_subtask_depth, THEN the creation is rejected and the worker is informed. -
GIVEN a worker instance with status
working, WHEN the user clicks "Pause", THEN the current session completes its turn, the instance moves topaused, and no new wakeups are processed.
Runtime capabilities
-
GIVEN an agent run scoped to task
KAN-1, WHEN the agent posts a comment onKAN-1, THEN Office records an agent-authored comment tied to that run context. -
GIVEN an agent run scoped to task
KAN-1, WHEN the agent tries to updateKAN-2without explicit scope, THEN the runtime denies the action and no task mutation is attempted.
The following operator-boundary scenarios are acceptance criteria that must pass before launcher settings are described as an isolation boundary:
-
GIVEN a running Office agent that can reach the backend, WHEN it submits an execution-profile mutation with its runtime JWT or without a credential, THEN the backend rejects the request and persists no launcher or environment change.
-
GIVEN an authenticated operator authorized for the target profile, WHEN the settings UI saves an execution-profile change, THEN the backend persists the change without exposing the operator credential to any agent runtime surface.
-
GIVEN an Office agent requests execution-profile discovery, WHEN the backend returns the agent-facing catalog, THEN the response contains no literal profile environment values, MCP environment values, MCP headers, or resolved secret material.
-
GIVEN agent-controlled JavaScript is rendered in a task preview, WHEN it attempts to use the operator session, THEN browser origin isolation prevents it from reading operator state or issuing an authenticated control-plane mutation.
-
GIVEN an agent run with
create_subtaskcapability and mutation scope for a parent task, WHEN it creates a subtask under that parent, THEN Office creates the task through the runtime action surface and preserves the caller agent identity. -
GIVEN an agent run without
create_subtaskcapability or without mutation scope for the requested parent, WHEN it attempts parented task creation, THEN Office rejects the request before reading parent relationships or creating any task. -
GIVEN a run without a capability, WHEN the agent attempts the matching action, THEN Office returns a forbidden error and logs no downstream mutation.
Context and instructions
-
GIVEN a CEO agent assigned a new task, WHEN the scheduler wakes it, THEN the agent's
AGENTS.mdwith delegation rules is in the system prompt,HEARTBEAT.mdis on disk at the instructions dir, env vars are set, and the wake payload contains the task details. -
GIVEN a worker agent being resumed for a
task_comment, WHEN it's a resume session, THEN only the new comment is sent in the prompt (instructions not re-injected; agent CLI retains them). -
GIVEN a user editing the CEO's
AGENTS.mdin the Instructions tab, WHEN they save, THEN the DB is updated. The next time the CEO wakes, the updated instructions are exported to disk and used. -
GIVEN a reviewer agent woken for a review, WHEN the scheduler prepares the session, THEN the reviewer's
AGENTS.md(review checklist) is in the prompt, its desired skills are written to the worktree, and the wake payload contains the task's changes.
Skills
-
GIVEN a user on
/office/workspace/skills, WHEN they click "Add Skill" and enter a name, description, and SKILL.md content, THEN the skill appears in the registry and is available for assignment. -
GIVEN a skill assigned to a Claude Code worker, WHEN the worker starts a new session, THEN the skill's
SKILL.mdis written to<worktree>/.claude/skills/<DirName(slug)>/SKILL.md(Claude'sProjectSkillDir) and begins with YAML frontmatter. For non-Claude agents, the path is<worktree>/.agents/skills/<DirName(slug)>/SKILL.md. -
GIVEN a skill sourced from a git URL, WHEN the user creates the skill entry, THEN the repository is cloned and cached and the file inventory displays in the UI.
-
GIVEN a running session with injected skills, WHEN the user edits the skill in the registry, THEN the running session is unaffected (file already written). The next session for that agent picks up updated content.
-
GIVEN an agent with three assigned skills, WHEN the user removes one from the agent config, THEN the next session only writes the remaining two skills to the worktree.
CLI and MCP
-
GIVEN a worker agent woken for
task_assigned, WHEN it needs to update task status, THEN it runs$KANDEV_CLI kandev task update --status in_progress, which reads auth from env vars, callsPOST /api/v1/office/runtime/tasks/:id/status, and returns structured JSON. -
GIVEN an Office agent wants to add a comment without changing status, WHEN it invokes
task update --commentwithout--status, THEN the CLI rejects the command locally and directs it to the signedtasks messagesurface. -
GIVEN a CEO agent delegating work with
create_subtaskcapability and scope for the parent, WHEN it creates a subtask, THEN it runs$KANDEV_CLI kandev task create --title "..." --parent $KANDEV_TASK_ID --assignee agent_id, which callsPOST /api/v1/office/runtime/taskswith the run token and returns the created task ID. -
GIVEN an Office agent tries to move a task between workflow steps or archive it, WHEN it invokes
tasks moveortasks archive, THEN the CLI fails before making an HTTP request and directs the operation to a human or admin because no signed Office runtime capability exists for it. -
GIVEN a CEO with
can_create_projects=true, WHEN the setup task requires a project for a repository, THEN it runs$KANDEV_CLI kandev projects create --name "..." --repository "...", the project is created inKANDEV_WORKSPACE_ID, and the structured response contains its ID. -
GIVEN an Office agent without
can_create_projects, WHEN it attemptsprojects create, THEN the request is rejected with 403 and no project is created. -
GIVEN an Office agent creating a follow-up task for an existing project, WHEN it passes
--project PROJECT_ID, THENtask createsendsproject_id, runtime validation forces the token workspace and verifies the project, parent, and assignee are owned by it, and the created runner is assigned to the requested Office agent. -
GIVEN a direct Office runtime caller, WHEN it supplies a cross-workspace project, parent, or assignee, THEN task creation is denied before persistence or wakeup.
-
GIVEN an Office agent passes priority, blocker, or workspace-policy flags to
task create, WHEN the runtime cannot preserve those fields, THEN the CLI rejects the request explicitly instead of silently dropping them. -
GIVEN a user viewing an office task in advanced mode, WHEN the agent needs clarification, THEN it uses
ask_user_question(available in ModeOffice) and the user sees the question in the UI. -
GIVEN an office agent in ModeOffice, WHEN something tries to call
create_task_kandevMCP tool, THEN the MCP server returns an error saying to use$KANDEV_CLIinstead. -
GIVEN an office agent in ModeOffice, WHEN its first-turn system context is generated, THEN every advertised MCP tool is registered in ModeOffice, including
step_complete_kandev. -
GIVEN an Office-owned task without a scheduler-prepared signed run context, WHEN a generic manual or workflow task/session path attempts to start it in ModeOffice, THEN Kandev starts no agent process and returns an error directing the caller to start or wake the task through Office.
-
GIVEN a regular kanban task (non-office), WHEN a user starts a session, THEN ModeTask is used with the full Kanban MCP surface, including
step_complete_kandev. No Office CLI capability changes that behavior. -
GIVEN a regular task-mode session, WHEN an agent invokes
agentctl kandevwithout Office runtime credentials, THEN the CLI explains thatKANDEV_API_URLandKANDEV_API_KEYare injected automatically only for Office runs and directs the agent to its Kandev MCP tools. -
GIVEN a regular Kanban task on a step with a default agent profile, WHEN the runner projection resolves that profile, THEN the profile selects the execution identity without changing Office ownership or the session's
ModeTaskMCP surface. -
GIVEN a Docker executor, WHEN the agent runs
$KANDEV_CLI kandev task get, THEN agentctl resolves to/usr/local/bin/agentctl(on PATH inside the container), reads env vars, and calls the backend API. -
GIVEN a worker in a Docker container, WHEN the scheduler prepares the session, THEN skill files are written to the worktree on the host (under the agent type's
ProjectSkillDir), the worktree is mounted into the container, and the agent discovers skills in its CWD. -
GIVEN a CEO on Sprites, WHEN the scheduler prepares the session, THEN skill and instruction files are uploaded via the filesystem API to the equivalent paths inside the sprite.
Permissions
-
GIVEN a worker that calls
POST /office/agents, WHEN the backend validates the JWT, it loads the worker's permissions, seescan_create_agents: false, and returns 403 Forbidden. -
GIVEN a CEO creating a worker, WHEN it passes
role: "worker"with no permission overrides, THEN the backend applies worker defaults. The CEO can optionally passpermissions: {"can_assign_tasks": true}to give the worker delegation ability. -
GIVEN a user on the agent detail page, WHEN they click Configuration, THEN they see all permissions as toggles with the role default indicated. They can override any permission and save.
-
GIVEN a CEO trying to create an agent with
can_create_agents: true, WHEN the CEO itself has that permission, THEN it's allowed. If a worker (who lacks it) tries the same, it's rejected.
Dashboard and runs
-
GIVEN an agent with run history, WHEN the user opens
/office/agents/:id/dashboard, THEN the page returns server-rendered with the latest run card, the four 14-day charts, recent tasks, and costs populated from a singlesummaryround-trip. -
GIVEN a RUNNING run, WHEN the user opens its run detail page, THEN the SSR-supplied transcript and events render immediately and the Client Component subscribes to the run's WS channel, merging appended messages into state without a refetch.
-
GIVEN a FAILED run with an auth error, WHEN the user opens the run detail, THEN the header shows an "auth required" banner linking to the agent settings.
-
GIVEN a long run list, WHEN the user scrolls
/office/agents/:id/runs, THEN "Load more" fetches the next page using a(requested_at, id)cursor with stable order.
Out of scope
- Agent-to-agent real-time communication. Agents communicate via tasks and comments only.
- Custom agent binaries. Instances use the existing agent registry (Claude, Codex, Copilot, etc.).
- Automatic scaling of agent instances by workload; agent migration between workspaces.
- Replacing the existing scheduler. Distributed scheduling or multi-backend leader election. A public external API for third-party agent runtimes.
SOUL.md/TOOLS.mdcontent for v1 (empty files created, content later). AutomaticTOOLS.mdgeneration from API schema.- Per-task instruction overrides. All agents of a role share the same instructions.
- Skill marketplace or cross-workspace skill sharing. Skill versioning beyond what git-sourced skills offer.
- Skill-level permissions. All skills are available to all agents in the workspace; assignment is the access control.
- Automatic skill recommendation based on task content.
- Bash completion for
agentctl kandevsubcommands. Offline/cached mode for CLI. Incremental skill sync. - CLI commands for workspace config CRUD (workflows, executors). Handled by ModeConfig MCP tools used by IDE agents.
- CLI creation of additional Office workspaces. Office agents operate inside
KANDEV_WORKSPACE_ID; humans create or import workspaces through onboarding and settings. - Configurable date range on dashboard charts. Fixed 14 days for v1.
- Bespoke transcript renderer or adapter-specific "Nice mode" parsers. The existing session-messages component is reused.
- Object-store offload for run logs. The
office_run_eventstable covers the structured event log. - Per-run browser/system notifications. The inbox covers the failure path.
- Pagination for the recent-runs sidebar beyond a fixed ~30 row window.