[simple-agent-manager]

Summary

Implements idea 01M5PRH5C9ZBZ1C21AYQ8QWMC5 (SAM task 01M5SKY95H590EWADCMP505NEW): make the user-level SAM Connector (/connect/mcp) usable for coordinating a team of agents from ChatGPT or Claude. All changes go through the shared operations registry, so the Connector stays a thin adapter.

1. Readable transcripts. sam_chat_read now returns whole messages by default. Streamed chunks are assembled inside the ProjectData Durable Object (durable-objects/project-data/logical-transcript*.ts, logical-message.ts). Pages break only between messages, so each chunk appears exactly once across pages. Tool calls, hidden thoughts and plans become bounded activity entries instead of being dropped. The first page names the latest user request and assistant reply. limit counts messages, and role filters scan a bounded, disclosed window instead of returning empty pages. Long messages are capped with truncated + nextOffset, and the new sam_chat_message_get reads the rest by offset. Thinking is withheld unless requested. unit: "rows" keeps the previous stored-row paging for diagnostics. sam_chats_search attaches whole-message excerpts to the top results. sam_task_get now returns the complete latest assistant reply.
2. Schedules with receipts. New tools sam_schedules_list, sam_schedule_get, sam_schedule_create, sam_schedule_update and sam_schedule_cancel sit over the existing one-off ProjectData schedules and cron triggers. Wall-clock input is converted to UTC with explicit DST gap and overlap handling. Creates are idempotent (Connector receipt plus a DO idempotency key). Scheduled starts spend the same start budget as sam_chat_start. Responses keep acceptance, admission, execution receipt, task outcome and owner notification separate, and report unknowns as unknown. Recurring schedules can be paused, resumed or edited, but not deleted, through the Connector.
3. Channels. New tools sam_channels_list, sam_channel_history, sam_channel_get (roster + subscribers) and sam_channel_subscription_cancel (only for chats the caller can write). Peer posts are fenced as untrusted text. Humans still cannot post to channels: that needs a new human actor for channel events, and it is filed for a decision as Idea 01M5SR2HB56YT0VFY6BB6TCNCK.
4. Team view. New sam_team_status (scope: task, chat or coordination channel) returns bounded lineage, state with observation freshness, blockers and agent questions, PR head/CI state, evidence labelled agent-claimed vs control-plane, and measured usage. Values SAM does not record are reported as such: per-task tokens unavailable, deployed SHA not_recorded, provider subscription limits provider_reported_last_observed. Nothing is estimated.
5. Agent questions are visible. request_human_input questions now appear as pendingAttention in sam_chat_read (owners and shared writers only), as attention in sam_chat_interactions, and in sam_work_changes fingerprints. sam_inbox_get selects chats with open questions ahead of the recency cap, and its notifications carry the marker ID, category and options. Underneath: marker create/resolve now refresh the D1 session summary, the summary prefers answerable questions over other markers, and notification dedup keeps the newest marker's metadata. Answering still needs sam_agent_answer, which the Connector instructions require the user to confirm.

Review-driven changes (local specialist review, see below): sam_inbox_get checks at most limit chats per page (questions first); team status lists as many tasks as fit the response, shortening agent text (new setting connector.teamTextChars) only when that lists more, with disclosure; results are sized by what the adapter actually sends (both copies of the result, including the escaped text copy); ProjectData migration 070 indexes attention-marker changes and the summary delta reads them as two indexed row sets; archived transcript reads share one R2 deadline and, when it runs out, return what they read with a resume cursor; sam_task_get / get_task_details recentAssistantMessages are whole replies (they were raw streamed chunks); shared helpers instead of copies (run rule, row parser that logs content-free reasons, response byte budget, DIRECT_CHANNEL_RANGE_END in packages/shared).

Adjacent fixes found on the way: PATCH /api/projects/:id/triggers/:triggerId resuming with a new cron computed the next fire from the old cron (shared services/trigger-status.ts), and the DO schedule list now skips one malformed row instead of failing the whole read (rule 50).

