Epic: Agentic platform primitives (Harness + Registry)

[philmerrell]

Tracking hub for the primitive-enablement effort. Plan of record: docs/specs/agentic-platform-primitives.md (added in #558).

Goal

Enable the reusable primitive layer — headless execution, delivery, scheduling, first-class KB, memory, governance — so proactive-agent use cases (a chief-of-staff "Oliver", digests, monitoring, triage) become configuration, not bespoke features.

• Harness owns run → the headless run entrypoint (F1).
• Registry owns catalog + govern → discovery + governance seam (F6).

The six fundamentals

	Fundamental	State
F1	Headless, trigger-agnostic run entrypoint (run_agent_headless)	keystone — spike next
F2	Async result + delivery spine (run-record + session)	minimal in Phase A
F3	Scheduled trigger (modeled on sync_policies)	Phase B
F4	KB as first-class primitive (decouple from Assistants)	Phase C (open decision)
F5	Memory primitive (finish user-markdown-memory)	Phase C
F6a	Governance floor (audit / guardrails / PII)	pulled into Phase A
F6b	Registry catalog + dynamic discovery	Phase D (deferred)

Phase checklist

• Docs / plan of record — docs(specs): agentic platform primitives plan (+ scheduled-runs design + F1 spike brief) #558
• Phase A — F1 spike (Fable 5) — headless run as a user + server-side SSE + governance-floor seam, proven in dev-ai. Brief: harness-entrypoint-spike-brief.md. Output = design note + go/no-go.
• Decision gate — resolve the three open decisions using spike findings.
• Phase A build — run_agent_headless + minimal F2 + F6a floor + "Run now" (top-tier model).
• Phase B — F3 scheduler — data model + CRUD + dispatcher/worker + SPA (fan-out, cheaper tier).
• Phase C — F4 ∥ F5 — first-class KB + memory primitive.
• Phase D — F6b — Registry-backed catalog + dynamic discovery (after Tier-1 gateway-search measurement).
• Validation use cases — Oliver + digest + monitoring, as configuration.
• GA — grant scheduled-runs capability to the default role; keep SCHEDULED_RUNS_ENABLED kill switch.

Resolved decisions

1. F1 = minimal internal run_agent_headless(...), A2A-ready seam (not an A2A server yet; if ever exposed, capabilities must include streaming=True).
2. Governance is foundational — F6a floor forward into Phase A; F6b discovery deferred.

Open decisions (resolve at the gate)

• KB decoupling appetite (F4) — do the refactor now, or let scheduled runs borrow an assistant's KB in the interim?
• F6a floor depth — minimum audit/guardrails/classification to ship Phase A unattended-as-user.
• Sequencing — confirm proactive-spine-first (F1→F2→F3) with F4/F5 in parallel.

Cross-cutting

Cohort-gate each primitive via RBAC scheduled-runs capability + SCHEDULED_RUNS_ENABLED kill switch. Model-tiering: keystone → top model (Fable 5), pattern-following fan-out → cheapest adequate. UX bar: flexible foundation, minimal user-facing surface, governance backend-invisible.

🤖 Generated with Claude Code

[philmerrell]

Phase A — F1 spike: started (Fable 5, isolated worktree). Proving unattended-as-user runtime auth + server-side SSE against dev-ai, per docs/specs/harness-entrypoint-spike-brief.md. Deliverable: docs/specs/harness-entrypoint-spike-findings.md (design note) + go/no-go. #558 merged.

[philmerrell]

Phase A — F1 spike: COMPLETE → GO. Proven end-to-end in dev-ai (run run-8f10d164cff9). Findings + design deliverables: docs/specs/harness-entrypoint-spike-findings.md on branch spike/harness-headless-entrypoint (pushed for reference; spike code, not for direct merge — Phase A hardens it).

Headline decision for the gate: the preferred workload-token auth path is provably impossible (gateway JWT authorizer rejects the opaque workload blob; SigV4 refused). Chosen path = platform mints a per-owner Cognito access token by replaying the user's stored BFF refresh token → the platform can act as a user unattended for up to the BFF session lifetime (~30d since last login). Sound design (every downstream layer sees a genuine user token), but it's an explicit 'act as user' governance decision that needs sign-off — ties directly into the F6a floor + FERPA.

Open decisions now resolvable: F6a floor depth (audit implemented fail-closed; guardrails + PII are wired seams), the act-as-user token policy, KB decoupling, sequencing.

[philmerrell]

Decision gate cleared — all four calls locked (decision record: #560).

1. Act-as-user auth → per-owner Cognito token behind an explicit headless-grant record (own consent/revocation; "logged in within N days" policy).
2. F6a floor → audit fail-closed now; "Run now" = audit-only + seams; scheduled runs require PII checkpoint before cohort scheduling.
3. KB decoupling (F4) → deferred (borrow assistant KB).
4. Sequencing → proactive-spine-first confirmed.

Phase A (PR-1) started — Fable 5 hardening the spike into a reviewable PR (feature/harness-phase-a off the spike branch): production harness + "Run now" app-api route (cookie auth + scheduled-runs capability + SCHEDULED_RUNS_ENABLED flag) + headless-grant record + tests. Scheduler/SPA/guardrails-impl remain out of scope.

[philmerrell]

Phase A (PR-1) COMPLETE → draft PR #561 — full backend suite green (4208 passed), infra jest green (429), no new packages. Reviewed (orchestrator pass): faithful to locked decisions, no Phase-A blockers. One substantive finding logged for Phase B: the F6a classify_output PII checkpoint is structured 'before delivery', but the runtime turn persists the session/messages during the turn — so for scheduled runs the checkpoint must run in-loop or as a post-hoc scrub, not a pre-delivery gate. Details on #561.

[philmerrell]

Phase B started. Brief: #562. Work breakdown + tiering:

• B1 (Sonnet, in progress) — inert schedule data model + CRUD (mirrors sync_policies); schedules can be created but nothing fires. Draft PR incoming.
• B0 (Fable 5, pending Phil's fork decision) — fill the F6a PII/guardrails checkpoints for scheduled runs; resolve the classify_output ordering (in-loop vs post-hoc scrub).
• B2 (Sonnet, after B1) — dispatcher/worker + EventBridge (mirror KB-sync); delivery stays disabled until B0.
• B3 (Sonnet) — SPA.

Gating decision for scheduled delivery = the B0 in-loop-vs-scrub fork (see #562 §1).

[philmerrell]

Governance simplified (Phil's steer): scheduled runs execute as the owner with the owner's RBAC and deliver only to the owner's own session list — no new access boundary, no new recipient. So governance is role/auth-based (RBAC + grant lifecycle + quota + fail-closed audit, all already built); the content-classification pass is not needed. B0 dropped; B2 delivery unblocked. Revised primitives §6-4 + Phase B brief §1 in #562.

[philmerrell]

B1 COMPLETE → draft PR #563 (Sonnet). Inert schedule data model + CRUD on /schedules, mirrors sync_policies; suite green (4283 passed, 68 new). Reviewed: correct + faithful, no blockers (2 minor notes for B3 on #563). Ready to merge. B2 (dispatcher/worker) + B3 (SPA) depend on B1's code — will launch off develop once #563 merges.

[philmerrell]

B2 + B3 started in parallel (Sonnet), off develop with B1 merged.

• B2 — scheduler engine: dispatcher (due-sweep + runaway guard + conditional re-arm) + worker (mint → run_agent_headless(trigger=schedule) → record) + EventBridge/IAM (mirror KB-sync). Worker pauses cleanly on grant-expired (paused_error/reason reauth_required) instead of error-spam.
• B3 — schedule SPA + a small POST /runs/grant enable endpoint (so a user can turn on scheduled runs without clicking 'Run now'), grant-status + re-enable UX, and the B1 clear-optional-field affordance.

After both land + review: end-to-end scheduled runs behind the flag + scheduled-runs capability, ready to enable for the beta cohort.

[philmerrell]

B3 COMPLETE → draft PR #564 (Sonnet). POST /runs/grant enable endpoint + full schedule SPA (list/create/edit/pause/resume/delete, enablement banner, paused-state UX). Reviewed: clean, no blockers. Backend 62 pass, frontend ng test green.

Known follow-up (B-follow): B1's update_scheduled_prompt skips None → no way to clear assistantId/enabledTools on edit. B3 added omit-field checkboxes (documented no-op) + flagged it. Needs a small backend PATCH-clear contract before those work end-to-end. Non-blocking.

B2 (engine) still finishing on resume (it built everything but stalled before committing).

[philmerrell]

B2 COMPLETE → draft PR #565. Scheduler dispatcher + worker + EventBridge/IAM. Sonnet stalled before committing; finished + reviewed on Opus (per Phil's call to stop conserving). CDK/IAM correct as built (tightly scoped, no InvokeAgentRuntime — minted-bearer front door).

Defect found + fixed in review: the failure breaker used a last-status proxy that caps the streak at 2, so at the production default MAX_FAILURES=3 the repeated_failures pause could never fire (the existing test passed only because it set the threshold to 2). Fixed with a persistent consecutive_failures counter (mirrors sync_policies) + regression tests at the default. Backend 4302 pass, infra jest 429 pass.

Phase B is code-complete (B1 merged; B2 #565 + B3 #564 open). After both merge: end-to-end scheduled runs behind the flag + capability, GA = grant capability to default role.

[philmerrell]

Phase B COMPLETE ✅ (2026-07-05)

All merged to develop: B1 (#563), B2 (#565), B3 (#564). End-to-end scheduled runs now exist behind SCHEDULED_RUNS_ENABLED + the scheduled-runs capability.

Checklist status:

• Docs / plan of record (docs(specs): agentic platform primitives plan (+ scheduled-runs design + F1 spike brief) #558)
• Phase A — F1 spike (GO) + build (feat(harness): Phase A — headless run entrypoint + Run now (PR-1) #561)
• Decision gate (all locked; docs(specs): F1 spike findings + locked decision-gate calls #560)
• Phase B — F3 scheduler: B1 CRUD + B2 engine + B3 SPA & enable endpoint
• Enable + dogfood (ops, not code): flip the flag in dev, grant the capability to a tester, run a real schedule end-to-end
• Phase C — F4 KB-decoupling ∥ F5 memory
• Phase D — F6b Registry discovery (deferred)
• GA — grant scheduled-runs to default role

Known follow-up (non-blocking): B1's update_scheduled_prompt skips None → can't clear assistantId/enabledTools on edit; needs a small PATCH-clear contract. B3 added omit-field checkboxes (no-op) + flagged it.

Fan-out review catches (for the record): B2's failure-breaker was dead at the production default (fixed on Opus, persistent counter); B3's CI failed on router NG04002 unhandled rejections (fixed). Both passed the agents' self-reports — the review gate caught them.

Continuing in a new conversation from here.