Source Map

This map explains where the major runtime responsibilities live in src/, which modules own trust boundaries, and which seams should be extracted next when new work exposes a clear owner. It is a contributor guide, not a claim that every module is already in its final shape.

Dependency Shape

The intended dependency direction is:

flowchart TD ui["api shell fragments"] api["api"] cli["cli"] orchestrator["orchestrator"] workflows["workflows"] runtime["task-runtime"] tools["tools"] connectors["connectors"] db["db"] workspace["workspace"] policy["policy"] trace["trace"] shared["shared contracts/types"] domains["planner, report-automation, knowledge, source-intake, sandbox-runner"] ui --> api api --> orchestrator cli --> orchestrator orchestrator --> workflows orchestrator --> runtime orchestrator --> tools orchestrator --> connectors orchestrator --> db orchestrator --> policy orchestrator --> trace workflows --> runtime workflows --> tools workflows --> workspace runtime --> tools runtime --> policy tools --> connectors tools --> workspace tools --> domains domains --> shared api --> shared orchestrator --> shared workflows --> shared runtime --> shared tools --> shared

shared/ is the contract layer. Runtime modules may import shared contracts and types, but shared code should not import runtime modules.

Directory Ownership

Runtime manifests and TypeScript source have different jobs:

src/skills/manifests/ contains built-in skill manifests. They sit beside the skill registry implementation so skills and tools have parallel source ownership under src/.
src/skills/index.ts owns the small loader/import registry for those manifests.
src/tools/ contains executable tool implementations. Tools are code because they cross runtime boundaries such as repo files, workspace artifacts, subprocesses, local browsers, OAuth connectors, and external APIs.
src/tools/index.ts is now the composition point and shared tool contract owner; tool families register from focused modules.

Directory	Owns	Should not own
`src/api/`	HTTP server, local browser boundary checks, request validation, dashboard shell serving, API-worker adapter.	Core run policy, approval decisions, workflow semantics, connector business logic.
`src/api/shell-js-fragments/` and `src/api/shell-css-fragments/`	Static dashboard fragments assembled into the local UI bundle.	Durable state mutation outside documented API calls.
`src/cli/`	Operator command surface and local runbook commands.	Separate business rules that diverge from API/orchestrator behavior.
`src/orchestrator/`	Run lifecycle, queue/job coordination, approval checkpoints, capability inventory, coordinator turns, service-level composition.	Tool implementation details, large domain-specific workflows, connector protocol handling.
`src/task-runtime/`	Per-task model/tool execution, runtime allowlist enforcement, policy evaluation, approval preflight, prompt envelope construction.	API routing, durable orchestration, workflow planning.
`src/tools/`	Tool registry composition, shared tool contracts, runtime isolation metadata, and focused built-in tool family modules.	Skill manifests, workflow templates, or connector account lifecycle.
`src/connectors/`	Connector catalogs, OAuth account/runtime plumbing, provider-specific connector support such as Apple Developer and Plaid.	Generic tool registry ownership or workflow orchestration.
`src/workflows/`	Workflow templates and stage executors for coding, research, provider smoke, single-agent, security, and workflow primitives.	Global API behavior, policy definitions, raw database migrations.
`src/workspace/`	Run workspace artifact filesystem operations and containment.	Repository mutation policy or approval logic.
`src/verifiers/`	Host command verifier boundary: argv command execution, env allowlist, timeout, output caps, process cleanup.	Docker sandbox command language or workflow-specific verifier interpretation.
`src/sandbox-runner/`	Container sandbox plans, Docker readiness, artifact collection, resource/network policy metadata.	Host verifier behavior.
`src/source-intake/`	Source acquisition, quarantine, manifest building, archive safety checks.	Workflow stage orchestration or report rendering.
`src/db/`	SQLite schema, migrations, persistence methods, transactional helpers.	Policy choices or UI read-model formatting.
`src/policy/`	Action type classification, risk levels, approval requirements, blocked high-risk classes.	Per-tool implementation details.
`src/trace/`	Trace event storage and event type constants.	Human approval decisions or notification read state.
`src/model-runtime/`	Model gateway adapters, provider credential resolution, bounded provider CLI environment integration.	Prompt assembly rules outside the runtime envelope.
`src/knowledge/`	Local knowledge store and optional backend adapters.	Planner source-specific semantics.
`src/planner/`	Planner source ingestion, artifact/task model, conflict logic, ask/search service.	General workflow execution and connector account lifecycle.
`src/report-automation/`	Report contracts, orchestration helpers, renderer, approval gates, measurements, email intake.	General coordinator/run state machine.
`src/quality-preflight/`	Preflight report generation for package/docs/test hygiene.	Workflow queueing.
`src/skills/`	Skill registry implementation plus built-in skill manifests under `src/skills/manifests/*.skill.json`.	Runtime tool execution.
`src/shared/`	Cross-module contracts, schemas, primitive types, filesystem helpers, IDs, time, subprocess env helpers.	Runtime imports or side effects.