Read limits are admin settings in the Connector category (connector.*, services/connector-read-settings-definition.ts), not new Worker env vars. Migration 0208 adds two partial indexes on tasks (parent_task_id, (project_id, coordination_channel)).

Tool schema changes and compatibility

• Tool count 27 → 38 (read-only 20 → 27). New read tools: sam_chat_message_get, sam_team_status, sam_schedules_list, sam_schedule_get, sam_channels_list, sam_channel_history, sam_channel_get. New write tools: sam_schedule_create, sam_schedule_update, sam_schedule_cancel (destructive), sam_channel_subscription_cancel (write). Read-only connections see no write tools.
• sam_chat_read: new optional unit (messages default, rows legacy). The default response shape changes to logical messages (paginationUnit: "logical_messages"). Cursor format is unchanged, and legacy mid-message cursors are flagged. The workspace-agent path is unchanged.
• Additive fields only on sam_chats_search (excerpt, excerptCoverage), sam_chat_interactions (attention) and sam_inbox_get (question, coverage, cursor attention key). sam_inbox_get pages check at most limit chats, questions first; older inbox cursors still parse.
• sam_task_get: finalAssistantMessage is the complete latest reply and recentAssistantMessages are whole replies, newest first (same field names and shape, plus optional partialBefore / truncated).
• sam_team_status results carry counts.listed, truncated, omitted and agentTextShortenedTo when a team is too large for one response; a task without agent text has summary: null, and the untrusted-text guidance is stated once (untrustedTextGuidance).
• Connector refresh: clients that cache the tool list must refresh or reconnect the SAM connector to see the new tools. Existing tools keep their names.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test
• Additional validation run (if applicable)
• If this PR changes candidate selection for a sweep/cron/alarm loop (WHERE clause, status set, join, or equivalent), expected candidate volume and worst-case per-candidate cost are stated in the summary or validation notes (see .claude/rules/47-control-loop-io-budget.md)

Local validation (branch head after review fixes):

