Randall Stillwell 778fe1d321 plans: scaffold daily-driver-finish, saas-hardening, agent-coordination

Three new plan trees that fill in the gaps surfaced during repo review.
Together they map out what remains between the current scaffold-with-stubs
state and a daily-usable, multitenant, agent-coordinated app.

* Plan-daily-driver-finish (P0): turn stubs into real data. Five tasks
  covering the lint/shared-types breakage, hardcoded dashboard mocks,
  AI-page setTimeout placeholder, post-signin landing decision, and a
  cross-browser collab smoke test against the deployed Hocuspocus
  instance.

* Plan-multitenant-saas-hardening (P1): everything multitenant needs
  beyond what Plan-multitenant-cursor-sync already covers. Invites and
  role management, soft-delete + append-only audit log, rate limits on
  the auth + mutation hot paths, and a Vitest + GitHub Actions test
  foundation so PRs can't ship red.

* Plan-agent-coordination (P2): the layer that makes a Task-*.md
  runnable, not just readable. Adds workflow_prompt with task -> epic
  -> plan inheritance, an agent_runs table for auditable sessions, and
  two new MCP tools (claim_task / complete_task) that replace the
  freeform update_object composition agents do today. Includes an
  intentionally-deferred Epic-optional-orchestrator that captures the
  Symphony-shaped runner as a decision point rather than an immediate
  build.

Each task is bead-scale (one focused Cursor session) with explicit
in-scope, out-of-scope, and anti-goal sections so a future agent can
pick up a single Task-*.md and start without scrollback context.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-01 23:52:22 -05:00

3.6 KiB

Raw Blame History

kind	slug	title	plan_slug	epic_slug	status	priority	tenant_id	owner	cursor_todo_id	updated_at
task	mcp-complete-task-tool	MCP complete_task tool — close an agent_runs row and finalize status	agent-coordination	mcp-claim-complete	ready	P2	global	unassigned	null	2026-06-01

Task summary

A new MCP tool complete_task that an agent calls at session end. It closes the agent_runs row with an outcome and token totals, and optionally flips the backlog item to done (or another terminal status).

Description

Contract

Input zod schema:

{
  runId: string,                  // uuid of the agent_runs row to close
  outcome: "succeeded" | "failed" | "cancelled" | "stalled",
  tokensInput?: number,
  tokensOutput?: number,
  tokensTotal?: number,
  notes?: string,                 // freeform summary, capped at ~2000 chars
  error?: string,                 // optional failure message
  finalStatus?: "done" | "blocked" | "ready" | "in_progress" | "cancelled",
                                  // optional override for the backlog item's status
}

Behavior:

Look up the run; verify it's still open (finished_at IS NULL). If already closed, error RUN_ALREADY_FINISHED.
Resolve the backlog item and confirm its workspace matches the run's workspace.
Update the run row: finished_at=now(), outcome, tokens, notes, error.
Compute the final backlog status:
- If finalStatus provided: use it (validate it's a legal markdown_backlog_items.status value).
- Else if outcome === "succeeded": set status to done.
- Else if outcome === "failed": set status to blocked.
- Else: leave status as-is.
Write audit_log row (action: "task.completed", metadata: { outcome, final_status }).
Return { runId, finishedAt, finalStatus, tokensTotal }.

Token semantics

Take the agent at its word for tokensTotal — don't recompute from input+output. This matches Symphony's "prefer absolute thread totals" rule (SPEC.md §13.5) and avoids double-counting when models report cumulative totals natively.

If tokensTotal is omitted but tokensInput and tokensOutput are provided, compute total as input + output and store. If all three are present and inconsistent, prefer tokensTotal and don't error.

Idempotency

Closing an already-closed run is an error, not a silent no-op. The agent should know it tried to close something twice. If the operator wants to amend a closed run, they can do it via a future tRPC procedure — not through this tool.

Anti-goals

No streaming updates. This tool runs once at session end.
No "extend" or "renew" semantics. A long session that the agent thinks is still going should keep its run open by not calling complete_task. Stall detection is the orchestrator's job (deferred).

Subtasks

Create apps/mcp-server/src/tools/complete-task.ts.
Register in apps/mcp-server/src/tools/index.ts.
Implement the 6-step behavior with zod validation.
Audit log write.
Verify with a manual end-to-end loop: claim_task → do nothing → complete_task and confirm the run row is closed.

Owner or assignee

Unassigned

Status

ready

Estimation

Acceptance criteria

Successful close updates finished_at, outcome, tokens, and (when appropriate) the backlog item's status.
Double-close errors with RUN_ALREADY_FINISHED.
Token inconsistency is resolved by preferring tokensTotal.

Epic: ./Epic-mcp-claim-complete.md
Plan: ../Plan-agent-coordination.md

3.6 KiB Raw Blame History