Boundary Owners

Boundary	Primary owner	Supporting modules	Tests to look at
Local API browser mutation boundary	`src/api/server.ts`, `src/api/server-helpers.ts`	`src/api/config.ts`	`tests/api-browser-boundary.test.ts`, `tests/api-body-limits.test.ts`
Operator and headless-agent token scopes	`src/api/server-helpers.ts`	`src/shared/contracts.ts`, `src/shared/types.ts`	`tests/control-plane-api.test.ts`
Tool allowlists and runtime policy preflight	`src/task-runtime/index.ts`	`src/tools/index.ts`, `src/policy/index.ts`	`tests/runtime-policy-service.test.ts`, `tests/runtime-isolation-policy.test.ts`, `tests/oauth-connectors.test.ts`
Repo filesystem containment	`src/tools/repo-boundary.ts`, `src/tools/repo-tools.ts`	`src/tools/index.ts`, `src/workspace/index.ts`	`tests/verifier-bounds.test.ts`, `tests/workspace-containment.test.ts`
Workspace artifact containment	`src/workspace/index.ts`	`src/shared/fs.ts`	`tests/workspace-containment.test.ts`
Approval checkpoint creation and resume	`src/orchestrator/service.ts`	`src/task-runtime/index.ts`, `src/db/database.ts`	`tests/approval-checkpoints.test.ts`, `tests/run-lifecycle-service.test.ts`, `tests/transaction-boundaries.test.ts`
Repo-write patch bundle evidence	`src/workflows/coding-stage-executor.ts`, `src/workflows/single-agent-stage-executor.ts`	`src/shared/file-changes.ts`, `src/verifiers/index.ts`	`tests/coding-approval-verification.test.ts`, `tests/coding-stage-executor.test.ts`, `tests/single-agent-coding.test.ts`
Generic OAuth write approval previews	`src/connectors/oauth-api-tools.ts`, `src/task-runtime/index.ts`	`src/orchestrator/service.ts`, `src/workflows/primitives.ts`	`tests/oauth-connectors.test.ts`, `tests/runtime-policy-service.test.ts`, `tests/workflow-test-runs.test.ts`
Tool runtime isolation inventory	`src/tools/index.ts`, `src/orchestrator/service.ts`	`src/tools/-tools.ts`, `src/connectors/`, `src/sandbox-runner/index.ts`, `src/verifiers/index.ts`	`tests/runtime-policy-service.test.ts`, `tests/capability-inventory.test.ts`
Provider CLI environment	`src/model-runtime/index.ts`, `src/shared/subprocess-env.ts`	`src/connectors/oauth.ts` for credentials	`tests/model-provider-env.test.ts`, `tests/provider-smoke-env.test.ts`
Host verifier command execution	`src/verifiers/index.ts`	`src/tools/code-tools.ts`, `src/tools/repo-tools.ts`	`tests/verifier-bounds.test.ts`
Container sandbox execution	`src/sandbox-runner/index.ts`	`src/source-intake/index.ts`	`tests/sandbox-runner.test.ts`
Source intake quarantine	`src/source-intake/index.ts`	`src/shared/fs.ts`	`tests/source-intake.test.ts`, `tests/source-provider-expansion.test.ts`
Secrets and connector credential metadata	`src/orchestrator/service.ts`, `src/connectors/oauth.ts`	`src/tools/state.ts`, `src/connectors/*`	`tests/secret-registry-service.test.ts`, `tests/oauth-connectors.test.ts`, `tests/plaid-connectors.test.ts`
Capability lifecycle inventory	`src/orchestrator/service.ts`	`src/tools/index.ts`, `src/skills/index.ts`, `src/workflows/index.ts`	`tests/capability-inventory.test.ts`, `tests/connector-sdk.test.ts`
Report workflow public output	`src/report-automation/`	`src/workflows/*stage-executor.ts`	`tests/report-contracts.test.ts`, `tests/report-orchestration.test.ts`, `tests/report-approval-gates.test.ts`

