Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
25 KiB
status, system, requirements, created, owners
| status | system | requirements | created | owners | ||
|---|---|---|---|---|---|---|
| draft | office |
|
2026-05-02 |
|
Office Tasks System Design Part 1
Purpose and boundaries
This design preserves the technical source detail for REQ-OFFICE-TASKS-001 during migration.
Requirement mapping
| Requirement | Design section |
|---|---|
REQ-OFFICE-TASKS-001 |
Migrated source detail |
Migrated source detail
Why
Office tasks are the unit of work in office mode: a single task carries a description, a workspace, an assignee, optional reviewers and approvers, blockers, parent/child relationships, a chat thread, and a per-agent session of working memory. Users and agents need to drive these tasks end-to-end - hand off context across a tree of subtasks, request review and approval, edit properties inline, see the agent's work in the chat, react to property changes without an agent having to poll, and preserve each participant's conversation across many short-lived agent runs.
This spec consolidates the office task surface: lifecycle, parent/child handoffs, approval flow, advanced execution mode, blocker cycle detection, the reactivity pipeline, per-(task, agent) session identity, inline editable properties, and the chat / activity views.
Session constraint boundary
The current schema stores the Office agent identity in
task_sessions.agent_profile_id. The shared table has no pair-wide constraint
because Kanban rows also use this column and can legitimately share the pair.
CreateOfficeTaskSession guards live pairs inside a transaction. Lookup prefers
live rows and retains existing duplicate rows. A future cross-process SQLite
topology would need an Office-only discriminator and a partial index. No such
schema change is part of the current design.
What
A. Lifecycle and identity
- A task progresses through statuses
todo → in_progress → in_review → done, withblockedandcancelledas branchable states. Status transitions are user- or agent-driven and feed the reactivity pipeline (section E). - Every office task has zero or more task sessions: one per
(task_id, agent_profile_id)pair. A session represents one agent's persistent conversation thread on the task, not a single launch. - Sessions cycle through
CREATED → STARTING → RUNNING → IDLE → RUNNING → IDLE → ...for as many turns as the agent is woken. A session is terminal (COMPLETED/FAILED/CANCELLED) only when the agent leaves the task's participants list. - Wakeups (section E) drive transitions IDLE → RUNNING. Turn-complete events drive RUNNING → IDLE, tearing down the executor and agent process entirely; the conversation is preserved via the stored ACP session token.
- Kanban / quick-chat sessions keep their per-launch model and
WAITING_FOR_INPUTsemantics - office's IDLE state is office-scoped.
B. Parent / child handoffs
- Tasks form a tree via
parent_id. Parent tasks act as the default home for shared specs, plans, and coordination documents. - Child tasks can read parent-owned documents and write parent-owned coordination documents by default. Document handoffs reuse the existing blocker mechanism: a consumer task is blocked-by the producer task and reads the resulting documents from its wakeup prompt context. There is no separate "required documents" data type.
- Agents can list related tasks (parent, children, siblings, blockers, blocked) and can read/write allowed task documents via MCP or CLI tools.
- A parent task defines a default child workspace policy for its tree: children inherit the parent workspace OR create their own workspace.
- A parent task defines a default child ordering policy: children are created with dependency edges (sequential) or without (parallel).
- Each child task can override the parent workspace policy and run in the parent workspace, a new workspace, or an explicit shared workspace group.
- When a user creates a subtask from a Kanban task detail dialog, the dialog lets them choose to inherit the parent materialized workspace or create a new workspace from repositories, local folders, or remote URLs.
- When the user chooses to inherit the parent workspace, the dialog can identify the parent session branch because the child shares that worktree and file state.
- When the user chooses a new workspace, the dialog shows only the selected source and base-branch controls. It does not present the parent session branch as the branch of the isolated child workspace.
- When an agent creates a subtask through
create_task_kandev, the MCP surface mirrors that choice: subtasks inherit the parent materialized workspace by default, andworkspace_mode="new_workspace"requests a fresh materialized workspace/worktree. - Subtasks inheriting a parent materialized workspace are represented through the same shared workspace group model used by Office-created tasks.
- Shared workspaces are visible in the UI: source task, member tasks, materialized path/environment, and whether tasks are ordered by dependencies.
- Workspace sharing does not lock execution in v1. Sequential behavior is expressed through task blocker / dependency edges.
- Wakeup prompt context names whether the agent should read parent documents, source-task documents, or shared workspace files; document bodies are NOT injected inline.
- Archiving or deleting a task releases it from shared workspace membership and can trigger cleanup when no active, non-archived members remain.
- Archiving a parent task cancels active descendant runs, recursively archives descendants, releases their workspace memberships, and runs cleanup.
- Deleting a parent task cancels active descendant runs, recursively deletes descendants, releases their workspace memberships, and runs cleanup.
C. Approval flow
- A task carries two participant lists: reviewers (advisory) and approvers (gating). The lists are edited inline from the Properties panel.
- When a task enters
in_review, every reviewer AND approver is woken withtask_review_requested. The wakeup carriesroleso the agent's prompt renders an appropriate hint. - A task SHALL NOT transition
in_review → donewhile it has any approvers without a currentdecision = approved. Reviewers are advisory and do not gate completion. - Transitioning
in_review → todo|in_progress(rework) supersedes all prior decisions; re-enteringin_reviewstarts a fresh round. - Approving a task while approvers are pending wakes the assignee with
task_changes_requested(when changes are requested) ortask_ready_to_close(when the final approval lands). - Recording a decision does NOT terminate the deciding agent's session. The reviewer's session stays IDLE between cycles and is re-used on a subsequent
task_review_requestedwakeup. - Tasks awaiting the current user's review/approval surface in the inbox as item type
task_review_requestonly when the user/agent is a reviewer or approver participant with a required decision. Runner/assignee participation alone does not create a review inbox item. - v1 approval is unanimous: every listed approver must approve. There is no quorum / any-of-N mode.
D. Inline editable properties
- Every property row that holds an enumerable, lookup-able, or free-text value is editable inline by clicking the value: Status, Priority, Assignee, Project, Parent task, Blocked by, Reviewers, Approvers, Labels, Title, Description.
- Read-only rows stay read-only: Created by, Started, Completed, Created, Updated, Tree cost metrics. They reflect events, not user intent.
- Edits are optimistic: the new value renders immediately; on API failure the row reverts to the prior value and a toast surfaces the error.
- Pickers are searchable when the candidate list could exceed roughly 10 items (Assignee, Project, Parent, Blocked-by). Status and Priority pickers use a fixed list. The threshold for switching to a search input is around 8 candidates.
- The editor works inline on the task detail page - no separate dialog, no navigation.
- Property changes broadcast over the existing WS event stream so other open clients update reactively. No polling.
E. Reactivity pipeline
A backend pipeline runs synchronously on every relevant task property change. Property mutators (UpdateTaskStatus, MoveTask, SetTaskAssignee, CreateTaskComment, blocker mutations, participant mutations) feed the pipeline; the pipeline returns wakeups, patches, and decision records that are persisted in one DB transaction alongside the user's change.
Wakeup triggers:
status → done: query tasks blocked by this task; wake each with{reason: "blocker_resolved", resolved_blocker_task_id}. Wake the parent task with{reason: "child_completed"}if all siblings are done.status: blocked → unblocked: wake assignee with{reason: "task_unblocked"}.status: done|cancelled → todo|in_progress: wake assignee with{reason: "task_reopened", actor_id, actor_type}.- Assignee change: wake new assignee with
{reason: "assigned", comment_id?, actor_id}. If old assignee had an active session, cancel it cleanly (session.cancellednotification) and surface that to the new assignee's context. - Created task with assignee: if a newly-created task or subtask already has a runner, queue the same assigned wakeup idempotently with
{reason: "assigned", task_id}. - Comment created by user: wake assignee with
{reason: "user_comment", comment_id}. Wake any @-mentioned agents in the same workspace with{reason: "mentioned", comment_id}. status → in_review: wake every reviewer and approver with{reason: "task_review_requested", role}.decision = changes_requested: wake assignee with{reason: "task_changes_requested", comment}.- All approvers have approved AND status is
in_review: wake assignee with{reason: "task_ready_to_close"}. status → cancelled: cancel the task's active execution immediately (interrupt the current turn, mark the session cancelled) and emitoffice.task.cancelled.
Execution-policy transition engine runs alongside wakeups: reads the task's execution_policy (work / review / approval stages) and returns (1) a patch to apply alongside the user's change (e.g. advance execution_state to review_pending), (2) wakeups to queue, (3) a decision record if the transition encodes an approval verdict. The engine is invoked from every mutation entry point and MUST NOT poll or schedule.
Wakeup context carries a structured JSON payload: reason, task_id, optional actor_id/actor_type, optional comment_id, cascade-specific fields (resolved_blocker_task_id, child_task_id), policy fields (stage_id, allowed_actions). The agent runtime reads context.reason to select the system prompt template.
F. Blocker cycle detection
- Adding a blocker
B blocks ASHALL be rejected when a path already exists fromBback toAthrough existing blockers. This catches cycles of length 3 or more (existing checks already cover self-blocking and direct two-node cycles). - The detection runs as a breadth-first walk starting at the proposed
blockerTaskID, traversing the blocker chain via existing repository queries, bounded by a visited set. - A rejected attempt returns a typed error including the cycle path (e.g.
"would create cycle: A → B → C → A"). The frontend blockers picker surfaces the message as a toast and rolls back its optimistic chip.
G. Per-(task, agent) session lifecycle
task_sessionsrows use(task_id, agent_profile_id)for Office identity. The same pair reuses one row across many wakeups. Kanban and quick-chat sessions also useagent_profile_idand keep their per-launch andis_primarymodel.- A single task may carry multiple sessions: assignee, each reviewer, each approver, each @-mentioned agent. Each maintains its own conversation; one agent's notes never appear in another's buffer.
- On wakeup,
EnsureSessionForAgent(task, agent_profile_id):- Looks up the row by
(task_id, agent_profile_id). - If found and IDLE: flip to RUNNING.
- If found and RUNNING/STARTING: return as-is (idempotent).
- If found and terminal: create a new row (prior pair was retired).
- If not found: insert with state
CREATED.
- Looks up the row by
- ACP init: if
acp_session_idis stored, callsession/load. On failure (expired session, agent CLI version mismatch), fall back tosession/newand overwrite the stored token. Row identity is preserved at the kandev level even when the underlying conversation is reset. - On turn complete for office sessions, the agent process AND executor backend (container, standalone process, sprites instance, agentctl) tear down completely. The conversation is preserved via the stored ACP token. The next wakeup recreates the executor cold.
- A session goes terminal (
COMPLETED) only on participation removal:- Reassignment retires the previous assignee's session.
- Removing a reviewer/approver via the picker retires that agent's session.
- Deleting the agent instance at workspace level cascades and retires all of its sessions across all tasks.
- Decisions (approve / request-changes) do NOT terminate the deciding agent's session - they cycle RUNNING → IDLE so a subsequent review round resumes the same conversation.
- Re-adding the same agent after a terminal row creates a fresh row with a fresh conversation thread.
H. Advanced mode
/office/tasks/[id]?mode=advancedexposes dockview panels (files, terminal, changes) backed by a running agentctl execution.- Office tasks usually have no warm execution (the agent ran and tore down), so entering advanced mode SHALL ensure an execution exists for the resolved session without sending a new prompt to the agent.
- The session resolved for advanced mode is:
- The current viewer's session if the viewer is an authenticated agent.
- Otherwise (singleton human user), the current assignee's session.
- If no session exists yet (user enters advanced mode before the first wakeup), create one for the assignee on demand, then ensure the executor.
- Panels gate on
agentctlStatus.isReady; existing WS eventssession.agentctl_starting/session.agentctl_readydrive their loading states. No panel directly creates executions. - If executor resume fails, the call is non-fatal: the session still returns and panels show their existing "not available" states.
I. Task chat
The Chat tab on the office task detail page is a unified timeline of comments, agent work, and system events.
Auto-bridging agent responses to comments:
- When an agent completes a turn, its final text message is auto-posted as a
task_commentwithauthor_type=agentandsource=session. - Only messages of type
message(notstatus,script_execution, etc.) are bridged. - The comment carries the agent's name as
author_id. - Duplicate comments are prevented by checking for an existing
source=sessioncomment for the same turn.
Merged thread:
The Chat tab displays a chronological merge of:
- User comments posted via the comment input or API.
- Agent comments auto-bridged from session messages, or posted via
kandev comment add. Agent comments from auto-bridge show a "via session" indicator. - Timeline events for status changes (SCHEDULING, IN_PROGRESS, REVIEW, DONE) and assignee changes, rendered as compact system entries.
- Inline approval-decision events ("CEO approved this task" / "Eng Lead requested changes: '...'").
Expandable agent session in chat (v2):
- Between comments, each agent work session appears as a collapsible entry, one per (task, agent) pair, ordered by most-recent activity.
- Collapsed: shows "Agent worked for Xm Ys" with a chevron. If running, shows a spinner and "Agent working..." and auto-expands.
- Expanded: renders the
AdvancedChatPanelcomponent (reused from advanced mode) with the full session transcript - tool calls, thinking, messages. - A task with assignee + 2 reviewers shows up to 3 entries. Each entry collapses when its agent's session is IDLE; expanded by default while RUNNING.
- The "ran N commands" header derives from messages on that session, accumulated across launches.
Reply wakes agent:
- Posting a comment on a task with an
assignee_agent_instance_idqueues atask_commentwakeup for that assignee. - The agent receives the comment text in its wakeup context and can respond on its next turn.
Activity tab:
- Task status transitions (CREATED → SCHEDULING → IN_PROGRESS → REVIEW → DONE) are logged to
office_activity_logwithtarget_type=taskandtarget_id=taskID. - The Activity tab renders these entries with the status transition and timestamp.
Sidebar counters:
- The office sidebar shows count badges next to Tasks, Skills, and Routines, fetched from the dashboard API or dedicated count endpoints, updated on navigation or data change.
Data model
task_sessions
id TEXT PK
task_id TEXT FK -> office_tasks.id
agent_profile_id TEXT nullable -- shared by Office, Kanban, and quick-chat
acp_session_id TEXT nullable -- preserved across IDLE turns
state enum CREATED | STARTING | RUNNING | IDLE
| WAITING_FOR_INPUT | COMPLETED | FAILED | CANCELLED
is_primary bool -- kanban resume; office never reads this
...
-- No table-level pair constraint. CreateOfficeTaskSession guards live
-- Office pairs inside a transaction and retains historical duplicates.
office_task_approval_decisions
id TEXT PK
task_id TEXT FK -> office_tasks.id ON DELETE CASCADE
decider_type enum user | agent
decider_id TEXT '' for user
role enum reviewer | approver
decision enum approved | changes_requested
comment TEXT default ''
created_at DATETIME
superseded_at DATETIME nullable -- non-NULL when replaced by a newer decision
INDEX idx_task_decisions_task (task_id)
office_task_execution_decisions
id TEXT PK
task_id TEXT FK -> office_tasks.id
stage_id TEXT
verdict enum approved | changes_requested | rejected
actor_id TEXT
actor_type enum user | agent
comment_id TEXT nullable
created_at DATETIME
task_blockers -- existing
task_id TEXT FK
blocker_task_id TEXT FK
CHECK (task_id != blocker_task_id)
task_comments -- existing, extended
...
author_type enum user | agent
source enum manual | session -- session = auto-bridged from agent turn
office_activity_log -- existing, extended
target_type enum ... | task
target_id TEXT
event_type TEXT -- 'status_changed', ...
...
Multiple rows per (task, decider, role) in office_task_approval_decisions are allowed; only the most recent (superseded_at IS NULL) counts toward the gate.
API surface
HTTP (office task service):
POST /tasks/:id/approve { comment?: string }- caller approves. 403 if caller is not in reviewers or approvers. Returns the created decision row.POST /tasks/:id/request-changes { comment: string }- caller requests changes. Comment required. Same 403 rule. Returns the decision row.GET /tasks/:id/decisions- current (non-superseded) decisions. Also surfaced on the task detail endpoint as adecisions: TaskDecision[]field.PATCH /tasks/:id- inline property edits (status, priority, assignee, project, parent, blocked-by, reviewers, approvers, labels). Returns the updated task. Title and description are not fields of this endpoint; they are edited throughPATCH /api/v1/tasks/:id.POST /tasks/:id/blockers { blocker_task_id }- returns 400 with a body carrying the cycle path when the addition would create a cycle.DELETE /tasks/:id/reviewers/:agentId/DELETE /tasks/:id/approvers/:agentId- removes the participant AND terminates that agent's session for the task.
WebSocket:
session.ensure { task_id, ensure_execution?: bool }- idempotent; returns the resolved session. Whenensure_executionis true and the session exists without a running execution, the backend ensures the executor resumes. Non-fatal on resume failure.office.task.decision_recorded { task_id, decision_id, role, decider_type, decider_id, decision, created_at }.office.task.review_requested { task_id, role, reviewer_agent_id }- fans out per reviewer for client-side inbox refresh.office.task.cancelled { task_id }.office.task.updated/office.task.status_changed- existing events continue to fire on property and status mutations.session.agentctl_starting/session.agentctl_ready- existing events drive advanced-mode panel readiness.
Go interfaces:
EnsureSessionForAgent(ctx, task, agentInstance) (*TaskSession, error)- office wakeup launch path.applyTaskExecutionPolicyTransition(task, change) (patch, []Wakeup, *Decision)- policy engine, invoked synchronously inside every mutator that can advance a stage.- Wakeup queue producers emit a structured
contextJSON (reason,task_id, optional fields per section E).
State machine
Task session (office):
CREATED ──► STARTING ──► RUNNING ──► IDLE ──► RUNNING ──► IDLE ──► ...
│ │
▼ ▼
COMPLETED COMPLETED (on participation removal)
/ FAILED / FAILED
/ CANCELLED / CANCELLED
IDLE → RUNNING: a wakeup for the matching(task, agent_instance)fires.EnsureSessionForAgentflips the row.RUNNING → IDLE: turn-complete event for an office session. The agent process and executor backend tear down.acp_session_idis preserved.RUNNING → CANCELLED: status set tocancelled, or an explicit hard cancel from the reactivity pipeline (e.g. reassignment of the prior assignee).* → COMPLETED: participation removal (reassignment of assignee, picker-removal of reviewer/approver, workspace-level deletion of the agent instance). Plain decisions do NOT cause this.
The updateTaskSessionState terminal-state guard relaxes for office: COMPLETED / FAILED / CANCELLED stay terminal, but IDLE → RUNNING is allowed.
Kanban / quick-chat sessions keep CREATED → STARTING → RUNNING → WAITING_FOR_INPUT → ... and warm executors between turns; office-only states are not used.
Task status (relevant transitions for reactivity):
todo ──► in_progress ──► in_review ──► done
│ │ │ ▲
│ ▼ │ │
└───────► blocked └── todo / in_progress (rework, supersedes decisions)
└───────► cancelled (from any non-terminal state)
Permissions
There are two authorization layers: agent capability (what a running agent can do via runtime APIs) and HTTP caller identity (what a UI user or JWT-bearing agent can do via task endpoints). See agents.md for the agent role / permission model that supplies the capability set on each run.
Agent runtime capabilities (resolved from role + permission overrides; enforced by the office runtime handlers):
| Task action | Required capability | Default holders |
|---|---|---|
| Post a comment / reply | post_comment |
All roles (assignee, reviewers, approvers, mentioned agents). |
| Change task status | update_task_status |
All roles. |
| Create a subtask | create_subtask |
Roles with can_create_tasks (CEO, worker). |
| Request approval on a task | request_approval |
Roles with can_approve (CEO). |
| Spawn an agent run on a task (assign and wake) | spawn_agent_run |
Roles with can_assign_tasks (CEO, worker). |
An agent's run JWT also pins an AllowedTaskIDs scope. The runtime rejects mutations against any task outside that scope with ErrTaskOutOfScope (403, shared.ErrForbidden), even when the capability is granted - this prevents a worker on task T1 from mutating task T2 just because both belong to its workspace.
HTTP endpoint gates (internal/office/approvals, task service):
POST /tasks/:id/approve,POST /tasks/:id/request-changes: when called by an agent (caller has an agent JWT), the handler additionally checks: (1)caller.WorkspaceID == task.WorkspaceID(403 otherwise), (2)has_permission(can_approve)(403 otherwise), (3) the caller is not the requester of the approval (403 self-decide). Reviewers / approvers list membership is the user-facing gate; thecan_approvepermission is the underlying agent gate. UI callers (no agent JWT) are accepted without these checks today.DELETE /tasks/:id/reviewers/:agentId,DELETE /tasks/:id/approvers/:agentId: caller must be a workspace UI user; no agent-side endpoint exposes participant removal.PATCH /tasks/:id(inline property edits) andPOST /tasks/:id/blockers: no per-field authorization in v1; any UI user with workspace access can edit any task, and any agent with the appropriate runtime capability can mutate within its task scope.- Approver gate on
done: independent of caller identity. Adonetransition is rejected 409 while any approver lacks a currentapproveddecision (see Failure modes).
Out of scope for this iteration:
- A "no permission" UI state for fields a user cannot edit, and per-field user-side permission rules (see
out of scope). - Granular per-task ACLs beyond workspace membership.
- Workspace-level rules for who can be added as assignee / reviewer / approver - those follow the existing agent / workspace membership rules and are not redefined here.