• pnpm check:fast (format ratchet, ESLint, type-boundary ratchet) and tsc --noEmit for apps/api and apps/web: pass.
• Quality gates: quality:source-contract-tests, quality:do-migration-safety, quality:migration-safety, quality:migration-ordering, quality:runtime-tunables, quality:wrangler-bindings, file-size check for new files: pass.
• Full apps/api unit suite on 12580f35f: 13,889 tests, 0 failures (JSON reporter success: true). The changes after it, in 2ae748061 (channel and search fitting, the unknown continuation flag, logging the skipped row's id), were verified with the affected unit files (622 tests, plus 50 project-event tests); CI runs the full suite on the head. An earlier run found one failure, the omitted-var coverage guard flagging a new read of PROJECT_DATA_ARCHIVE_R2_TIMEOUT_MS; it was fixed in bc2e2c09b.
• The first CI run on this draft found two regressions, both fixed in 582789824. (1) Resolving an attention marker returned SQLite rowsWritten, which on a Durable Object also counts index entries, so migration 070 changed the count; it now returns the number of markers resolved. (2) Pull-request states always carried null headSha and checksUpdatedAt, which grew byte-bounded agent context enough to drop an idea update; they now appear only when known.
• Workers runtime: tests/workers/connector-whole-message-team-tools.test.ts (new; real /connect/mcp adapter into the real ProjectData Durable Object), plus connector-oauth, notification-dedup-do, workflow-runs, session-summary-index-sync, project-data-compact-archive (all pass; re-run after the last fixes: 61 tests in the four affected files) and sam-grounding-runtime under the SAM runtime config (35 pass).
• Guards proven discriminating by reverting each once (the named test went red): team text shortening and task dropping (team-status.test.ts), inbox per-page cap (connector-operations.test.ts), indexed summary delta and migration 070 (session-summary-sync.test.ts plan test), shared archive R2 deadline (logical-transcript-archive.test.ts), scheduled-start budget in both directions (execution.test.ts), off-page latest fitting (connector-transcript.test.ts), excerpt owner memo (connector-transcript.test.ts), recent-replies page budget (task-final-assistant-message.test.ts), plus the earlier dedup metadata, summary priority, inbox question-first, legacy cursor, writer gate, schedule list isolation and trigger PATCH checks.

I/O per call (rule 60): sam_chat_read 5 (owner) or 8 (shared writer); sam_chat_message_get 2–3; sam_chats_search about 3 plus up to connector.searchContextResults (default 3, max 5) excerpt reads, owner looked up once per chat; sam_inbox_get at most 10 (4 D1, at most limit InteractionStore reads, 1 Notification; was 9); sam_team_status about 8–12; sam_task_get one whole-message read (was two raw reads); schedule and channel tools 2–5. Inbox, search and team status are cross-project or project-wide aggregations (budget 20).

Candidate selection (rule 47): the ProjectData session-summary delta now also selects sessions whose attention markers were created or resolved since the last sync. Expected volume is the number of marker changes since the previous debounced sync (small, still capped by the existing LIMIT); per-candidate cost is unchanged (one D1 upsert). Both halves are index range searches (migration 070, pinned by a query-plan test).

Staging Verification (REQUIRED for all code changes — merge-blocking)

N/A: staging skipped by explicit user authorization for this task ("User explicitly authorizes SKIPPING STAGING for this task. Do not add a staging deployment/test gate."). Verification is local unit/integration tests, CI, specialist review, and read-only/owned-fixture checks against production after deploy.

• Staging deployment green — skipped by explicit user authorization
• Live app verified via Playwright — skipped by explicit user authorization
• Existing workflows confirmed working — covered by the full API unit suite and CI
• New feature/fix verified on staging — replaced by production read-only checks after deploy (recorded below)
• Infrastructure verification completed — N/A: no infra changes
• Mobile and desktop verification notes added for UI changes — N/A: no UI changes

Staging Verification Evidence

N/A: staging skipped by explicit user authorization. Production verification evidence is added after deploy.

UI Compliance Checklist (Required for UI changes)

N/A: no UI change. The only apps/web edit imports DIRECT_CHANNEL_RANGE_END from packages/shared instead of defining the same value locally (apps/web/src/lib/query-options/automation.ts); web typecheck and automation-flows.test.tsx pass, and the CI visual audit runs because the path changed.

UI Screenshot Evidence

N/A: no UI changes.

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations (see .claude/rules/10-e2e-verification.md)
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code (not just "read the code")
• If any gap exists between automated test coverage and full E2E, manual verification steps documented below

Data Flow Trace

1. App → POST /connect/mcp (routes/connector-mcp.ts:createConnectorServer) → operations/registry.ts → samChatRead.run (operations/platform-operations.ts) → authorizeProjectOperation → readChat (operations/chat-core.ts): writerPendingRequests (InteractionStore via connectorPendingInteractions; pendingAttention in operations/attention-core.ts → services/project-data.ts:listActiveAttentionMarkers → durable-objects/project-data/attention.ts) and readChatMessages (operations/chat-transcript.ts) → services/project-data.ts:getLogicalTranscriptPage → DO archiveSourceGetLogicalTranscript / archiveTargetGetLogicalTranscript (durable-objects/project-data/index.ts) → readLogicalTranscriptPage (logical-transcript.ts) over sourceTranscriptReader / targetTranscriptReader (message-context.ts) → byte budget (operations/response-budget.ts) → envelope size check in connector-mcp.ts.
2. request_human_input (routes/mcp/human-input-tool.ts) → DO createAttentionMarker → scheduleSummarySync → session-summary-sync.ts:SESSION_SUMMARY_DELTA_SQL → D1 session_summaries.attention_json (summary prefers answerable questions, attention.ts:getAttentionSummary) → sam_inbox_get (operations/connector-read-core.ts:inboxGet); Notification DO dedup keeps the newest marker's metadata (durable-objects/notification.ts) → inbox question.
3. sam_team_status (operations/team-operations.ts) → teamStatus (operations/team-core.ts) → readTeamTasks (operations/team-lineage.ts, recursive CTE on the migration 0208 index) + listAgentActivityTasks, DO getSessionsByTaskIds, getPullRequestStates, agent_sessions, compute_usage, listProjectCredentialLimits → fitTasks.
4. sam_schedule_create (operations/schedule-operations.ts) → createSchedule (operations/schedule-writes.ts) → executeConnectorWrite (services/connector-execution.ts: receipt, write and start budgets) → DO createProjectSchedule (one-off) or createTrigger (services/trigger-create.ts, recurring) → sam_schedule_get (operations/schedule-reads.ts:getSchedule → schedule-core.ts:findSchedule).
5. Channels: sam_channels_list / sam_channel_history / sam_channel_get (operations/channel-operations.ts) → DO listProjectEventChannels / getProjectEventChannelHistory / listProjectEventChannelSubscribers + D1 roster (channel-core.ts:channelRoster); sam_channel_subscription_cancel → requireSubscriptionCanceller → DO cancelProjectEventSubscription.

Capability test across the boundaries: apps/api/tests/workers/connector-whole-message-team-tools.test.ts.

Untested Gaps

• Staging was skipped by explicit user authorization. After the production deploy, verification uses read-only checks and owned fixtures only (recorded below once done).
• A recurring (cron) schedule is created through the operation against real SQLite D1 (schedule-operations.test.ts), not through the Workers adapter path.
• The shared archive R2 deadline is tested at the reader with a fake clock, not against real R2 latency.
• Deliberately not built (tracked in Ideas 01M5SR2HB56YT0VFY6BB6TCNCK and 01M5SR2Q7PH4FEK8YDYDQDJ10M): human channel posting, inbox coverage of shared chats, /sam access to the new reads, newest-first channel history, cron UTC-offset zones, per-task token counts, per-member privacy of schedule text and direct channels. Deployed commit is reported as not_recorded.

Post-Mortem (Required for bug fix PRs)

N/A: not a bug fix. This PR is a feature; the two adjacent fixes (trigger PATCH next-fire cron, schedule list row isolation) carry regression tests.

Specialist Review Evidence (Required for agent-authored PRs)

• All local reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human

Reviewer	Status	Outcome
security-auditor	ADDRESSED	No critical or high findings. MEDIUM: schedule prompt and reason text is visible to every project member; kept at REST and web parity because chats are project-visible, and per-member privacy is recorded for a decision in Idea 01M5SR2Q7PH4FEK8YDYDQDJ10M (item 6). LOW: agent-dm.* participant check (same idea); team status shows that a question exists without its text, by design.
cloudflare-specialist	ADDRESSED	MEDIUM unindexed attention-marker delta: ProjectData migration 070 plus an indexed UNION delta with a query-plan test (80e09af88). MEDIUM per-page R2 deadline: one budget per archived read (80e09af88), returning what was read when it runs out (8a4cb8338). LOW/MEDIUM whole-run concatenation: only the requested slice is built (80e09af88).
performance-reviewer	ADDRESSED	HIGH inbox fan-out: at most limit chats per page, questions first (eed17870f). HIGH unindexed summary-sync subquery: migration 070 plus a plan test (80e09af88). MEDIUM excerpt owner lookup per hit: one lookup per chat, and connector.searchContextResults capped at 5 (85c57625d). LOW sequential findSchedule: kept, because a parallel lookup would add a D1 query to every one-off read.
architecture-reviewer	ADDRESSED	HIGH duplicated run rule and page size: one definition. HIGH duplicated row parsers: shared parseRowsSkippingInvalid. MEDIUM DIRECT_CHANNEL_RANGE_END moved to packages/shared. MEDIUM unused type alias removed. LOW shared UTF-8 helper reused. All in eed17870f.
constitution-validator	ADDRESSED	MEDIUM hardcoded team text cap: now the connector.teamTextChars setting. LOW attention category length: categories validated against HUMAN_INPUT_CATEGORIES. LOW bind chunk size: uses the shared D1 limit. All in eed17870f.
test-engineer	ADDRESSED	HIGH: tests added for the scheduled-start budget, archived-chat reads and an off-page latest message. MEDIUM: Workers tools/call slice through the real adapter and Durable Object, schedule kinds pinned, sam_chat_message_get non-member case. LOW: exact error codes, and the real DO RPC exercised. Commits 80e09af88 and 85c57625d.
doc-sync-validator	ADDRESSED	MEDIUM team activity states corrected; new behaviour documented (85c57625d, 8a4cb8338).
task-completion-validator	PASS	Checks A–F pass. The task file lists the verified criteria and each deferral with its Idea (85c57625d).
fix-verification review (general-purpose, of the fix commits)	ADDRESSED	No critical or high findings. MEDIUM: a shared archive deadline could fail a whole read; it now returns partial results. MEDIUM: team fitting shortened text needlessly; it now shortens only when that lists more tasks, with null empty text. LOW: old inbox cursors, zero-task fit, a response measure that counts both copies, and one final-reply rule. Fixed in 8a4cb8338. A confirmation pass found every one of those findings resolved and four new LOWs, all fixed in 2ae748061: channel pages and search excerpts are now fitted to the response, an out-of-time continuation is reported as unknown, and skipped schedule rows are logged with their id.

CodeRabbit Review Evidence (Required for agent-authored PRs)

• CodeRabbit requested after local review, staging if applicable, and CI gates passed
• Waited about 15 minutes, or up to about 45 minutes in total while a review CodeRabbit had started was still in progress
• Either CodeRabbit reviewed and no CodeRabbit feedback is unresolved, or it did not review and the observed outcome is recorded below

CodeRabbit Notes

Requested at 2026-10-25 17:22:44 UTC by applying the coderabbit-review label after the PR left draft with CI green; the trusted bridge workflow (run 40216177798) succeeded. CodeRabbit answered at 17:22:58 UTC: "Action not completed: Review rate limited". It had also posted a "Review limit reached" notice when the draft opened at 16:23 UTC. CodeRabbit did not review. Per .claude/rules/25-review-merge-gate.md, the rate-limit outcome is recorded and the PR proceeds on its remaining gates; it was not re-triggered.

Production Deployment and Verification

Merged as a3a802caab12fabf18fa8e785f06ea1e94183452 at 2026-10-25 17:37:34 UTC.

• Main CI: run 40217371249 succeeded. The first attempt failed on a flaky web test (skill-form-dialog-agent-models.test.tsx), which passed 3 of 3 runs locally, and the re-run passed.
• Deploy Production: run 40219994438.
  • Attempt 1 was blocked by the post-migration D1 integrity gate: DATABASE.vm_provisioning_leases: 1 -> 0 (100.000% decrease exceeds 50% churning-table limit). Migration 0208 (two CREATE INDEX statements on tasks) was applied at 18:18:36 UTC. The Worker was not deployed.
  • Diagnosis, from read-only production D1 queries: a VM admission moved to placed at 18:19:00.872 UTC, between the gate's two counts, and placement deletes its provisioning lease (releaseVmProvisioningLease). The lease count is still 0, and both new indexes exist. No restore was run; the printed time-travel restore would have erased legitimate production writes.
  • Attempt 2 re-ran the failed job. The migration ledger no longer advanced, so the gate logged "Post-migration data integrity check SKIPPED. No migrations were applied to any database." The deploy succeeded, including "Record successful production deployment".
  • The false positive is tracked as idea 01M5T541KKCR7Y9H78VCQ3K0P7.
• Deployed version: Cloudflare deployment of sam-api-prod at 18:38:58 UTC with annotation commit:a3a802caab12fabf18fa8e785f06ea1e94183452, version 3a8b3d4e-7561-460f-a77a-26aa1431e487 at 100% of traffic.
• Public smoke, no credentials:
  • API health returns 200 healthy, and the app returns 200.
  • /.well-known/oauth-protected-resource/connect/mcp returns 200 with resource https://api.simple-agent-manager.org/connect/mcp and scopes sam.read sam.write.
  • An unauthenticated POST /connect/mcp returns 401 with the Bearer resource_metadata challenge.
• Shared operations on production data: these ran through SAM MCP, which calls the same operations as the Connector. All were read-only and used this task's own records.
  • get_task_details calls samTaskGet. Before the deploy, recentAssistantMessages held five one-chunk fragments of a single reply. After the deploy it holds five whole replies, newest first, assembled by the ProjectData logical transcript reader.
  • search_messages (samChatsSearch) and get_linked_context (samLinkedContextGet) return without errors.
• Not verified in production: an authenticated tools/call through /connect/mcp itself. No production Connector token or OAuth client is available to this workspace; the smoke token is staging-only by design. The adapter path is covered by tests/workers/connector-whole-message-team-tools.test.ts, which uses the real adapter, a PAT and a real Durable Object.

Exceptions (If any)

• Scope: Staging deployment and staging verification.
• Rationale: The user explicitly authorized skipping staging for this task. Production verification uses read-only and owned-fixture checks only.
• Expiration: This PR only.

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: no new external APIs. Internal contracts only; IANA time zone conversion uses the runtime Intl.DateTimeFormat already used by the web automation page.

Codebase Impact Analysis

apps/api/src/durable-objects/project-data/ (logical transcript readers, attention summary, summary sync, schedule list isolation, compact archive deadline), apps/api/src/durable-objects/migrations.ts (ProjectData migration 070, additive indexes), apps/api/src/durable-objects/notification.ts (dedup metadata), apps/api/src/lib/runtime-validation.ts + apps/api/src/services/workflow-run-read.ts (shared row parser), packages/shared/src/types/project-event-channels.ts + apps/web/src/lib/query-options/automation.ts (shared constant), apps/api/src/operations/ (chat, transcript, attention, inbox, team, schedule, channel operations; registry), apps/api/src/services/ (project-data wrappers, connector execution/receipts, connector read settings, trigger status, final assistant message, agent activity), apps/api/src/routes/connector-mcp.ts (instructions), apps/api/src/routes/triggers/crud.ts (PATCH next fire), apps/api/src/db/migrations/0208_* + schema.ts, packages/shared/src/types/pull-requests.ts (optional fields).

Documentation & Specs

Updated apps/www/src/content/docs/docs/guides/sam-connector.md, apps/www/src/content/docs/docs/guides/admin-settings.md, apps/www/src/content/docs/docs/reference/api.md, .claude/skills/api-reference/SKILL.md. No specs/ edits (outside a spec context, rule 01).

Constitution & Risk Check

Principle XI: new limits are typed admin settings with code defaults (no env vars). Remaining constants are structural (DO page size inside a bounded scan, D1 bind chunking, response-cap share) and named. Principle X: one implementation per operation; REST and Connector share the schedule/trigger services. Risks: default sam_chat_read response shape change (mitigated by unit: "rows"); added DO scan work per read (bounded by connector.transcriptScanRows, disclosed in coverage); new write tools (task:write, session-writer checks, receipts, idempotency, start budget); attention visibility (writer-gated question text).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: raphaeltm/simple-agent-manager
• Branch: main
• File: .coderabbit.yaml
• Commit: 1d185cb
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: a9ededc8-4277-46cd-b837-e3f4ab6718c9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codspeed]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/implement-ship-all-existing-505new (8812ca7) with main (26c799e)¹}

Footnotes

1. No successful run was found on main (1d185cb) during the generation of this report, so 26c799e was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[raphaeltm]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[sonarqubecloud]

Quality Gate passed

Issues
29 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.4% Duplication on New Code

See analysis details on SonarQube Cloud