Current Hotspots

These are not defects by themselves, but they are due-diligence flags for public readability and future extension work.

Module	Approximate size observed during this pass	Risk
`src/orchestrator/service.ts`	30k+ lines	Too many lifecycle, API read-model, approval, connector, workflow, and coordinator responsibilities in one file.
`src/tools/index.ts`	~400 lines	Improved: now mostly shared contracts and registry composition. Keep it that way; new tool code should live in a focused family module.
`src/workflows/single-agent-stage-executor.ts`	7k+ lines	Large workflow-specific runtime with repo-write, source-intake, QA, and agent behavior mixed together.
`src/db/database.ts`	5k+ lines	Persistence API and migration logic are centralized; transaction boundaries need careful review.
`src/shared/contracts.ts` and `src/shared/types.ts`	3k+ lines each	Contract sprawl can hide ownership and make generated/public schemas hard to reason about.
`src/api/server.ts`	3k+ lines	Route handling is still centralized even after helper extraction.
Dashboard fragments under `src/api/shell-js-fragments/dashboard/`	several large files, including `user-dashboard.ts`	UI behavior is modular by file but still large enough to make changes risky without focused tests.

Refactor Rules

Keep public contracts stable unless the PR explicitly changes a contract and updates tests/docs.
Move behavior behind existing tests before moving files.
Extract by boundary first, not by line count.
Keep tool permission, policy, approval, and filesystem checks close to their owning boundary.
Do not add a second implementation path in the new module; move the existing path and keep callers thin.
Update this map when a boundary owner changes.

For new tool families, follow the Tool Extension Lifecycle. For reusable workflow changes, follow the Workflow Extension Lifecycle.

Near-Term Extraction Targets

1. Tool Family Extraction

Status: mostly completed for the original monolithic src/tools/index.ts.

Completed tool family modules:

src/tools/agent-tools.ts
src/tools/apple-developer-tools.ts
src/tools/browser-capture-tools.ts
src/tools/code-tools.ts
src/tools/flow-data-tools.ts
src/tools/knowledge-tools.ts
src/tools/media-research-asset-tools.ts
src/tools/network-utility-tools.ts
src/tools/notification-email-tools.ts
src/tools/repo-tools.ts
src/tools/report-orchestration-tools.ts
src/tools/research-source-tools.ts
src/tools/security-tools.ts
src/tools/source-setup-tools.ts
src/tools/store-artifact-tools.ts
worker trigger tools under src/tools/
src/tools/web-citation-tools.ts

Rule: do not add new handler bodies to src/tools/index.ts; add or extend a family module and register it from createToolRegistry().

2. Repo Tools

Status: completed. Repo read/write/diff/check tool manifests and handlers now live in src/tools/repo-tools.ts, and realpath-aware repository containment lives in src/tools/repo-boundary.ts.

Why first:

Repo tools are a high-risk boundary.
Symlink and sibling-prefix tests already exist.
The module is a good example of extension-friendly tool ownership.

Current shape:

src/tools/repo-tools.ts
src/tools/repo-boundary.ts
exported registerRepoTools(registry)
no direct orchestrator dependency
tests continue to cover allowlist, path containment, symlink escapes, command verifier bounds, and approval-contextual writes

3. Generic OAuth Connector Tools

Completed shape: reusable OAuth api-read and api-request registration plus request handling live in a connector-owned module.

Why:

Generic request tools are advanced escape hatches and should be visibly owned by connector code.
Typed connector operations should become the preferred write surface.
Approval preview validation should remain available before runtime approval creation.

Shape:

src/connectors/oauth-api-tools.ts
explicit registration function for OAuth catalog-backed tools
shared preview validation before token lookup or network execution

4. Approval Checkpoint Handling

Target: extract approval evidence construction, checkpoint creation, idempotency checks, and resume/reject transitions from HarnessService.

Why:

Approval behavior is a trust boundary, not incidental orchestration plumbing.
It has broad impact across repo writes, external writes, delivery gates, and high-risk actions.
It will make future connector enablement checklists easier to enforce.

Expected shape:

src/orchestrator/approvals.ts
service delegates to a small approval service with database/trace dependencies
existing approval queue and transaction tests remain the behavioral gate

5. API Route Modules

Target: split src/api/server.ts by resource after route contract coverage is strong.

Suggested route groups:

runs/jobs/tasks/artifacts
conversations/coordinator
approvals/notifications/audit
workflows/automations/capabilities
settings/models/connectors/secrets
planner/research/report surfaces

6. Report And Planner Service Edges

Target: keep domain orchestration in src/report-automation/ and src/planner/, with HarnessService acting as a coordinator rather than a domain implementation host.

Why:

These domains have clear contracts and substantial dedicated tests.
They are extensibility surfaces, not core runtime state-machine code.

Test Ownership Map

Test file	Primary coverage
Focused coordinator, runtime, approval, and workflow suites under `tests/`	Former legacy harness coverage split by boundary and workflow ownership.
`tests/oauth-connectors.test.ts`	OAuth lifecycle, connector catalog defaults, OAuth request handling, typed connector helpers.
`tests/workspace-containment.test.ts`	Workspace path boundaries and symlink rejection.
`tests/verifier-bounds.test.ts`	Host command verifier boundaries.
`tests/sandbox-runner.test.ts`	Docker sandbox command/artifact/network/resource behavior.
`tests/source-intake.test.ts`	Source acquisition and quarantine safety.
`tests/workflow-test-runs.test.ts`	Workflow draft execution and workflow-agent tool defaults.
`tests/workflow-assets.test.ts` and `tests/primitive-tools.test.ts`	Workflow primitive catalog and primitive tool behavior.
`tests/api-browser-boundary.test.ts` and `tests/api-body-limits.test.ts`	Local API browser and request body safety.
`tests/transaction-boundaries.test.ts`, `tests/job-claiming.test.ts`, `tests/schema-migrations.test.ts`	Database transaction, queue, and migration behavior.
`tests/report-*.test.ts` and client-profile tests	Report automation contracts, orchestration, approvals, and output safety.
`tests/planner-*.test.ts`	Planner contracts, sources, retrieval, conflicts, tasks, and API behavior.

Contributor Checklist

Before changing a boundary-sensitive module, answer:

Which boundary does this touch: model, connector, filesystem, repo write, external write, secret, approval, API, sandbox, or database?
Which module owns that boundary today?
Which test proves the negative case?
Does a tool need all required allowlist tokens, or explicit alternatives?
Does an unsafe external write have approval evidence that matches the exact request?
Does a filesystem path use shared containment helpers instead of string-prefix checks?
Does a subprocess inherit only documented environment variables?
Does the public contract or audit packet shape change?

If the answer is unclear, update this map or the architecture docs before expanding the surface area.