From fd7b9c9e912187fb6bf7a2199bd1fefcc74236e9 Mon Sep 17 00:00:00 2001 From: Drew Stone Date: Thu, 2 Jul 2026 21:00:52 -0600 Subject: [PATCH] =?UTF-8?q?docs(api):=20zero=20own=20blank=20catalog=20row?= =?UTF-8?q?s=20=E2=80=94=20backfill=2075=20summaries,=20ratchet=20to=2034?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Backfill TSDoc one-line summaries on all ~75 own-section callables that were rendering blank in the primitive catalog: Root: createIterableBackend, createSandboxPromptBackend, DEFAULT_ROUTER_BASE_URL, DELEGATED_LOOP_MODES, isDelegatedLoopMode, notifyRuntimeHookEvent, notifyRuntimeDecisionPoint, sanitizeKnowledgeReadinessReport, sanitizeAgentRuntimeEvent, sanitizeRuntimeStreamEvent, createRuntimeEventCollector, readinessServerSentEvent, runtimeStreamServerSentEvent, sleep, CircuitOpenError, DeadlineExceededError, InMemoryConversationJournal, InMemoryRuntimeSessionStore, toolBuildPrompt, mcpBuildPrompt, mcpServeVerifier. /agent: createSurfaceKnowledgeAdapter, renderSurfaceIssues, AgentManifestError. /loops: createWaterfallCollector, defaultAuditorInstruction, defaultProfileRichnessThresholds. /profiles: coderTaskToPrompt, createInProcessUiAuditClient, createUiAuditorValidator, encodeAuditTaskEnvelope, formatAuditorPrompt, initAuditWorkspace, parseAuditorEvents, readAuditRegistry, summarizeRegistry, LENS_BRIEFS, SHARED_AUDITOR_RULES. /platform: PlatformAuthClient, PlatformAuthError, PlatformHubClient, PlatformHubError. /mcp: captureWorktreeDiff, createDelegateFeedbackHandler, createDelegateUiAuditHandler, createDelegationHistoryHandler, createDelegationStatusHandler, createDelegationTraceCollector, createWorktree, parseDetachedSessionRef, removeWorktree, validateDelegateArgs, validateDelegateFeedbackArgs, validateDelegateUiAuditArgs, validateDelegationHistoryArgs, validateDelegationStatusArgs, DELEGATE_DESCRIPTION, DELEGATE_FEEDBACK_DESCRIPTION, DELEGATE_FEEDBACK_INPUT_SCHEMA, DELEGATE_FEEDBACK_TOOL_NAME, DELEGATE_INPUT_SCHEMA, DELEGATE_TOOL_NAME, DELEGATE_UI_AUDIT_DESCRIPTION, DELEGATE_UI_AUDIT_INPUT_SCHEMA, DELEGATE_UI_AUDIT_TOOL_NAME, DELEGATION_HISTORY_DESCRIPTION, DELEGATION_HISTORY_INPUT_SCHEMA, DELEGATION_HISTORY_TOOL_NAME, DELEGATION_STATUS_DESCRIPTION, DELEGATION_STATUS_INPUT_SCHEMA, DELEGATION_STATUS_TOOL_NAME, DelegationTaskQueue, InMemoryDelegationStore, InMemoryFeedbackStore. Ratchet lowered from 108 → 34 (remaining blanks are all agent-eval re-exports where the source TSDoc lives in the substrate; 1 is AgentEvalError whose alias chain resolves into agent-eval). Regenerate docs/api/ to include new summaries and updated line-number citations. docs(arch): replace dated result stamp with ledger pointer; reconcile selector claim - architecture-interpretations.md §7: remove dated 'frozen-holdout tie, 2026-06-09' stamp; replace with qualitative pointer to .evolve/current.json + memory ledger. - architecture.md §7: replace 'faked with the oracle' sentence with one grounded in the built verifierGroundedSelect (bench/src/selector.ts:71); cite interpretations doc for evidence status; selector-is-never-the-judge law unchanged. --- docs/api/agent.md | 20 ++- docs/api/index.md | 118 ++++++++++----- docs/api/mcp.md | 64 +++++++- docs/api/platform.md | 72 ++++----- docs/api/primitive-catalog.md | 148 +++++++++---------- docs/api/profiles.md | 20 +++ docs/api/runtime.md | 46 +++--- docs/architecture-interpretations.md | 2 +- docs/architecture.md | 6 +- scripts/gen-primitive-catalog.mjs | 2 +- src/agent/define-agent.ts | 1 + src/agent/knowledge-adapter.ts | 1 + src/agent/surfaces.ts | 1 + src/audit/issue-writer.ts | 6 +- src/backends.ts | 4 +- src/conversation/call-policy.ts | 3 + src/conversation/journal.ts | 1 + src/improvement/build-prompts.ts | 2 + src/improvement/mcp-serve-verifier.ts | 1 + src/loop-runner.ts | 4 +- src/mcp/delegation-store.ts | 2 +- src/mcp/delegation-trace.ts | 2 +- src/mcp/detached-turn.ts | 2 +- src/mcp/feedback-store.ts | 2 +- src/mcp/task-queue.ts | 2 +- src/mcp/tools/delegate-feedback.ts | 10 +- src/mcp/tools/delegate-ui-audit.ts | 10 +- src/mcp/tools/delegate.ts | 8 +- src/mcp/tools/delegation-history.ts | 10 +- src/mcp/tools/delegation-status.ts | 10 +- src/mcp/worktree.ts | 6 +- src/model-resolution.ts | 1 + src/platform/auth.ts | 2 + src/platform/integrations.ts | 2 + src/profiles/coder.ts | 2 +- src/profiles/ui-auditor/in-process-client.ts | 2 +- src/profiles/ui-auditor/lens-prompts.ts | 4 +- src/profiles/ui-auditor/output-adapter.ts | 2 +- src/profiles/ui-auditor/prompt.ts | 4 +- src/profiles/ui-auditor/validator.ts | 2 +- src/runtime-hooks.ts | 2 + src/runtime/audit-intent.ts | 1 + src/runtime/supervise/authoring.ts | 1 + src/runtime/waterfall.ts | 1 + src/sanitize.ts | 8 +- src/sessions.ts | 2 +- src/sse.ts | 4 +- 47 files changed, 384 insertions(+), 242 deletions(-) diff --git a/docs/api/agent.md b/docs/api/agent.md index 940d8023..dd9dfe05 100644 --- a/docs/api/agent.md +++ b/docs/api/agent.md @@ -10,7 +10,9 @@ ### AgentManifestError -Defined in: [agent/define-agent.ts:308](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/define-agent.ts#L308) +Defined in: [agent/define-agent.ts:309](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/define-agent.ts#L309) + +Thrown when `defineAgent` finds a required surface missing on disk. #### Extends @@ -22,7 +24,7 @@ Defined in: [agent/define-agent.ts:308](https://github.com/tangle-network/agent- > **new AgentManifestError**(`message`, `agentId`, `issues?`): [`AgentManifestError`](#agentmanifesterror) -Defined in: [agent/define-agent.ts:309](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/define-agent.ts#L309) +Defined in: [agent/define-agent.ts:310](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/define-agent.ts#L310) ###### Parameters @@ -52,13 +54,13 @@ readonly `unknown`[] = `[]` > `readonly` **agentId**: `string` -Defined in: [agent/define-agent.ts:311](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/define-agent.ts#L311) +Defined in: [agent/define-agent.ts:312](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/define-agent.ts#L312) ##### issues > `readonly` **issues**: readonly `unknown`[] = `[]` -Defined in: [agent/define-agent.ts:312](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/define-agent.ts#L312) +Defined in: [agent/define-agent.ts:313](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/define-agent.ts#L313) ## Interfaces @@ -1528,7 +1530,7 @@ directly in the chat surface. > **defineAgent**\<`TPersona`, `TRunOutput`\>(`manifest`): [`AgentManifest`](#agentmanifest)\<`TPersona`, `TRunOutput`\> -Defined in: [agent/define-agent.ts:332](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/define-agent.ts#L332) +Defined in: [agent/define-agent.ts:333](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/define-agent.ts#L333) Construct a validated agent manifest. Throws `AgentManifestError` if any required surface is missing on disk. @@ -1588,7 +1590,9 @@ The substrate-default `ImprovementAdapter`: resolve each finding's subject to a > **createSurfaceKnowledgeAdapter**\<`TProposal`\>(`opts`, `deps`): [`KnowledgeAdapter`](analyst-loop.md#knowledgeadapter)\<`TProposal`\> -Defined in: [agent/knowledge-adapter.ts:58](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/knowledge-adapter.ts#L58) +Defined in: [agent/knowledge-adapter.ts:59](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/knowledge-adapter.ts#L59) + +Wire a surface-based `KnowledgeAdapter` that writes analyst proposals to agent surface files. #### Type Parameters @@ -1755,7 +1759,9 @@ readonly [`SurfaceValidationIssue`](#surfacevalidationissue)[] > **renderSurfaceIssues**(`issues`, `repoRoot`): `string` -Defined in: [agent/surfaces.ts:246](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/surfaces.ts#L246) +Defined in: [agent/surfaces.ts:247](https://github.com/tangle-network/agent-runtime/blob/main/src/agent/surfaces.ts#L247) + +Format a list of surface validation issues into a human-readable error string. #### Parameters diff --git a/docs/api/index.md b/docs/api/index.md index 8023d070..12086132 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -10,7 +10,9 @@ ### CircuitOpenError -Defined in: [conversation/call-policy.ts:42](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L42) +Defined in: [conversation/call-policy.ts:43](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L43) + +Thrown when the circuit breaker is open for a participant and no retry is allowed yet. #### Extends @@ -22,7 +24,7 @@ Defined in: [conversation/call-policy.ts:42](https://github.com/tangle-network/a > **new CircuitOpenError**(`participant`, `retryAfterMs`): [`CircuitOpenError`](#circuitopenerror) -Defined in: [conversation/call-policy.ts:43](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L43) +Defined in: [conversation/call-policy.ts:44](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L44) ###### Parameters @@ -46,7 +48,9 @@ Defined in: [conversation/call-policy.ts:43](https://github.com/tangle-network/a ### DeadlineExceededError -Defined in: [conversation/call-policy.ts:51](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L51) +Defined in: [conversation/call-policy.ts:53](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L53) + +Thrown when a backend call exceeds its per-attempt deadline. #### Extends @@ -58,7 +62,7 @@ Defined in: [conversation/call-policy.ts:51](https://github.com/tangle-network/a > **new DeadlineExceededError**(`deadlineMs`): [`DeadlineExceededError`](#deadlineexceedederror) -Defined in: [conversation/call-policy.ts:52](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L52) +Defined in: [conversation/call-policy.ts:54](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L54) ###### Parameters @@ -78,7 +82,7 @@ Defined in: [conversation/call-policy.ts:52](https://github.com/tangle-network/a ### CircuitBreakerState -Defined in: [conversation/call-policy.ts:84](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L84) +Defined in: [conversation/call-policy.ts:86](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L86) Live circuit-breaker state — one instance per (participant, conversation run). @@ -88,7 +92,7 @@ Live circuit-breaker state — one instance per (participant, conversation run). > **new CircuitBreakerState**(`config`): [`CircuitBreakerState`](#circuitbreakerstate) -Defined in: [conversation/call-policy.ts:88](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L88) +Defined in: [conversation/call-policy.ts:90](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L90) ###### Parameters @@ -106,7 +110,7 @@ Defined in: [conversation/call-policy.ts:88](https://github.com/tangle-network/a > **preflight**(`participant`, `now?`): `void` -Defined in: [conversation/call-policy.ts:94](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L94) +Defined in: [conversation/call-policy.ts:96](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L96) Check whether the next call is allowed. Throws `CircuitOpenError` when the breaker is open and the cooldown hasn't elapsed. @@ -129,7 +133,7 @@ the breaker is open and the cooldown hasn't elapsed. > **recordSuccess**(): `void` -Defined in: [conversation/call-policy.ts:104](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L104) +Defined in: [conversation/call-policy.ts:106](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L106) ###### Returns @@ -139,7 +143,7 @@ Defined in: [conversation/call-policy.ts:104](https://github.com/tangle-network/ > **recordFailure**(`now?`): `void` -Defined in: [conversation/call-policy.ts:109](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L109) +Defined in: [conversation/call-policy.ts:111](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L111) ###### Parameters @@ -325,7 +329,9 @@ is observed-final; subsequent `loadRun` returns the same halt. ### InMemoryConversationJournal -Defined in: [conversation/journal.ts:59](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L59) +Defined in: [conversation/journal.ts:60](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L60) + +In-memory `ConversationJournal` — suitable for testing and single-process runs. #### Implements @@ -347,7 +353,7 @@ Defined in: [conversation/journal.ts:59](https://github.com/tangle-network/agent > **loadRun**(`runId`): `Promise`\<[`ConversationJournalEntry`](#conversationjournalentry) \| `undefined`\> -Defined in: [conversation/journal.ts:62](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L62) +Defined in: [conversation/journal.ts:63](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L63) Load any prior state for `runId`. Returns `undefined` for a fresh run. Implementations MUST NOT mutate the returned object — the runner clones @@ -372,7 +378,7 @@ identically, so a journal with zero turns is equivalent to "fresh." > **beginRun**(`runId`, `startedAt`): `Promise`\<`void`\> -Defined in: [conversation/journal.ts:75](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L75) +Defined in: [conversation/journal.ts:76](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L76) Initialise journal state for a fresh run. Called once per run, before any `appendTurn`. Idempotent: calling with an existing runId is a no-op if @@ -400,7 +406,7 @@ the entry already exists with the same `startedAt`. > **appendTurn**(`runId`, `turn`): `Promise`\<`void`\> -Defined in: [conversation/journal.ts:88](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L88) +Defined in: [conversation/journal.ts:89](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L89) Append a committed turn. The runner only calls this AFTER the turn's backend stream completed and the credit total has been updated, so an @@ -428,7 +434,7 @@ appended turn is observed-committed and never speculative. > **recordHalt**(`runId`, `halt`, `endedAt`): `Promise`\<`void`\> -Defined in: [conversation/journal.ts:103](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L103) +Defined in: [conversation/journal.ts:104](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L104) Record the run's terminal halt reason + end time. Once called, the run is observed-final; subsequent `loadRun` returns the same halt. @@ -459,7 +465,7 @@ is observed-final; subsequent `loadRun` returns the same halt. ### FileConversationJournal -Defined in: [conversation/journal.ts:123](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L123) +Defined in: [conversation/journal.ts:124](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L124) JSONL on disk. One line per record; first line is the `begin`, subsequent lines are `turn` records, terminal line is `halt`. Replays the whole file @@ -480,7 +486,7 @@ process crash between writes never loses an acknowledged turn. > **new FileConversationJournal**(`path`): [`FileConversationJournal`](#fileconversationjournal) -Defined in: [conversation/journal.ts:124](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L124) +Defined in: [conversation/journal.ts:125](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L125) ###### Parameters @@ -498,7 +504,7 @@ Defined in: [conversation/journal.ts:124](https://github.com/tangle-network/agen > **loadRun**(`runId`): `Promise`\<[`ConversationJournalEntry`](#conversationjournalentry) \| `undefined`\> -Defined in: [conversation/journal.ts:126](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L126) +Defined in: [conversation/journal.ts:127](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L127) Load any prior state for `runId`. Returns `undefined` for a fresh run. Implementations MUST NOT mutate the returned object — the runner clones @@ -523,7 +529,7 @@ identically, so a journal with zero turns is equivalent to "fresh." > **beginRun**(`runId`, `startedAt`): `Promise`\<`void`\> -Defined in: [conversation/journal.ts:162](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L162) +Defined in: [conversation/journal.ts:163](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L163) Initialise journal state for a fresh run. Called once per run, before any `appendTurn`. Idempotent: calling with an existing runId is a no-op if @@ -551,7 +557,7 @@ the entry already exists with the same `startedAt`. > **appendTurn**(`runId`, `turn`): `Promise`\<`void`\> -Defined in: [conversation/journal.ts:175](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L175) +Defined in: [conversation/journal.ts:176](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L176) Append a committed turn. The runner only calls this AFTER the turn's backend stream completed and the credit total has been updated, so an @@ -579,7 +585,7 @@ appended turn is observed-committed and never speculative. > **recordHalt**(`runId`, `halt`, `endedAt`): `Promise`\<`void`\> -Defined in: [conversation/journal.ts:179](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L179) +Defined in: [conversation/journal.ts:180](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/journal.ts#L180) Record the run's terminal halt reason + end time. Once called, the run is observed-final; subsequent `loadRun` returns the same halt. @@ -785,6 +791,8 @@ Defined in: [errors.ts:117](https://github.com/tangle-network/agent-runtime/blob Defined in: [sessions.ts:41](https://github.com/tangle-network/agent-runtime/blob/main/src/sessions.ts#L41) +In-memory `RuntimeSessionStore` for single-process use and tests. + #### Stable #### Implements @@ -3346,7 +3354,7 @@ Defined in: [model-resolution.ts:39](https://github.com/tangle-network/agent-run ### ResolvedChatModel -Defined in: [model-resolution.ts:79](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L79) +Defined in: [model-resolution.ts:80](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L80) #### Properties @@ -3354,13 +3362,13 @@ Defined in: [model-resolution.ts:79](https://github.com/tangle-network/agent-run > **source**: `string` -Defined in: [model-resolution.ts:80](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L80) +Defined in: [model-resolution.ts:81](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L81) ##### model > **model**: `string` -Defined in: [model-resolution.ts:81](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L81) +Defined in: [model-resolution.ts:82](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L82) *** @@ -6786,7 +6794,7 @@ MUST map this to `RunRecord.error` rather than recording silent > `const` **defaultIsRetryable**: [`RetryableErrorPredicate`](#retryableerrorpredicate) -Defined in: [conversation/call-policy.ts:63](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L63) +Defined in: [conversation/call-policy.ts:65](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L65) Default retryable classification — network/timeout class errors. Errors a model deliberately throws (validation, refusal, 4xx) are not retried; @@ -6860,7 +6868,7 @@ Defined in: [loop-runner.ts:47](https://github.com/tangle-network/agent-runtime/ **`Experimental`** -Every delegated-loop mode, for validation + CLI surfaces. +All valid delegated-loop mode names — used for validation and CLI surfaces. *** @@ -6868,7 +6876,9 @@ Every delegated-loop mode, for validation + CLI surfaces. > `const` **DEFAULT\_ROUTER\_BASE\_URL**: `"https://router.tangle.tools"` = `'https://router.tangle.tools'` -Defined in: [model-resolution.ts:42](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L42) +Defined in: [model-resolution.ts:43](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L43) + +Default Tangle Router base URL used when no env override is set. *** @@ -6888,6 +6898,8 @@ Wire version the eval-runs ingest enforces (X-Tangle-Wire-Version + body). Defined in: [backends.ts:30](https://github.com/tangle-network/agent-runtime/blob/main/src/backends.ts#L30) +Wrap any custom async-iterable stream into a typed `AgentExecutionBackend`. + #### Type Parameters ##### TInput @@ -6932,6 +6944,8 @@ Defined in: [backends.ts:30](https://github.com/tangle-network/agent-runtime/blo Defined in: [backends.ts:41](https://github.com/tangle-network/agent-runtime/blob/main/src/backends.ts#L41) +Build an `AgentExecutionBackend` backed by a sandbox/sidecar `streamPrompt` call. + #### Type Parameters ##### TBox @@ -7077,7 +7091,7 @@ OpenAI Chat Completions `response_format`. Omit for provider default text. > **makePerAttemptSignal**(`parentSignal`, `deadlineMs`): `object` -Defined in: [conversation/call-policy.ts:127](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L127) +Defined in: [conversation/call-policy.ts:129](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L129) Build a per-attempt AbortSignal linked to the parent signal AND fired when the deadline elapses. The returned `dispose()` MUST be called in a @@ -7127,7 +7141,7 @@ the underlying operation throws. > **computeBackoff**(`spec`, `attempt`): `number` -Defined in: [conversation/call-policy.ts:167](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L167) +Defined in: [conversation/call-policy.ts:169](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L169) Compute the delay before the next attempt. Default: 250ms exponential with jitter. @@ -7151,7 +7165,9 @@ Compute the delay before the next attempt. Default: 250ms exponential with jitte > **sleep**(`ms`): `Promise`\<`void`\> -Defined in: [conversation/call-policy.ts:177](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L177) +Defined in: [conversation/call-policy.ts:180](https://github.com/tangle-network/agent-runtime/blob/main/src/conversation/call-policy.ts#L180) + +Resolve after `ms` milliseconds — used for retry backoff in conversation call policy. #### Parameters @@ -7613,7 +7629,9 @@ A `Verifier` that runs a command in the worktree: exit 0 ⇒ ok, any other > **toolBuildPrompt**(`args`): `string` -Defined in: [improvement/build-prompts.ts:30](https://github.com/tangle-network/agent-runtime/blob/main/src/improvement/build-prompts.ts#L30) +Defined in: [improvement/build-prompts.ts:31](https://github.com/tangle-network/agent-runtime/blob/main/src/improvement/build-prompts.ts#L31) + +Build the starting instruction for a coder agent tasked with implementing a new tool. #### Parameters @@ -7631,7 +7649,9 @@ Defined in: [improvement/build-prompts.ts:30](https://github.com/tangle-network/ > **mcpBuildPrompt**(`args`): `string` -Defined in: [improvement/build-prompts.ts:43](https://github.com/tangle-network/agent-runtime/blob/main/src/improvement/build-prompts.ts#L43) +Defined in: [improvement/build-prompts.ts:45](https://github.com/tangle-network/agent-runtime/blob/main/src/improvement/build-prompts.ts#L45) + +Build the starting instruction for a coder agent tasked with implementing a new MCP server. #### Parameters @@ -7721,7 +7741,9 @@ The one reflective/agentic improvement proposer (`SurfaceProposer`): owns the ca > **mcpServeVerifier**(`spec`): [`Verifier`](#verifier) -Defined in: [improvement/mcp-serve-verifier.ts:43](https://github.com/tangle-network/agent-runtime/blob/main/src/improvement/mcp-serve-verifier.ts#L43) +Defined in: [improvement/mcp-serve-verifier.ts:44](https://github.com/tangle-network/agent-runtime/blob/main/src/improvement/mcp-serve-verifier.ts#L44) + +Build a `Verifier` that boots a generated MCP server over stdio and checks it exposes tools. #### Parameters @@ -7763,7 +7785,7 @@ Defined in: [loop-runner.ts:53](https://github.com/tangle-network/agent-runtime/ **`Experimental`** -Type guard for an untrusted mode string (CLI / config input). +Type guard — returns true when `value` is a valid `DelegatedLoopMode` string. #### Parameters @@ -7984,7 +8006,7 @@ readonly `string`[] > **resolveRouterBaseUrl**(`env?`): `string` -Defined in: [model-resolution.ts:45](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L45) +Defined in: [model-resolution.ts:46](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L46) Resolve the router base URL from env, normalised — no trailing `/v1` or `/`. @@ -8004,7 +8026,7 @@ Resolve the router base URL from env, normalised — no trailing `/v1` or `/`. > **getModels**(`routerBaseUrl?`): `Promise`\<[`ModelInfo`](#modelinfo)[]\> -Defined in: [model-resolution.ts:55](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L55) +Defined in: [model-resolution.ts:56](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L56) Fetch the model catalog from the router's `/v1/models`. Throws on a non-2xx response — callers decide whether to fail open (empty catalog) or closed. @@ -8025,7 +8047,7 @@ response — callers decide whether to fail open (empty catalog) or closed. > **cleanModelId**(`value`): `string` \| `undefined` -Defined in: [model-resolution.ts:67](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L67) +Defined in: [model-resolution.ts:68](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L68) Trim a candidate model id; `undefined` for non-strings and blanks. @@ -8045,7 +8067,7 @@ Trim a candidate model id; `undefined` for non-strings and blanks. > **resolveChatModel**(`candidates`, `fallback`): [`ResolvedChatModel`](#resolvedchatmodel) -Defined in: [model-resolution.ts:90](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L90) +Defined in: [model-resolution.ts:91](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L91) Resolve a chat model by precedence: the first candidate carrying a non-blank model wins, else `fallback`. The caller owns the precedence @@ -8072,7 +8094,7 @@ etc.) while the first-non-blank logic and the telemetry shape stay shared. > **validateChatModelId**(`modelId`, `options?`): `Promise`\<`ChatModelValidation`\> -Defined in: [model-resolution.ts:130](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L130) +Defined in: [model-resolution.ts:131](https://github.com/tangle-network/agent-runtime/blob/main/src/model-resolution.ts#L131) Validate a caller-supplied chat-model id. Rejects non-strings, malformed ids, and ids absent from both the caller's `allowlist` and the live router @@ -8441,7 +8463,9 @@ event. Use this to attach N observers to a loop instead of a second event bus. > **notifyRuntimeHookEvent**(`hooks`, `event`, `context?`): `void` -Defined in: [runtime-hooks.ts:157](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime-hooks.ts#L157) +Defined in: [runtime-hooks.ts:158](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime-hooks.ts#L158) + +Fire `hooks.onEvent`, swallowing sync throws and surfacing async failures to `onError`. #### Parameters @@ -8467,7 +8491,9 @@ Defined in: [runtime-hooks.ts:157](https://github.com/tangle-network/agent-runti > **notifyRuntimeDecisionPoint**(`hooks`, `point`, `context?`): `void` -Defined in: [runtime-hooks.ts:187](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime-hooks.ts#L187) +Defined in: [runtime-hooks.ts:189](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime-hooks.ts#L189) + +Fire `hooks.onDecisionPoint`, swallowing sync throws and surfacing async failures to `onError`. #### Parameters @@ -8518,6 +8544,8 @@ lifetime; consumers should not share it across requests. Defined in: [sanitize.ts:82](https://github.com/tangle-network/agent-runtime/blob/main/src/sanitize.ts#L82) +Strip PII and large blobs from a `KnowledgeReadinessReport` for safe telemetry emission. + #### Parameters ##### report @@ -8542,6 +8570,8 @@ Defined in: [sanitize.ts:82](https://github.com/tangle-network/agent-runtime/blo Defined in: [sanitize.ts:105](https://github.com/tangle-network/agent-runtime/blob/main/src/sanitize.ts#L105) +Reduce an `AgentRuntimeEvent` to a PII-safe, serializable plain object for telemetry. + #### Type Parameters ##### TState @@ -8584,6 +8614,8 @@ Defined in: [sanitize.ts:105](https://github.com/tangle-network/agent-runtime/bl Defined in: [sanitize.ts:161](https://github.com/tangle-network/agent-runtime/blob/main/src/sanitize.ts#L161) +Reduce a `RuntimeStreamEvent` to a PII-safe, serializable plain object for telemetry. + #### Parameters ##### event @@ -8608,6 +8640,8 @@ Defined in: [sanitize.ts:161](https://github.com/tangle-network/agent-runtime/bl Defined in: [sanitize.ts:531](https://github.com/tangle-network/agent-runtime/blob/main/src/sanitize.ts#L531) +Build an in-memory collector that sanitizes and accumulates `AgentRuntimeEvent`s for inspection. + #### Type Parameters ##### TState @@ -8673,6 +8707,8 @@ on `type` alone would misroute events. Defined in: [sse.ts:42](https://github.com/tangle-network/agent-runtime/blob/main/src/sse.ts#L42) +Serialize a `KnowledgeReadinessReport` as a Server-Sent Event string. + #### Parameters ##### report @@ -8697,6 +8733,8 @@ Defined in: [sse.ts:42](https://github.com/tangle-network/agent-runtime/blob/mai Defined in: [sse.ts:57](https://github.com/tangle-network/agent-runtime/blob/main/src/sse.ts#L57) +Serialize a `RuntimeStreamEvent` as a Server-Sent Event string. + #### Parameters ##### event diff --git a/docs/api/mcp.md b/docs/api/mcp.md index bdf6494b..fe37c583 100644 --- a/docs/api/mcp.md +++ b/docs/api/mcp.md @@ -110,6 +110,8 @@ Defined in: [mcp/delegation-store.ts:76](https://github.com/tangle-network/agent **`Experimental`** +In-memory `DelegationStore` — suitable for single-process use and tests. + #### Implements - [`DelegationStore`](#delegationstore) @@ -372,6 +374,8 @@ Defined in: [mcp/feedback-store.ts:42](https://github.com/tangle-network/agent-r **`Experimental`** +In-memory `FeedbackStore` — suitable for single-process use and tests. + #### Implements - [`FeedbackStore`](#feedbackstore) @@ -453,6 +457,8 @@ Defined in: [mcp/task-queue.ts:243](https://github.com/tangle-network/agent-runt **`Experimental`** +In-process queue for async delegation tasks — submit, cancel, poll status, and read history. + #### Constructors ##### Constructor @@ -5930,6 +5936,8 @@ Defined in: [mcp/tools/delegate-feedback.ts:25](https://github.com/tangle-networ **`Experimental`** +MCP tool name for the `delegate_feedback` feedback-recording tool. + *** ### DELEGATE\_FEEDBACK\_DESCRIPTION @@ -5940,6 +5948,8 @@ Defined in: [mcp/tools/delegate-feedback.ts:28](https://github.com/tangle-networ **`Experimental`** +Human-readable description of the `delegate_feedback` MCP tool, injected into the tool manifest. + *** ### DELEGATE\_FEEDBACK\_INPUT\_SCHEMA @@ -5950,6 +5960,8 @@ Defined in: [mcp/tools/delegate-feedback.ts:52](https://github.com/tangle-networ **`Experimental`** +JSON Schema for `delegate_feedback` tool arguments (`refersTo`, `rating`, `by`, optional fields). + #### Type Declaration ##### type @@ -6102,6 +6114,8 @@ Defined in: [mcp/tools/delegate-ui-audit.ts:30](https://github.com/tangle-networ **`Experimental`** +MCP tool name for the `delegate_ui_audit` async kickoff tool. + *** ### DELEGATE\_UI\_AUDIT\_DESCRIPTION @@ -6112,6 +6126,8 @@ Defined in: [mcp/tools/delegate-ui-audit.ts:33](https://github.com/tangle-networ **`Experimental`** +Human-readable description of the `delegate_ui_audit` MCP tool, injected into the tool manifest. + *** ### DELEGATE\_UI\_AUDIT\_INPUT\_SCHEMA @@ -6122,6 +6138,8 @@ Defined in: [mcp/tools/delegate-ui-audit.ts:86](https://github.com/tangle-networ **`Experimental`** +JSON Schema for `delegate_ui_audit` tool arguments (`workspaceDir`, `routes`, optional config). + #### Type Declaration ##### type @@ -6378,6 +6396,8 @@ Defined in: [mcp/tools/delegate.ts:26](https://github.com/tangle-network/agent-r **`Experimental`** +MCP tool name for the `delegate` generic-delegation tool. + *** ### DELEGATE\_DESCRIPTION @@ -6388,6 +6408,8 @@ Defined in: [mcp/tools/delegate.ts:29](https://github.com/tangle-network/agent-r **`Experimental`** +Human-readable description of the `delegate` MCP tool, injected into the tool manifest. + *** ### DELEGATE\_INPUT\_SCHEMA @@ -6398,6 +6420,8 @@ Defined in: [mcp/tools/delegate.ts:47](https://github.com/tangle-network/agent-r **`Experimental`** +JSON Schema for `delegate` tool arguments (`intent` + optional `model` and `runId`). + #### Type Declaration ##### type @@ -6462,6 +6486,8 @@ Defined in: [mcp/tools/delegation-history.ts:18](https://github.com/tangle-netwo **`Experimental`** +MCP tool name for the `delegation_history` read-past-delegations tool. + *** ### DELEGATION\_HISTORY\_DESCRIPTION @@ -6472,6 +6498,8 @@ Defined in: [mcp/tools/delegation-history.ts:21](https://github.com/tangle-netwo **`Experimental`** +Human-readable description of the `delegation_history` MCP tool, injected into the tool manifest. + *** ### DELEGATION\_HISTORY\_INPUT\_SCHEMA @@ -6482,6 +6510,8 @@ Defined in: [mcp/tools/delegation-history.ts:42](https://github.com/tangle-netwo **`Experimental`** +JSON Schema for `delegation_history` tool arguments (optional `namespace`, `profile`, `since`, `limit`). + #### Type Declaration ##### type @@ -6554,6 +6584,8 @@ Defined in: [mcp/tools/delegation-status.ts:17](https://github.com/tangle-networ **`Experimental`** +MCP tool name for the `delegation_status` synchronous-poll tool. + *** ### DELEGATION\_STATUS\_DESCRIPTION @@ -6564,6 +6596,8 @@ Defined in: [mcp/tools/delegation-status.ts:20](https://github.com/tangle-networ **`Experimental`** +Human-readable description of the `delegation_status` MCP tool, injected into the tool manifest. + *** ### DELEGATION\_STATUS\_INPUT\_SCHEMA @@ -6574,6 +6608,8 @@ Defined in: [mcp/tools/delegation-status.ts:42](https://github.com/tangle-networ **`Experimental`** +JSON Schema for `delegation_status` tool arguments (`taskId` + optional `includeTrace`). + #### Type Declaration ##### type @@ -6807,6 +6843,8 @@ Defined in: [mcp/delegation-trace.ts:131](https://github.com/tangle-network/agen **`Experimental`** +Build a `DelegationTraceCollector` that buffers loop-trace events and converts them to spans on settle. + #### Parameters ##### onSpans @@ -6876,7 +6914,7 @@ Defined in: [mcp/detached-turn.ts:104](https://github.com/tangle-network/agent-r **`Experimental`** -Inverse of [formatDetachedSessionRef](#formatdetachedsessionref); throws `ValidationError` on malformed input. +Parse a `detachedSessionRef` string back to parts; throws `ValidationError` on malformed input. #### Parameters @@ -7377,6 +7415,8 @@ Defined in: [mcp/tools/delegate-feedback.ts:83](https://github.com/tangle-networ **`Experimental`** +Parse and validate raw MCP tool input into typed `DelegateFeedbackArgs`; throws `TypeError` on bad input. + #### Parameters ##### raw @@ -7397,6 +7437,8 @@ Defined in: [mcp/tools/delegate-feedback.ts:160](https://github.com/tangle-netwo **`Experimental`** +Build the MCP tool handler that persists feedback events and attaches them to delegation records. + #### Parameters ##### options @@ -7417,6 +7459,8 @@ Defined in: [mcp/tools/delegate-ui-audit.ts:114](https://github.com/tangle-netwo **`Experimental`** +Parse and validate raw MCP tool input into typed `DelegateUiAuditArgs`; throws `TypeError` on bad input. + #### Parameters ##### raw @@ -7437,6 +7481,8 @@ Defined in: [mcp/tools/delegate-ui-audit.ts:300](https://github.com/tangle-netwo **`Experimental`** +Build the MCP tool handler that validates input, deduplicates via idempotency key, and enqueues a UI audit. + #### Parameters ##### options @@ -7457,6 +7503,8 @@ Defined in: [mcp/tools/delegate.ts:75](https://github.com/tangle-network/agent-r **`Experimental`** +Parse and validate raw MCP tool input into typed `DelegateArgs`; throws `TypeError` on bad input. + #### Parameters ##### raw @@ -7499,6 +7547,8 @@ Defined in: [mcp/tools/delegation-history.ts:54](https://github.com/tangle-netwo **`Experimental`** +Parse and validate raw MCP tool input into typed `DelegationHistoryArgs`; throws `TypeError` on bad input. + #### Parameters ##### raw @@ -7519,6 +7569,8 @@ Defined in: [mcp/tools/delegation-history.ts:95](https://github.com/tangle-netwo **`Experimental`** +Build the MCP tool handler that reads filtered past delegations from a `DelegationTaskQueue`. + #### Parameters ##### options @@ -7539,6 +7591,8 @@ Defined in: [mcp/tools/delegation-status.ts:57](https://github.com/tangle-networ **`Experimental`** +Parse and validate raw MCP tool input into typed `DelegationStatusArgs`; throws `TypeError` on bad input. + #### Parameters ##### raw @@ -7559,6 +7613,8 @@ Defined in: [mcp/tools/delegation-status.ts:82](https://github.com/tangle-networ **`Experimental`** +Build the MCP tool handler that polls a `DelegationTaskQueue` for task status. + #### Parameters ##### options @@ -7651,6 +7707,8 @@ Defined in: [mcp/worktree.ts:114](https://github.com/tangle-network/agent-runtim **`Experimental`** +Checkout a fresh git worktree for a delegation run on a new branch under `variantsDir`. + #### Parameters ##### options @@ -7671,6 +7729,8 @@ Defined in: [mcp/worktree.ts:134](https://github.com/tangle-network/agent-runtim **`Experimental`** +Stage all changes in a worktree and return the diff patch + shortstat against the base ref. + #### Parameters ##### options @@ -7691,6 +7751,8 @@ Defined in: [mcp/worktree.ts:174](https://github.com/tangle-network/agent-runtim **`Experimental`** +Remove a git worktree and delete its branch; tolerates already-removed paths. + #### Parameters ##### options diff --git a/docs/api/platform.md b/docs/api/platform.md index 1c96c934..5808f06a 100644 --- a/docs/api/platform.md +++ b/docs/api/platform.md @@ -10,16 +10,9 @@ ### PlatformAuthError -Defined in: [platform/auth.ts:50](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L50) - -`@tangle-network/agent-runtime/platform` — typed server-side clients -for the Tangle platform's cross-site SSO bridge and integrations -hub. Apps consume these to avoid rolling their own OAuth, session, -and connection storage. +Defined in: [platform/auth.ts:51](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L51) -See: - - [PlatformAuthClient](#platformauthclient) for "Login with Tangle" - - [PlatformHubClient](#platformhubclient) for the `/v1/hub/*` surface +Thrown when a `PlatformAuthClient` request returns a non-success status. #### Extends @@ -31,7 +24,7 @@ See: > **new PlatformAuthError**(`message`, `status`, `body`): [`PlatformAuthError`](#platformautherror) -Defined in: [platform/auth.ts:51](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L51) +Defined in: [platform/auth.ts:52](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L52) ###### Parameters @@ -61,28 +54,21 @@ Defined in: [platform/auth.ts:51](https://github.com/tangle-network/agent-runtim > `readonly` **status**: `number` -Defined in: [platform/auth.ts:53](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L53) +Defined in: [platform/auth.ts:54](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L54) ##### body > `readonly` **body**: `unknown` -Defined in: [platform/auth.ts:54](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L54) +Defined in: [platform/auth.ts:55](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L55) *** ### PlatformAuthClient -Defined in: [platform/auth.ts:61](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L61) - -`@tangle-network/agent-runtime/platform` — typed server-side clients -for the Tangle platform's cross-site SSO bridge and integrations -hub. Apps consume these to avoid rolling their own OAuth, session, -and connection storage. +Defined in: [platform/auth.ts:63](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L63) -See: - - [PlatformAuthClient](#platformauthclient) for "Login with Tangle" - - [PlatformHubClient](#platformhubclient) for the `/v1/hub/*` surface +HTTP client for the Tangle Platform SSO: builds authorize URLs and exchanges auth codes for API keys. #### Constructors @@ -90,7 +76,7 @@ See: > **new PlatformAuthClient**(`options`): [`PlatformAuthClient`](#platformauthclient) -Defined in: [platform/auth.ts:66](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L66) +Defined in: [platform/auth.ts:68](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L68) ###### Parameters @@ -108,7 +94,7 @@ Defined in: [platform/auth.ts:66](https://github.com/tangle-network/agent-runtim > **authorizeUrl**(`options`): `string` -Defined in: [platform/auth.ts:81](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L81) +Defined in: [platform/auth.ts:83](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L83) Build the URL the user is redirected to in order to start SSO. The platform redirects back to one of `appId`'s registered @@ -128,7 +114,7 @@ The platform redirects back to one of `appId`'s registered > **exchange**(`code`): `Promise`\<[`ExchangeCodeResult`](#exchangecoderesult)\> -Defined in: [platform/auth.ts:99](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L99) +Defined in: [platform/auth.ts:101](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/auth.ts#L101) Exchange a single-use auth code (delivered to the consumer's callback by the platform) for an API key + the user's identity. @@ -148,7 +134,9 @@ Codes are single-use and expire ~5 minutes after issue. ### PlatformHubError -Defined in: [platform/integrations.ts:132](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L132) +Defined in: [platform/integrations.ts:133](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L133) + +Thrown when a `PlatformHubClient` request returns a non-success status. #### Extends @@ -160,7 +148,7 @@ Defined in: [platform/integrations.ts:132](https://github.com/tangle-network/age > **new PlatformHubError**(`message`, `status`, `code`, `body`): [`PlatformHubError`](#platformhuberror) -Defined in: [platform/integrations.ts:133](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L133) +Defined in: [platform/integrations.ts:134](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L134) ###### Parameters @@ -194,25 +182,27 @@ Defined in: [platform/integrations.ts:133](https://github.com/tangle-network/age > `readonly` **status**: `number` -Defined in: [platform/integrations.ts:135](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L135) +Defined in: [platform/integrations.ts:136](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L136) ##### code > `readonly` **code**: `string` \| `undefined` -Defined in: [platform/integrations.ts:136](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L136) +Defined in: [platform/integrations.ts:137](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L137) ##### body > `readonly` **body**: `unknown` -Defined in: [platform/integrations.ts:137](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L137) +Defined in: [platform/integrations.ts:138](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L138) *** ### PlatformHubClient -Defined in: [platform/integrations.ts:150](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L150) +Defined in: [platform/integrations.ts:152](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L152) + +HTTP client for the Tangle Platform Hub API: provider catalog, connection flow, and status. #### Constructors @@ -220,7 +210,7 @@ Defined in: [platform/integrations.ts:150](https://github.com/tangle-network/age > **new PlatformHubClient**(`options`): [`PlatformHubClient`](#platformhubclient) -Defined in: [platform/integrations.ts:155](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L155) +Defined in: [platform/integrations.ts:157](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L157) ###### Parameters @@ -238,7 +228,7 @@ Defined in: [platform/integrations.ts:155](https://github.com/tangle-network/age > **catalog**(): `Promise`\<[`CatalogResult`](#catalogresult)\> -Defined in: [platform/integrations.ts:166](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L166) +Defined in: [platform/integrations.ts:168](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L168) GET /v1/hub/providers — the connectable provider catalog. @@ -250,7 +240,7 @@ GET /v1/hub/providers — the connectable provider catalog. > **listConnections**(): `Promise`\<[`PlatformConnection`](#platformconnection)[]\> -Defined in: [platform/integrations.ts:171](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L171) +Defined in: [platform/integrations.ts:173](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L173) GET /v1/hub/connections — the calling user's live connections. @@ -262,7 +252,7 @@ GET /v1/hub/connections — the calling user's live connections. > **revokeConnection**(`connectionId`): `Promise`\<\{ `connection`: [`PlatformConnection`](#platformconnection); \}\> -Defined in: [platform/integrations.ts:180](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L180) +Defined in: [platform/integrations.ts:182](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L182) DELETE /v1/hub/connections/:connectionId — revoke + disable a connection. @@ -280,7 +270,7 @@ DELETE /v1/hub/connections/:connectionId — revoke + disable a connection. > **startAuth**(`input`): `Promise`\<[`StartAuthResult`](#startauthresult)\> -Defined in: [platform/integrations.ts:190](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L190) +Defined in: [platform/integrations.ts:192](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L192) POST /v1/hub/connections/:provider/start — begin OAuth/grant. The provider is taken from the URL; the body carries `returnUrl` (+ `cli`). The platform's @@ -301,7 +291,7 @@ substrate → `redirectUrl`); this normalizes to `authorizationUrl`. > **listHealthchecks**(): `Promise`\<[`HealthCheck`](#healthcheck)[]\> -Defined in: [platform/integrations.ts:217](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L217) +Defined in: [platform/integrations.ts:219](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L219) Last-known health for every connection. The platform has no global healthcheck listing — health rides on each connection row — so this derives @@ -315,7 +305,7 @@ the list from `listConnections()` (one request, no extra round-trips). > **checkConnectionHealth**(`connectionId`): `Promise`\<[`ConnectionHealthResult`](#connectionhealthresult)\> -Defined in: [platform/integrations.ts:231](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L231) +Defined in: [platform/integrations.ts:233](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L233) POST /v1/hub/connections/:connectionId/health — trigger a fresh health probe for one connection and return its updated state. @@ -334,7 +324,7 @@ probe for one connection and return its updated state. > **runHealthchecks**(): `Promise`\<\{ `scheduled`: `number`; \}\> -Defined in: [platform/integrations.ts:240](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L240) +Defined in: [platform/integrations.ts:242](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L242) Trigger a fresh health probe across all of the user's connections. The platform exposes health per-connection only, so this fans out over @@ -348,7 +338,7 @@ platform exposes health per-connection only, so this fans out over > **status**(): `Promise`\<[`PlatformHubStatus`](#platformhubstatus)\> -Defined in: [platform/integrations.ts:247](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L247) +Defined in: [platform/integrations.ts:249](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L249) GET /v1/hub/status — principal + aggregate connection counts. @@ -360,7 +350,7 @@ GET /v1/hub/status — principal + aggregate connection counts. > **mintToken**(`input`): `Promise`\<[`MintTokenResult`](#minttokenresult)\> -Defined in: [platform/integrations.ts:256](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L256) +Defined in: [platform/integrations.ts:258](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L258) POST /v1/hub/tokens — mint a short-lived, action-scoped capability token a sandbox can use to invoke one hub action on the user's behalf without @@ -380,7 +370,7 @@ seeing the underlying provider credential. > **exec**(`input`): `Promise`\<`unknown`\> -Defined in: [platform/integrations.ts:261](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L261) +Defined in: [platform/integrations.ts:263](https://github.com/tangle-network/agent-runtime/blob/main/src/platform/integrations.ts#L263) POST /v1/hub/exec — execute a hub action and return its result. diff --git a/docs/api/primitive-catalog.md b/docs/api/primitive-catalog.md index 15ff31bb..f92cbea8 100644 --- a/docs/api/primitive-catalog.md +++ b/docs/api/primitive-catalog.md @@ -30,12 +30,12 @@ Import from `@tangle-network/agent-runtime` — 208 exports. | `composeRuntimeHooks` | function | Merge several {@link RuntimeHooks} into one. Falsy entries are dropped (so you can | | `computeBackoff` | function | Compute the delay before the next attempt. Default: 250ms exponential with jitter. | | `createConversationBackend` | function | Wrap a `Conversation` so it satisfies `AgentExecutionBackend`. The result is | -| `createIterableBackend` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `createIterableBackend` | function | Wrap any custom async-iterable stream into a typed `AgentExecutionBackend`. | | `createOpenAICompatibleBackend` | function | OpenAI-compat streaming backend. Routes `runAgentTaskStream` through any | | `createOtelExporter` | function | Create an OTEL exporter. Returns undefined when no endpoint is configured. | -| `createRuntimeEventCollector` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `createRuntimeEventCollector` | function | Build an in-memory collector that sanitizes and accumulates `AgentRuntimeEvent`s for inspection. | | `createRuntimeStreamEventCollector` | function | Streaming-event counterpart of `createRuntimeEventCollector`. Pass each | -| `createSandboxPromptBackend` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `createSandboxPromptBackend` | function | Build an `AgentExecutionBackend` backed by a sandbox/sidecar `streamPrompt` call. | | `d1ToSqlAdapter` | function | Adapt a Cloudflare D1 binding to the SqlAdapter shape. Lives here so D1 | | `decideKnowledgeReadiness` | function | Map a `KnowledgeReadinessReport` to a three-state branch (`ready` / `blocked` / `caveat`) the runtime, route handlers, and UI shells all switch on. | | `defineConversation` | function | Declarative constructor for a multi-agent `Conversation`. Validates inputs | @@ -46,19 +46,19 @@ Import from `@tangle-network/agent-runtime` — 208 exports. | `handleChatTurn` | function | Run one chat turn. Returns immediately with a `ReadableStream` body; | | `improve` | function | Run the held-out-gated self-improvement loop on ONE profile surface. | | `improvementDriver` | function | The one reflective/agentic improvement proposer (`SurfaceProposer`): owns the candidate worktree lifecycle and delegates HOW a change is produced to a pluggable `CandidateGenerator`. | -| `isDelegatedLoopMode` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `isDelegatedLoopMode` | function | Type guard — returns true when `value` is a valid `DelegatedLoopMode` string. | | `isDepthExceeded` | function | Refuse further forwarding when the inbound depth has reached the limit. | | `loopEventToOtelSpan` | function | Convert a LoopTraceEvent into an OtelSpan for export. | | `makePerAttemptSignal` | function | Build a per-attempt AbortSignal linked to the parent signal AND fired when | -| `mcpBuildPrompt` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `mcpServeVerifier` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `mcpBuildPrompt` | function | Build the starting instruction for a coder agent tasked with implementing a new MCP server. | +| `mcpServeVerifier` | function | Build a `Verifier` that boots a generated MCP server over stdio and checks it exposes tools. | | `mcpToolsForRuntimeMcp` | function | Returns the queue-bound delegation tools projected into OpenAI Chat | | `mcpToolsForRuntimeMcpSubset` | function | Subset filter — return only the projected tools whose `function.name` | -| `notifyRuntimeDecisionPoint` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `notifyRuntimeHookEvent` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `notifyRuntimeDecisionPoint` | function | Fire `hooks.onDecisionPoint`, swallowing sync throws and surfacing async failures to `onError`. | +| `notifyRuntimeHookEvent` | function | Fire `hooks.onEvent`, swallowing sync throws and surfacing async failures to `onError`. | | `parseLoopRunnerArgv` | function | Parse `--mode X --config Y` from an argv tail (`process.argv.slice(2)`). | | `readDepth` | function | Read the depth counter off an inbound request. Missing → 0 (caller is the | -| `readinessServerSentEvent` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `readinessServerSentEvent` | function | Serialize a `KnowledgeReadinessReport` as a Server-Sent Event string. | | `reflectiveGenerator` | function | Cheap no-sandbox `CandidateGenerator` (the `shots=1` setting): draft surface edits via the improvement adapter and apply them as one coherent candidate. | | `researchLoopRunner` | function | `research` mode — research-in-a-loop with valid-only KB growth. | | `resolveChatModel` | function | Resolve a chat model by precedence: the first candidate carrying a | @@ -71,35 +71,35 @@ Import from `@tangle-network/agent-runtime` — 208 exports. | `runLoopRunnerCli` | function | Pure CLI core (no process / argv / IO) so it's unit-testable: validate the | | `runPersonaConversation` | function | Run one worker profile against one persona as a multi-round conversation. | | `runPersonaDispatch` | function | Wrap {@link runPersonaConversation} as a `ProfileDispatchFn` for | -| `runtimeStreamServerSentEvent` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `runtimeStreamServerSentEvent` | function | Serialize a `RuntimeStreamEvent` as a Server-Sent Event string. | | `runToolLoop` | function | Run the bounded tool loop and return the final text + every executed tool | -| `sanitizeAgentRuntimeEvent` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `sanitizeKnowledgeReadinessReport` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `sanitizeRuntimeStreamEvent` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `sanitizeAgentRuntimeEvent` | function | Reduce an `AgentRuntimeEvent` to a PII-safe, serializable plain object for telemetry. | +| `sanitizeKnowledgeReadinessReport` | function | Strip PII and large blobs from a `KnowledgeReadinessReport` for safe telemetry emission. | +| `sanitizeRuntimeStreamEvent` | function | Reduce a `RuntimeStreamEvent` to a PII-safe, serializable plain object for telemetry. | | `selfImproveLoopRunner` | function | `self-improve` mode — agent-eval's one-call closed improvement loop (held-out gated). | -| `sleep` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `sleep` | function | Resolve after `ms` milliseconds — used for retry backoff in conversation call policy. | | `slugifySpeaker` | function | Reduce a speaker name to ASCII alphanumerics + dashes. Preserves enough | | `startRuntimeRun` | function | Construct a runtime-run handle. The returned handle is mutable across its | | `streamToolLoop` | function | Streaming bounded tool loop: yields each raw turn event (the caller maps + | -| `toolBuildPrompt` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `toolBuildPrompt` | function | Build the starting instruction for a coder agent tasked with implementing a new tool. | | `turnId` | function | Deterministic turn identifier. Stable across retries of the same logical | | `validateChatModelId` | function | Validate a caller-supplied chat-model id. Rejects non-strings, malformed | | `worktreeLoopRunner` | function | `code` mode on the GENERIC recursive path: author one `AgentProfile` per harness, run them as a | | `DEFAULT_MAX_DEPTH` | const | Hard cap on chained gateway hops; refused beyond this. Default keeps recursion bounded. | -| `DEFAULT_ROUTER_BASE_URL` | const | _(no summary — add a TSDoc line at the declaration)_ | +| `DEFAULT_ROUTER_BASE_URL` | const | Default Tangle Router base URL used when no env override is set. | | `defaultIsRetryable` | const | Default retryable classification — network/timeout class errors. Errors | -| `DELEGATED_LOOP_MODES` | const | _(no summary — add a TSDoc line at the declaration)_ | +| `DELEGATED_LOOP_MODES` | const | All valid delegated-loop mode names — used for validation and CLI surfaces. | | `FORWARD_HEADERS` | const | Standard names — lowercased so Headers maps interop on every runtime. | | `INTELLIGENCE_WIRE_VERSION` | const | Wire version the eval-runs ingest enforces (X-Tangle-Wire-Version + body). | | `AgentEvalError` | class | _(no summary — add a TSDoc line at the declaration)_ | | `BackendTransportError` | class | A backend transport call (HTTP, gRPC, sidecar IPC) failed with a non-success | | `CircuitBreakerState` | class | Live circuit-breaker state — one instance per (participant, conversation run). | -| `CircuitOpenError` | class | _(no summary — add a TSDoc line at the declaration)_ | +| `CircuitOpenError` | class | Thrown when the circuit breaker is open for a participant and no retry is allowed yet. | | `ConfigError` | class | Configuration missing or malformed (`HOME` unset, required image not supplied, env var absent). | -| `DeadlineExceededError` | class | _(no summary — add a TSDoc line at the declaration)_ | +| `DeadlineExceededError` | class | Thrown when a backend call exceeds its per-attempt deadline. | | `FileConversationJournal` | class | JSONL on disk. One line per record; first line is the `begin`, subsequent | -| `InMemoryConversationJournal` | class | _(no summary — add a TSDoc line at the declaration)_ | -| `InMemoryRuntimeSessionStore` | class | _(no summary — add a TSDoc line at the declaration)_ | +| `InMemoryConversationJournal` | class | In-memory `ConversationJournal` — suitable for testing and single-process runs. | +| `InMemoryRuntimeSessionStore` | class | In-memory `RuntimeSessionStore` for single-process use and tests. | | `JudgeError` | class | A judge call failed in a way that's not retryable: schema parse failure, bad rubric, conflicting dimensions. | | `NotFoundError` | class | A named resource (run, span, rubric, scenario, dataset row, route) does not exist. | | `PlannerError` | class | The dynamic-loop planner returned an unusable topology move — the LLM emitted | @@ -152,14 +152,14 @@ Import from `@tangle-network/agent-runtime/agent` — 33 exports. | `collectAgentRun` | function | Drain `act`'s `events` into an array AND await its `output`. Useful for | | `createSandboxAct` | function | Build an `AgentRuntime.act` implementation backed by a single prod-profile | | `createSurfaceImprovementAdapter` | function | The substrate-default `ImprovementAdapter`: resolve each finding's subject to a real surface path, LLM-draft a unified-diff patch, then auto-apply or open a PR. | -| `createSurfaceKnowledgeAdapter` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `createSurfaceKnowledgeAdapter` | function | Wire a surface-based `KnowledgeAdapter` that writes analyst proposals to agent surface files. | | `defineAgent` | function | Construct a validated agent manifest. Throws `AgentManifestError` | | `measureOutcome` | function | Run `runAnalystLoop` and stamp an `OutcomeMeasurement` onto the | -| `renderSurfaceIssues` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `renderSurfaceIssues` | function | Format a list of surface validation issues into a human-readable error string. | | `resolveSubjectPath` | function | Resolve a parsed `FindingSubject` to the file path the substrate | | `unimplementedAgentRun` | function | Stub for agents whose `runtime.act` is not yet wired to the substrate's | | `validateSurfaces` | function | Validate an `AgentSurfaces` map on disk — missing paths fail loud at `defineAgent` time instead of silently skipping self-improvement edits. | -| `AgentManifestError` | class | _(no summary — add a TSDoc line at the declaration)_ | +| `AgentManifestError` | class | Thrown when `defineAgent` finds a required surface missing on disk. | | `AgentManifest` | interface | The full agent manifest. Each agent ships ONE of these. | | `AgentSurfaces` | interface | Surface declarations. Every path is repo-relative (or absolute) at | | `CreateSurfaceKnowledgeAdapterOpts` | interface | Substrate-default `KnowledgeAdapter` — wraps agent-knowledge's | @@ -278,7 +278,7 @@ Import from `@tangle-network/agent-runtime/loops` — 409 exports. | `createShapeRegistry` | function | Build a fresh open `ShapeRegistry`. A factory is stored type-erased and re-cast on resolve — the | | `createSupervisor` | function | The `Supervisor` impl (KEYSTONE, build step 5). | | `createVerifierEnvironment` | function | Any checkable task as an `Environment`, no tool surface required: the artifact is the worker's answer and the domain is one deployable `check` over it. | -| `createWaterfallCollector` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `createWaterfallCollector` | function | Build a `WaterfallCollector` that records agent spans and renders them as an ASCII timeline. | | `createWorktreeCliExecutor` | function | Build a worktree-CLI leaf `Executor`. Per-spawn (a fresh worktree + abort + teardown each), so a | | `decodeToolPart` | function | Decode a part with a specific harness's adapter when known, else try every registered adapter | | `defaultSelectWinner` | function | The kernel's winner argmax — best-valid-score, ties broken by earliest index, | @@ -371,9 +371,9 @@ Import from `@tangle-network/agent-runtime/loops` — 409 exports. | `builtinShapes` | const | The default registry `runPersonified` resolves a shape name against. Empty by construction — | | `cliWorktreeExecutor` | const | The leaf `createWorktreeCliExecutor` as a backend-as-data factory: a supervisor-authored | | `defaultAnalystInstruction` | const | The default observer instruction — exported so an optimizer can seed its population. | -| `defaultAuditorInstruction` | const | _(no summary — add a TSDoc line at the declaration)_ | +| `defaultAuditorInstruction` | const | Default system instruction for intent-auditor agents: diagnose diverged/drifting trajectories. | | `defaultDelegateBudget` | const | The conserved pool a `delegate()` call applies when the caller does not pass its own `budget`. | -| `defaultProfileRichnessThresholds` | const | _(no summary — add a TSDoc line at the declaration)_ | +| `defaultProfileRichnessThresholds` | const | Default thresholds for `ProfileRichnessThresholds` — 600 chars / 6 lines minimum system prompt. | | `refine` | const | Built-in `Strategy`: attempt → `observe()` reads the trace → steer the next attempt → repeat (deepen one lineage). | | `sample` | const | Built-in `Strategy`: K independent attempts, keep the best-verifying (best-of-N / resample). | | `sampleThenRefine` | const | The explore-then-exploit MIX: spend ⌈budget/2⌉ on independent samples (kept open), | @@ -663,21 +663,21 @@ Import from `@tangle-network/agent-runtime/profiles` — 43 exports. |---|---|---| | `appendFindings` | function | Append findings to a workspace, writing one Markdown file per finding | | `buildAuditorSystemPrompt` | function | Build a system prompt for a single auditor iteration. | -| `coderTaskToPrompt` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `createInProcessUiAuditClient` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `createUiAuditorValidator` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `coderTaskToPrompt` | function | Render a `CoderTask` into the per-task instruction handed to the coder profile. | +| `createInProcessUiAuditClient` | function | Create a `SandboxClient` that drives a local Playwright browser for in-process UI audits. | +| `createUiAuditorValidator` | function | Build a `Validator` that rejects off-lens findings and findings missing screenshot evidence. | | `decodeAuditTaskEnvelope` | function | Parse a task envelope back out of a prompt string. Returns undefined if | -| `encodeAuditTaskEnvelope` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `formatAuditorPrompt` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `initAuditWorkspace` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `parseAuditorEvents` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `readAuditRegistry` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `encodeAuditTaskEnvelope` | function | Wrap a `UiAuditTask` in a machine-readable envelope so iterations are self-describing. | +| `formatAuditorPrompt` | function | Produce the user message for one audit iteration: lens, captures to take, and the task envelope. | +| `initAuditWorkspace` | function | Create the `issues/`, `screenshots/`, and `registry.json` scaffold in a new audit workspace. | +| `parseAuditorEvents` | function | Parse raw `SandboxEvent` emissions from an audit iteration into structured `UiAuditOutput`. | +| `readAuditRegistry` | function | Read and validate the `registry.json` from an audit workspace. | | `registerCaptures` | function | Record screenshots taken for a route in the registry, without filing a | -| `summarizeRegistry` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `summarizeRegistry` | function | Compute finding counts by severity, lens, and route from an `AuditRegistry`. | | `uiAuditorProfile` | function | Preset `runLoop` bundle for vision-driven UI audits: returns the `AgentRunSpec`, output adapter, validator, and prompt formatter the loop kernel needs. | | `writeAuditIndex` | function | Regenerate `/index.md` from registry.json. | -| `LENS_BRIEFS` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `SHARED_AUDITOR_RULES` | const | _(no summary — add a TSDoc line at the declaration)_ | +| `LENS_BRIEFS` | const | Per-lens auditor briefs: concrete signals to look for and cross-lens distinctions to respect. | +| `SHARED_AUDITOR_RULES` | const | Cross-lens rules injected into every UI audit iteration: finding quality standards and scope limits. | | `UI_FINDING_SEVERITIES` | const | Frozen severity tuple, ordered worst → least bad for sort/report. | | `UI_LENSES` | const | Frozen tuple of lenses for validation + iteration. | | `UiAuditOutput` | interface | Output of one iteration. `findings` is the headline payload; `captures` | @@ -695,10 +695,10 @@ Import from `@tangle-network/agent-runtime/platform` — 20 exports. | Symbol | Kind | Summary | |---|---|---| -| `PlatformAuthClient` | class | _(no summary — add a TSDoc line at the declaration)_ | -| `PlatformAuthError` | class | _(no summary — add a TSDoc line at the declaration)_ | -| `PlatformHubClient` | class | _(no summary — add a TSDoc line at the declaration)_ | -| `PlatformHubError` | class | _(no summary — add a TSDoc line at the declaration)_ | +| `PlatformAuthClient` | class | HTTP client for the Tangle Platform SSO: builds authorize URLs and exchanges auth codes for API keys. | +| `PlatformAuthError` | class | Thrown when a `PlatformAuthClient` request returns a non-success status. | +| `PlatformHubClient` | class | HTTP client for the Tangle Platform Hub API: provider catalog, connection flow, and status. | +| `PlatformHubError` | class | Thrown when a `PlatformHubClient` request returns a non-success status. | | `HealthCheck` | interface | Last-known health for a connection, derived from the connection row. | | `PlatformAuthClientOptions` | interface | Server-side client for the Tangle platform's cross-site SSO bridge. | | `PlatformCatalogProvider` | interface | A connectable provider in the catalog (`/v1/hub/providers`). | @@ -715,16 +715,16 @@ Import from `@tangle-network/agent-runtime/mcp` — 170 exports. |---|---|---| | `buildDelegationTraceSpans` | function | Derive the compact span tree for ONE loop run from its buffered | | `capDelegationTrace` | function | Enforce the trace caps over an ordered (oldest-first) span list. Drops the | -| `captureWorktreeDiff` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `captureWorktreeDiff` | function | Stage all changes in a worktree and return the diff patch + shortstat against the base ref. | | `coderTaskFromArgs` | function | Canonical `DelegateCodeArgs` → `CoderTask` mapping — the single source for | | `composeLoopTraceEmitters` | function | Fan one `LoopTraceEvent` stream into several emitters — e.g. the | | `createCoordinationTools` | function | Build the driver's MCP tools over a live scope. | -| `createDelegateFeedbackHandler` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `createDelegateFeedbackHandler` | function | Build the MCP tool handler that persists feedback events and attaches them to delegation records. | | `createDelegateHandler` | function | Build the `delegate` tool handler. Closes over the injected supervisor substrate (`router` / | -| `createDelegateUiAuditHandler` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `createDelegationHistoryHandler` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `createDelegationStatusHandler` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `createDelegationTraceCollector` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `createDelegateUiAuditHandler` | function | Build the MCP tool handler that validates input, deduplicates via idempotency key, and enqueues a UI audit. | +| `createDelegationHistoryHandler` | function | Build the MCP tool handler that reads filtered past delegations from a `DelegationTaskQueue`. | +| `createDelegationStatusHandler` | function | Build the MCP tool handler that polls a `DelegationTaskQueue` for task status. | +| `createDelegationTraceCollector` | function | Build a `DelegationTraceCollector` that buffers loop-trace events and converts them to spans on settle. | | `createDetachedTurnResumeDriver` | function | Build the `driveTurn`-backed {@link DelegationResumeDriver}. Each `tick()` | | `createFleetWorkspaceExecutor` | function | Build an executor that resolves each delegated iteration to an existing | | `createInProcessExecutor` | function | Build an in-process executor. Returns a {@link DelegationExecutor} whose `client.create()` | @@ -733,7 +733,7 @@ Import from `@tangle-network/agent-runtime/mcp` — 170 exports. | `createMcpServer` | function | Stdio JSON-RPC MCP server exposing the delegation tools (`delegate`, `delegate_feedback`, `delegation_status`, `delegation_history`, optional `delegate_ui_audit`) to sandbox coding-harness agents. | | `createPropagatingTraceEmitter` | function | Create a LoopTraceEmitter that: | | `createSiblingSandboxExecutor` | function | Wrap a raw sandbox SDK client so the kernel emits | -| `createWorktree` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `createWorktree` | function | Checkout a fresh git worktree for a delegation run on a new branch under `variantsDir`. | | `detachedSessionDelegate` | function | Build the sandbox-session coder delegate. It drives `runLoop` against the project's | | `detachedTurnEvents` | function | Synthesize the terminal event array a detached turn settles through. Shaped | | `detectExecutor` | function | Pick the right executor for an MCP server invocation based on env vars. | @@ -744,44 +744,44 @@ Import from `@tangle-network/agent-runtime/mcp` — 170 exports. | `makeCheckRunner` | function | Build a `run_analyst` runner over a kind directory. | | `mcpToolsForRuntimeMcp` | function | Returns the queue-bound delegation tools projected into OpenAI Chat | | `mcpToolsForRuntimeMcpSubset` | function | Subset filter — return only the projected tools whose `function.name` | -| `parseDetachedSessionRef` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `parseDetachedSessionRef` | function | Parse a `detachedSessionRef` string back to parts; throws `ValidationError` on malformed input. | | `readTraceContextFromEnv` | function | Read trace context from the process environment. | -| `removeWorktree` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `removeWorktree` | function | Remove a git worktree and delete its branch; tolerates already-removed paths. | | `renderTrace` | function | Render a worker's trace (tool calls + results) into the text an analyst lens reads. Generic over | | `runCheck` | function | Run ONE lens over a trace → findings. Generic over any kind: prompt = the lens + the agent-eval | | `runDetachedTurn` | function | Dispatch one detached turn and advance it to a terminal state with | | `runLocalHarness` | function | Spawn a local coding harness CLI as a subprocess + collect its output. | | `settleDetachedCoderTurn` | function | Settle a completed detached coder turn through the same gate the streaming | | `traceContextToEnv` | function | Build env vars to pass to a child MCP subprocess so it inherits the | -| `validateDelegateArgs` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `validateDelegateFeedbackArgs` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `validateDelegateUiAuditArgs` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `validateDelegationHistoryArgs` | function | _(no summary — add a TSDoc line at the declaration)_ | -| `validateDelegationStatusArgs` | function | _(no summary — add a TSDoc line at the declaration)_ | +| `validateDelegateArgs` | function | Parse and validate raw MCP tool input into typed `DelegateArgs`; throws `TypeError` on bad input. | +| `validateDelegateFeedbackArgs` | function | Parse and validate raw MCP tool input into typed `DelegateFeedbackArgs`; throws `TypeError` on bad input. | +| `validateDelegateUiAuditArgs` | function | Parse and validate raw MCP tool input into typed `DelegateUiAuditArgs`; throws `TypeError` on bad input. | +| `validateDelegationHistoryArgs` | function | Parse and validate raw MCP tool input into typed `DelegationHistoryArgs`; throws `TypeError` on bad input. | +| `validateDelegationStatusArgs` | function | Parse and validate raw MCP tool input into typed `DelegationStatusArgs`; throws `TypeError` on bad input. | | `defaultChecks` | const | The built-in lens directory. Domain-blind (about any agent trace); compose at test time. | -| `DELEGATE_DESCRIPTION` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATE_FEEDBACK_DESCRIPTION` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATE_FEEDBACK_INPUT_SCHEMA` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATE_FEEDBACK_TOOL_NAME` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATE_INPUT_SCHEMA` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATE_TOOL_NAME` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATE_UI_AUDIT_DESCRIPTION` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATE_UI_AUDIT_INPUT_SCHEMA` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATE_UI_AUDIT_TOOL_NAME` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATION_HISTORY_DESCRIPTION` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATION_HISTORY_INPUT_SCHEMA` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATION_HISTORY_TOOL_NAME` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATION_STATUS_DESCRIPTION` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATION_STATUS_INPUT_SCHEMA` | const | _(no summary — add a TSDoc line at the declaration)_ | -| `DELEGATION_STATUS_TOOL_NAME` | const | _(no summary — add a TSDoc line at the declaration)_ | +| `DELEGATE_DESCRIPTION` | const | Human-readable description of the `delegate` MCP tool, injected into the tool manifest. | +| `DELEGATE_FEEDBACK_DESCRIPTION` | const | Human-readable description of the `delegate_feedback` MCP tool, injected into the tool manifest. | +| `DELEGATE_FEEDBACK_INPUT_SCHEMA` | const | JSON Schema for `delegate_feedback` tool arguments (`refersTo`, `rating`, `by`, optional fields). | +| `DELEGATE_FEEDBACK_TOOL_NAME` | const | MCP tool name for the `delegate_feedback` feedback-recording tool. | +| `DELEGATE_INPUT_SCHEMA` | const | JSON Schema for `delegate` tool arguments (`intent` + optional `model` and `runId`). | +| `DELEGATE_TOOL_NAME` | const | MCP tool name for the `delegate` generic-delegation tool. | +| `DELEGATE_UI_AUDIT_DESCRIPTION` | const | Human-readable description of the `delegate_ui_audit` MCP tool, injected into the tool manifest. | +| `DELEGATE_UI_AUDIT_INPUT_SCHEMA` | const | JSON Schema for `delegate_ui_audit` tool arguments (`workspaceDir`, `routes`, optional config). | +| `DELEGATE_UI_AUDIT_TOOL_NAME` | const | MCP tool name for the `delegate_ui_audit` async kickoff tool. | +| `DELEGATION_HISTORY_DESCRIPTION` | const | Human-readable description of the `delegation_history` MCP tool, injected into the tool manifest. | +| `DELEGATION_HISTORY_INPUT_SCHEMA` | const | JSON Schema for `delegation_history` tool arguments (optional `namespace`, `profile`, `since`, `limit`). | +| `DELEGATION_HISTORY_TOOL_NAME` | const | MCP tool name for the `delegation_history` read-past-delegations tool. | +| `DELEGATION_STATUS_DESCRIPTION` | const | Human-readable description of the `delegation_status` MCP tool, injected into the tool manifest. | +| `DELEGATION_STATUS_INPUT_SCHEMA` | const | JSON Schema for `delegation_status` tool arguments (`taskId` + optional `includeTrace`). | +| `DELEGATION_STATUS_TOOL_NAME` | const | MCP tool name for the `delegation_status` synchronous-poll tool. | | `DELEGATION_TRACE_MAX_BYTES` | const | Default cap on the serialized trace payload per record, in bytes. | | `DELEGATION_TRACE_MAX_SPANS` | const | Default cap on spans retained per delegation record. | | `DelegationPersistenceError` | class | A delegation-store read or write failed (filesystem error, store | | `DelegationStateCorruptError` | class | The persisted delegation state exists but cannot be parsed into | -| `DelegationTaskQueue` | class | _(no summary — add a TSDoc line at the declaration)_ | +| `DelegationTaskQueue` | class | In-process queue for async delegation tasks — submit, cancel, poll status, and read history. | | `FileDelegationStore` | class | JSON-file persistence for the delegation queue. Each write serializes | -| `InMemoryDelegationStore` | class | _(no summary — add a TSDoc line at the declaration)_ | -| `InMemoryFeedbackStore` | class | _(no summary — add a TSDoc line at the declaration)_ | +| `InMemoryDelegationStore` | class | In-memory `DelegationStore` — suitable for single-process use and tests. | +| `InMemoryFeedbackStore` | class | In-memory `FeedbackStore` — suitable for single-process use and tests. | | `Check` | interface | One lens — a composable analyst kind. Identity fields mirror `TraceAnalystKindSpec` so a kind is | | `CoordinationTools` | interface | The supervisor-side toolbox returned by {@link createCoordinationTools}: the MCP tool | | `DelegateArgs` | interface | Parsed `delegate` tool arguments. | diff --git a/docs/api/profiles.md b/docs/api/profiles.md index cdbc7863..7e4b8707 100644 --- a/docs/api/profiles.md +++ b/docs/api/profiles.md @@ -1316,6 +1316,8 @@ Defined in: [profiles/ui-auditor/lens-prompts.ts:18](https://github.com/tangle-n **`Experimental`** +Cross-lens rules injected into every UI audit iteration: finding quality standards and scope limits. + *** ### LENS\_BRIEFS @@ -1326,6 +1328,8 @@ Defined in: [profiles/ui-auditor/lens-prompts.ts:40](https://github.com/tangle-n **`Experimental`** +Per-lens auditor briefs: concrete signals to look for and cross-lens distinctions to respect. + *** ### UI\_LENSES @@ -1356,6 +1360,8 @@ Defined in: [audit/issue-writer.ts:79](https://github.com/tangle-network/agent-r **`Experimental`** +Create the `issues/`, `screenshots/`, and `registry.json` scaffold in a new audit workspace. + #### Parameters ##### workspaceDir @@ -1376,6 +1382,8 @@ Defined in: [audit/issue-writer.ts:93](https://github.com/tangle-network/agent-r **`Experimental`** +Read and validate the `registry.json` from an audit workspace. + #### Parameters ##### workspaceDir @@ -1456,6 +1464,8 @@ Defined in: [audit/issue-writer.ts:379](https://github.com/tangle-network/agent- **`Experimental`** +Compute finding counts by severity, lens, and route from an `AuditRegistry`. + #### Parameters ##### reg @@ -1520,6 +1530,8 @@ Defined in: [profiles/ui-auditor/in-process-client.ts:190](https://github.com/ta **`Experimental`** +Create a `SandboxClient` that drives a local Playwright browser for in-process UI audits. + #### Parameters ##### options @@ -1560,6 +1572,8 @@ Defined in: [profiles/ui-auditor/output-adapter.ts:33](https://github.com/tangle **`Experimental`** +Parse raw `SandboxEvent` emissions from an audit iteration into structured `UiAuditOutput`. + #### Parameters ##### events @@ -1632,6 +1646,8 @@ Defined in: [profiles/ui-auditor/prompt.ts:26](https://github.com/tangle-network **`Experimental`** +Wrap a `UiAuditTask` in a machine-readable envelope so iterations are self-describing. + #### Parameters ##### task @@ -1676,6 +1692,8 @@ Defined in: [profiles/ui-auditor/prompt.ts:56](https://github.com/tangle-network **`Experimental`** +Produce the user message for one audit iteration: lens, captures to take, and the task envelope. + #### Parameters ##### task @@ -1696,6 +1714,8 @@ Defined in: [profiles/ui-auditor/validator.ts:52](https://github.com/tangle-netw **`Experimental`** +Build a `Validator` that rejects off-lens findings and findings missing screenshot evidence. + #### Parameters ##### task diff --git a/docs/api/runtime.md b/docs/api/runtime.md index 3eb9e1a8..ac4fb41b 100644 --- a/docs/api/runtime.md +++ b/docs/api/runtime.md @@ -7751,7 +7751,7 @@ A prompt with fewer than this many non-blank lines is thin (default 6). ### ProfileRichness -Defined in: [runtime/supervise/authoring.ts:145](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L145) +Defined in: [runtime/supervise/authoring.ts:146](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L146) Per-field verdict on one authored profile — the raw material the bench renders + scores. @@ -7761,13 +7761,13 @@ Per-field verdict on one authored profile — the raw material the bench renders > `readonly` **name**: `string` -Defined in: [runtime/supervise/authoring.ts:146](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L146) +Defined in: [runtime/supervise/authoring.ts:147](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L147) ##### systemPrompt > `readonly` **systemPrompt**: `string` -Defined in: [runtime/supervise/authoring.ts:149](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L149) +Defined in: [runtime/supervise/authoring.ts:150](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L150) The resolved system prompt (canonical `prompt.systemPrompt`, the sandbox `prompt.system` convention, or a bare-string prompt — whichever the author used). @@ -7776,55 +7776,55 @@ The resolved system prompt (canonical `prompt.systemPrompt`, the sandbox `prompt > `readonly` **systemPromptChars**: `number` -Defined in: [runtime/supervise/authoring.ts:150](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L150) +Defined in: [runtime/supervise/authoring.ts:151](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L151) ##### systemPromptLines > `readonly` **systemPromptLines**: `number` -Defined in: [runtime/supervise/authoring.ts:151](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L151) +Defined in: [runtime/supervise/authoring.ts:152](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L152) ##### sentenceCount > `readonly` **sentenceCount**: `number` -Defined in: [runtime/supervise/authoring.ts:152](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L152) +Defined in: [runtime/supervise/authoring.ts:153](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L153) ##### hasDescription > `readonly` **hasDescription**: `boolean` -Defined in: [runtime/supervise/authoring.ts:153](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L153) +Defined in: [runtime/supervise/authoring.ts:154](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L154) ##### hasTools > `readonly` **hasTools**: `boolean` -Defined in: [runtime/supervise/authoring.ts:154](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L154) +Defined in: [runtime/supervise/authoring.ts:155](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L155) ##### hasSkills > `readonly` **hasSkills**: `boolean` -Defined in: [runtime/supervise/authoring.ts:155](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L155) +Defined in: [runtime/supervise/authoring.ts:156](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L156) ##### hasMcp > `readonly` **hasMcp**: `boolean` -Defined in: [runtime/supervise/authoring.ts:156](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L156) +Defined in: [runtime/supervise/authoring.ts:157](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L157) ##### hasSubagents > `readonly` **hasSubagents**: `boolean` -Defined in: [runtime/supervise/authoring.ts:157](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L157) +Defined in: [runtime/supervise/authoring.ts:158](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L158) ##### richness > `readonly` **richness**: `number` -Defined in: [runtime/supervise/authoring.ts:159](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L159) +Defined in: [runtime/supervise/authoring.ts:160](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L160) 0..1 — fraction of richness signals present (prompt-depth + the four levers). @@ -7832,7 +7832,7 @@ Defined in: [runtime/supervise/authoring.ts:159](https://github.com/tangle-netwo > `readonly` **thin**: `boolean` -Defined in: [runtime/supervise/authoring.ts:161](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L161) +Defined in: [runtime/supervise/authoring.ts:162](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L162) True when the supervisor authored a stub instead of a real profile. @@ -7840,7 +7840,7 @@ True when the supervisor authored a stub instead of a real profile. > `readonly` **reasons**: `string`[] -Defined in: [runtime/supervise/authoring.ts:163](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L163) +Defined in: [runtime/supervise/authoring.ts:164](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L164) The specific reasons it is thin (empty when rich) — used in the finding's action. @@ -14172,7 +14172,9 @@ Defined in: [runtime/workspace.ts:7](https://github.com/tangle-network/agent-run > `const` **defaultAuditorInstruction**: `string` -Defined in: [runtime/audit-intent.ts:65](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/audit-intent.ts#L65) +Defined in: [runtime/audit-intent.ts:66](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/audit-intent.ts#L66) + +Default system instruction for intent-auditor agents: diagnose diverged/drifting trajectories. *** @@ -14265,7 +14267,9 @@ The explore-then-exploit MIX: spend ⌈budget/2⌉ on independent samples (kept > `const` **defaultProfileRichnessThresholds**: [`ProfileRichnessThresholds`](#profilerichnessthresholds) -Defined in: [runtime/supervise/authoring.ts:139](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L139) +Defined in: [runtime/supervise/authoring.ts:140](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L140) + +Default thresholds for `ProfileRichnessThresholds` — 600 chars / 6 lines minimum system prompt. *** @@ -14376,7 +14380,7 @@ One row per (strategy, satisficing target): the shareable time-to-satisfactory t > **auditIntent**(`input`, `opts`): `Promise`\<[`IntentAudit`](#intentaudit)\> -Defined in: [runtime/audit-intent.ts:109](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/audit-intent.ts#L109) +Defined in: [runtime/audit-intent.ts:110](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/audit-intent.ts#L110) The route-rigor analyst: compare declared vs revealed vs user intent over a trajectory and return aligned / drifting / diverged with evidence and one recommended intervention. @@ -16633,7 +16637,7 @@ Build a worker AGENT from a profile the supervisor authored: the authored `syste > **assessAuthoredProfile**(`profile`, `opts?`): [`ProfileRichness`](#profilerichness) -Defined in: [runtime/supervise/authoring.ts:181](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L181) +Defined in: [runtime/supervise/authoring.ts:182](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L182) OBSERVE one authored `AgentProfile` and score its richness (no judge verdict is read). The task context (`needsMcp`) lets a domain say "this work needs a data/tool MCP" so a missing MCP counts. @@ -16664,7 +16668,7 @@ OBSERVE one authored `AgentProfile` and score its richness (no judge verdict is > **profileRichnessFinding**(`richness`, `opts?`): `AnalystFinding` -Defined in: [runtime/supervise/authoring.ts:244](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L244) +Defined in: [runtime/supervise/authoring.ts:245](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/authoring.ts#L245) Turn a [ProfileRichness](#profilerichness) verdict into a bus-routable `AnalystFinding` (area `profile-quality`). Severity scales with thinness; the recommended action names the MISSING lever so the supervisor can @@ -17516,7 +17520,9 @@ Any checkable task as an `Environment`, no tool surface required: the artifact i > **createWaterfallCollector**(): [`WaterfallCollector`](#waterfallcollector) -Defined in: [runtime/waterfall.ts:58](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/waterfall.ts#L58) +Defined in: [runtime/waterfall.ts:59](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/waterfall.ts#L59) + +Build a `WaterfallCollector` that records agent spans and renders them as an ASCII timeline. #### Returns diff --git a/docs/architecture-interpretations.md b/docs/architecture-interpretations.md index 7ffad13a..ebe26a38 100644 --- a/docs/architecture-interpretations.md +++ b/docs/architecture-interpretations.md @@ -222,7 +222,7 @@ Then run the §5 gate. If a findings-fed driver beats random@k at equal k under - `src/analyst-loop/` — `runAnalystLoop`; the trace observer feeding the canonical loop is `observe()` (`src/runtime/observe.ts`), consumed by the agent-driver. - Prompt-space optimization lives in agent-eval (`selfImprove`); the analyst-prompt - coordinate is measured flat (frozen-holdout tie, 2026-06-09). + coordinate has shown no significant lift on held-back problems in controlled runs to date — see `.evolve/current.json` and the memory ledger for the current evidence state. - `bench/src/selector.ts` + `bench/src/corpus-replay.mts --selector` — the deployable selector and its offline replay harness. - `bench/src/refine-loop.ts` — shared k-shot loop. diff --git a/docs/architecture.md b/docs/architecture.md index 9376c67d..3f14fdff 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -251,9 +251,9 @@ being squatted on. **Banned from steering only** (the trace-derived-findings firewall) — it scores the corpus, it never feeds a steer or a selection. - **Selector (distinct):** the deployable, learnable component that picks among candidates at - inference (vote / verifier-rerank). Today we still *fake* it with the oracle ("any-pass"), which - isn't available in deployment (§11) — replacing that fake with a real verifier-based selector is - the open work, not a reason to ban verifiers from the loop. + inference (vote / verifier-rerank). A verifier-grounded selector (`verifierGroundedSelect` in + `bench/src/selector.ts`) is built and measured — see `docs/architecture-interpretations.md` §2 + for its current evidence status. The law stands regardless: the selector is never the judge. --- diff --git a/scripts/gen-primitive-catalog.mjs b/scripts/gen-primitive-catalog.mjs index 261fb575..0fd1851b 100644 --- a/scripts/gen-primitive-catalog.mjs +++ b/scripts/gen-primitive-catalog.mjs @@ -271,7 +271,7 @@ for (let i = 0; i < allModules.length; i++) bySpecifier.set(allModules[i].specif // The ceiling is the exact current count; when a backfill lowers the real number, // lower the constant to match. Exceeding it (a new undocumented callable) exits 1. -const maxUndocumentedCallables = 108 +const maxUndocumentedCallables = 34 const ratchetKinds = new Set(['function', 'class', 'const']) // ───────────────────────────────────────────────────────────────────────────── diff --git a/src/agent/define-agent.ts b/src/agent/define-agent.ts index b6b7365d..22ec4604 100644 --- a/src/agent/define-agent.ts +++ b/src/agent/define-agent.ts @@ -305,6 +305,7 @@ export interface AutoApplyPolicy { // ── factory + validation ───────────────────────────────────────────── +/** Thrown when `defineAgent` finds a required surface missing on disk. */ export class AgentManifestError extends Error { constructor( message: string, diff --git a/src/agent/knowledge-adapter.ts b/src/agent/knowledge-adapter.ts index dd6dbebe..291a263d 100644 --- a/src/agent/knowledge-adapter.ts +++ b/src/agent/knowledge-adapter.ts @@ -55,6 +55,7 @@ export interface KnowledgeAdapterDeps { lintAfterApply?: (root: string) => Promise> } +/** Wire a surface-based `KnowledgeAdapter` that writes analyst proposals to agent surface files. */ export function createSurfaceKnowledgeAdapter( opts: CreateSurfaceKnowledgeAdapterOpts, deps: KnowledgeAdapterDeps, diff --git a/src/agent/surfaces.ts b/src/agent/surfaces.ts index 6b1b07e4..c86e5210 100644 --- a/src/agent/surfaces.ts +++ b/src/agent/surfaces.ts @@ -243,6 +243,7 @@ export function validateSurfaces( return issues } +/** Format a list of surface validation issues into a human-readable error string. */ export function renderSurfaceIssues( issues: ReadonlyArray, repoRoot: string, diff --git a/src/audit/issue-writer.ts b/src/audit/issue-writer.ts index 834bd32c..d1ca9afe 100644 --- a/src/audit/issue-writer.ts +++ b/src/audit/issue-writer.ts @@ -75,7 +75,7 @@ function assertValidWorkspaceDir(dir: string): void { } } -/** @experimental */ +/** Create the `issues/`, `screenshots/`, and `registry.json` scaffold in a new audit workspace. @experimental */ export async function initAuditWorkspace(workspaceDir: string): Promise { assertValidWorkspaceDir(workspaceDir) await fs.mkdir(path.join(workspaceDir, 'issues'), { recursive: true }) @@ -89,7 +89,7 @@ export async function initAuditWorkspace(workspaceDir: string): Promise { } } -/** @experimental */ +/** Read and validate the `registry.json` from an audit workspace. @experimental */ export async function readAuditRegistry(workspaceDir: string): Promise { assertValidWorkspaceDir(workspaceDir) const regPath = path.join(workspaceDir, 'registry.json') @@ -375,7 +375,7 @@ export interface AuditIndex { byRoute: Record } -/** @experimental */ +/** Compute finding counts by severity, lens, and route from an `AuditRegistry`. @experimental */ export function summarizeRegistry(reg: AuditRegistry): AuditIndex { const bySeverity: Record = { critical: 0, diff --git a/src/backends.ts b/src/backends.ts index 1a5aeeec..3f133421 100644 --- a/src/backends.ts +++ b/src/backends.ts @@ -26,7 +26,7 @@ import type { RuntimeStreamEvent, } from './types' -/** @stable */ +/** Wrap any custom async-iterable stream into a typed `AgentExecutionBackend`. @stable */ export function createIterableBackend(options: { kind: string start?: AgentExecutionBackend['start'] @@ -37,7 +37,7 @@ export function createIterableBackend(options: return options } -/** @stable */ +/** Build an `AgentExecutionBackend` backed by a sandbox/sidecar `streamPrompt` call. @stable */ export function createSandboxPromptBackend< TBox, TInput extends AgentBackendInput = AgentBackendInput, diff --git a/src/conversation/call-policy.ts b/src/conversation/call-policy.ts index 409a7c75..e29c4193 100644 --- a/src/conversation/call-policy.ts +++ b/src/conversation/call-policy.ts @@ -39,6 +39,7 @@ export interface BackendCallPolicy { circuitBreaker?: CircuitBreakerConfig } +/** Thrown when the circuit breaker is open for a participant and no retry is allowed yet. */ export class CircuitOpenError extends Error { constructor(participant: string, retryAfterMs: number) { super( @@ -48,6 +49,7 @@ export class CircuitOpenError extends Error { } } +/** Thrown when a backend call exceeds its per-attempt deadline. */ export class DeadlineExceededError extends Error { constructor(deadlineMs: number) { super(`backend call exceeded per-attempt deadline of ${deadlineMs}ms`) @@ -174,6 +176,7 @@ export function computeBackoff(spec: RetryBackoff | undefined, attempt: number): return Math.max(0, spec) } +/** Resolve after `ms` milliseconds — used for retry backoff in conversation call policy. */ export function sleep(ms: number): Promise { return new Promise((resolve) => setTimeout(resolve, ms)) } diff --git a/src/conversation/journal.ts b/src/conversation/journal.ts index 3d1cd73f..6eaa59f5 100644 --- a/src/conversation/journal.ts +++ b/src/conversation/journal.ts @@ -56,6 +56,7 @@ export interface ConversationJournal { recordHalt(runId: string, halt: HaltReason, endedAt: string): Promise } +/** In-memory `ConversationJournal` — suitable for testing and single-process runs. */ export class InMemoryConversationJournal implements ConversationJournal { private readonly entries = new Map() diff --git a/src/improvement/build-prompts.ts b/src/improvement/build-prompts.ts index f2f5edfa..c83e2815 100644 --- a/src/improvement/build-prompts.ts +++ b/src/improvement/build-prompts.ts @@ -27,6 +27,7 @@ function findingLines(findings: AnalystFinding[]): string[] { }) } +/** Build the starting instruction for a coder agent tasked with implementing a new tool. */ export function toolBuildPrompt(args: FindingsArg): string { return [ 'You are building a new TOOL for this codebase to address the gaps below.', @@ -40,6 +41,7 @@ export function toolBuildPrompt(args: FindingsArg): string { ].join('\n') } +/** Build the starting instruction for a coder agent tasked with implementing a new MCP server. */ export function mcpBuildPrompt(args: FindingsArg): string { return [ 'You are building a new MCP SERVER (Model Context Protocol) that exposes', diff --git a/src/improvement/mcp-serve-verifier.ts b/src/improvement/mcp-serve-verifier.ts index b23814ed..d23a36ae 100644 --- a/src/improvement/mcp-serve-verifier.ts +++ b/src/improvement/mcp-serve-verifier.ts @@ -40,6 +40,7 @@ interface JsonRpcResponse { error?: { code: number; message: string } } +/** Build a `Verifier` that boots a generated MCP server over stdio and checks it exposes tools. */ export function mcpServeVerifier(spec: McpServeSpec): Verifier { const timeoutMs = spec.timeoutMs ?? 30_000 const minTools = spec.minTools ?? 1 diff --git a/src/loop-runner.ts b/src/loop-runner.ts index 12dc2f03..bf9bd79d 100644 --- a/src/loop-runner.ts +++ b/src/loop-runner.ts @@ -43,13 +43,13 @@ import { worktreeFanout, } from './runtime' -/** @experimental Every delegated-loop mode, for validation + CLI surfaces. */ +/** All valid delegated-loop mode names — used for validation and CLI surfaces. @experimental */ export const DELEGATED_LOOP_MODES = ['code', 'review', 'research', 'audit', 'self-improve'] as const /** @experimental */ export type DelegatedLoopMode = (typeof DELEGATED_LOOP_MODES)[number] -/** @experimental Type guard for an untrusted mode string (CLI / config input). */ +/** Type guard — returns true when `value` is a valid `DelegatedLoopMode` string. @experimental */ export function isDelegatedLoopMode(value: unknown): value is DelegatedLoopMode { return typeof value === 'string' && (DELEGATED_LOOP_MODES as readonly string[]).includes(value) } diff --git a/src/mcp/delegation-store.ts b/src/mcp/delegation-store.ts index c30f5cd4..f1e624cf 100644 --- a/src/mcp/delegation-store.ts +++ b/src/mcp/delegation-store.ts @@ -72,7 +72,7 @@ export class DelegationPersistenceError extends AgentEvalError { } } -/** @experimental */ +/** In-memory `DelegationStore` — suitable for single-process use and tests. @experimental */ export class InMemoryDelegationStore implements DelegationStore { private readonly records = new Map() diff --git a/src/mcp/delegation-trace.ts b/src/mcp/delegation-trace.ts index c7247229..1070f5da 100644 --- a/src/mcp/delegation-trace.ts +++ b/src/mcp/delegation-trace.ts @@ -127,7 +127,7 @@ export interface DelegationTraceCollector { settle(): void } -/** @experimental */ +/** Build a `DelegationTraceCollector` that buffers loop-trace events and converts them to spans on settle. @experimental */ export function createDelegationTraceCollector( onSpans: (spans: DelegationTraceSpan[]) => void, ): DelegationTraceCollector { diff --git a/src/mcp/detached-turn.ts b/src/mcp/detached-turn.ts index 673ba6f8..7dfe47bb 100644 --- a/src/mcp/detached-turn.ts +++ b/src/mcp/detached-turn.ts @@ -100,7 +100,7 @@ export function formatDetachedSessionRef(parts: DetachedSessionRefParts): string return `sandbox=${parts.sandboxId};session=${parts.sessionId}` } -/** @experimental Inverse of {@link formatDetachedSessionRef}; throws `ValidationError` on malformed input. */ +/** Parse a `detachedSessionRef` string back to parts; throws `ValidationError` on malformed input. @experimental */ export function parseDetachedSessionRef(raw: string): DetachedSessionRefParts { const fields = new Map() for (const pair of raw.split(';')) { diff --git a/src/mcp/feedback-store.ts b/src/mcp/feedback-store.ts index 521caa0a..1ebbbfa6 100644 --- a/src/mcp/feedback-store.ts +++ b/src/mcp/feedback-store.ts @@ -38,7 +38,7 @@ export interface FeedbackStore { list(filter?: { namespace?: string; refersToRef?: string }): Promise } -/** @experimental */ +/** In-memory `FeedbackStore` — suitable for single-process use and tests. @experimental */ export class InMemoryFeedbackStore implements FeedbackStore { private readonly events: FeedbackEvent[] = [] diff --git a/src/mcp/task-queue.ts b/src/mcp/task-queue.ts index 8b22ebb2..7877de40 100644 --- a/src/mcp/task-queue.ts +++ b/src/mcp/task-queue.ts @@ -239,7 +239,7 @@ export interface DelegationTaskQueueOptions { traceContext?: TraceContext } -/** @experimental */ +/** In-process queue for async delegation tasks — submit, cancel, poll status, and read history. @experimental */ export class DelegationTaskQueue { private readonly records = new Map() private readonly controllers = new Map() diff --git a/src/mcp/tools/delegate-feedback.ts b/src/mcp/tools/delegate-feedback.ts index 41f7ebd5..b4af5182 100644 --- a/src/mcp/tools/delegate-feedback.ts +++ b/src/mcp/tools/delegate-feedback.ts @@ -21,10 +21,10 @@ import type { FeedbackRefersTo, } from '../types' -/** @experimental */ +/** MCP tool name for the `delegate_feedback` feedback-recording tool. @experimental */ export const DELEGATE_FEEDBACK_TOOL_NAME = 'delegate_feedback' -/** @experimental */ +/** Human-readable description of the `delegate_feedback` MCP tool, injected into the tool manifest. @experimental */ export const DELEGATE_FEEDBACK_DESCRIPTION = [ 'Record feedback on a delegation, artifact, or outcome. Synchronous — the', 'event is durably stored when this call returns.', @@ -48,7 +48,7 @@ export const DELEGATE_FEEDBACK_DESCRIPTION = [ 'delegation record so delegation_history surfaces it inline.', ].join('\n') -/** @experimental */ +/** JSON Schema for `delegate_feedback` tool arguments (`refersTo`, `rating`, `by`, optional fields). @experimental */ export const DELEGATE_FEEDBACK_INPUT_SCHEMA = { type: 'object', properties: { @@ -79,7 +79,7 @@ export const DELEGATE_FEEDBACK_INPUT_SCHEMA = { additionalProperties: false, } as const -/** @experimental */ +/** Parse and validate raw MCP tool input into typed `DelegateFeedbackArgs`; throws `TypeError` on bad input. @experimental */ export function validateDelegateFeedbackArgs(raw: unknown): DelegateFeedbackArgs { if (raw === null || typeof raw !== 'object') { throw new TypeError('delegate_feedback: arguments must be an object') @@ -156,7 +156,7 @@ export interface DelegateFeedbackHandlerOptions { now?: () => string } -/** @experimental */ +/** Build the MCP tool handler that persists feedback events and attaches them to delegation records. @experimental */ export function createDelegateFeedbackHandler( options: DelegateFeedbackHandlerOptions, ): (raw: unknown) => Promise { diff --git a/src/mcp/tools/delegate-ui-audit.ts b/src/mcp/tools/delegate-ui-audit.ts index ca6c8fef..0b951a28 100644 --- a/src/mcp/tools/delegate-ui-audit.ts +++ b/src/mcp/tools/delegate-ui-audit.ts @@ -26,10 +26,10 @@ import { hashIdempotencyInput, } from '../task-queue' -/** @experimental */ +/** MCP tool name for the `delegate_ui_audit` async kickoff tool. @experimental */ export const DELEGATE_UI_AUDIT_TOOL_NAME = 'delegate_ui_audit' -/** @experimental */ +/** Human-readable description of the `delegate_ui_audit` MCP tool, injected into the tool manifest. @experimental */ export const DELEGATE_UI_AUDIT_DESCRIPTION = [ 'Delegate a UI/UX audit to a vision-driven auditor that produces self-contained', 'GitHub-issue-ready Markdown findings — one file per finding, with embedded', @@ -82,7 +82,7 @@ const ROUTE_SCHEMA = { additionalProperties: false, } as const -/** @experimental */ +/** JSON Schema for `delegate_ui_audit` tool arguments (`workspaceDir`, `routes`, optional config). @experimental */ export const DELEGATE_UI_AUDIT_INPUT_SCHEMA = { type: 'object', properties: { @@ -110,7 +110,7 @@ export const DELEGATE_UI_AUDIT_INPUT_SCHEMA = { const PER_LENS_PER_ROUTE_ESTIMATE_MS = 45_000 -/** @experimental */ +/** Parse and validate raw MCP tool input into typed `DelegateUiAuditArgs`; throws `TypeError` on bad input. @experimental */ export function validateDelegateUiAuditArgs(raw: unknown): DelegateUiAuditArgs { if (raw === null || typeof raw !== 'object') { throw new TypeError('delegate_ui_audit: arguments must be an object') @@ -296,7 +296,7 @@ export interface DelegateUiAuditHandlerOptions { estimateDurationMs?: (args: DelegateUiAuditArgs) => number } -/** @experimental */ +/** Build the MCP tool handler that validates input, deduplicates via idempotency key, and enqueues a UI audit. @experimental */ export function createDelegateUiAuditHandler( options: DelegateUiAuditHandlerOptions, ): (raw: unknown) => Promise { diff --git a/src/mcp/tools/delegate.ts b/src/mcp/tools/delegate.ts index 0183fafd..b0a74ac9 100644 --- a/src/mcp/tools/delegate.ts +++ b/src/mcp/tools/delegate.ts @@ -22,10 +22,10 @@ import { type DelegateOptions, delegate } from '../../runtime/supervise/delegate import type { ExecutorConfig } from '../../runtime/supervise/runtime' import type { Spend, SupervisedResult } from '../../runtime/supervise/types' -/** @experimental */ +/** MCP tool name for the `delegate` generic-delegation tool. @experimental */ export const DELEGATE_TOOL_NAME = 'delegate' -/** @experimental */ +/** Human-readable description of the `delegate` MCP tool, injected into the tool manifest. @experimental */ export const DELEGATE_DESCRIPTION = [ 'Delegate an INTENT to a supervisor that AUTHORS and drives whatever worker the intent needs.', '', @@ -43,7 +43,7 @@ export const DELEGATE_DESCRIPTION = [ 'a success.', ].join('\n') -/** @experimental */ +/** JSON Schema for `delegate` tool arguments (`intent` + optional `model` and `runId`). @experimental */ export const DELEGATE_INPUT_SCHEMA = { type: 'object', properties: { @@ -71,7 +71,7 @@ export interface DelegateArgs { runId?: string } -/** @experimental */ +/** Parse and validate raw MCP tool input into typed `DelegateArgs`; throws `TypeError` on bad input. @experimental */ export function validateDelegateArgs(raw: unknown): DelegateArgs { if (raw === null || typeof raw !== 'object') { throw new TypeError('delegate: arguments must be an object') diff --git a/src/mcp/tools/delegation-history.ts b/src/mcp/tools/delegation-history.ts index 31efc343..fec9e4a1 100644 --- a/src/mcp/tools/delegation-history.ts +++ b/src/mcp/tools/delegation-history.ts @@ -14,10 +14,10 @@ import type { DelegationTaskQueue, } from '../task-queue' -/** @experimental */ +/** MCP tool name for the `delegation_history` read-past-delegations tool. @experimental */ export const DELEGATION_HISTORY_TOOL_NAME = 'delegation_history' -/** @experimental */ +/** Human-readable description of the `delegation_history` MCP tool, injected into the tool manifest. @experimental */ export const DELEGATION_HISTORY_DESCRIPTION = [ 'Read past delegations newest-first. Each entry carries the original', 'arguments, current status, cost, and any feedback attached via', @@ -38,7 +38,7 @@ export const DELEGATION_HISTORY_DESCRIPTION = [ 'to 50, capped at 500.', ].join('\n') -/** @experimental */ +/** JSON Schema for `delegation_history` tool arguments (optional `namespace`, `profile`, `since`, `limit`). @experimental */ export const DELEGATION_HISTORY_INPUT_SCHEMA = { type: 'object', properties: { @@ -50,7 +50,7 @@ export const DELEGATION_HISTORY_INPUT_SCHEMA = { additionalProperties: false, } as const -/** @experimental */ +/** Parse and validate raw MCP tool input into typed `DelegationHistoryArgs`; throws `TypeError` on bad input. @experimental */ export function validateDelegationHistoryArgs(raw: unknown): DelegationHistoryArgs { if (raw === undefined || raw === null) return {} if (typeof raw !== 'object') { @@ -91,7 +91,7 @@ export interface DelegationHistoryHandlerOptions { queue: DelegationTaskQueue } -/** @experimental */ +/** Build the MCP tool handler that reads filtered past delegations from a `DelegationTaskQueue`. @experimental */ export function createDelegationHistoryHandler( options: DelegationHistoryHandlerOptions, ): (raw: unknown) => Promise { diff --git a/src/mcp/tools/delegation-status.ts b/src/mcp/tools/delegation-status.ts index 1112b3f2..ae989a4a 100644 --- a/src/mcp/tools/delegation-status.ts +++ b/src/mcp/tools/delegation-status.ts @@ -13,10 +13,10 @@ import type { DelegationTaskQueue, } from '../task-queue' -/** @experimental */ +/** MCP tool name for the `delegation_status` synchronous-poll tool. @experimental */ export const DELEGATION_STATUS_TOOL_NAME = 'delegation_status' -/** @experimental */ +/** Human-readable description of the `delegation_status` MCP tool, injected into the tool manifest. @experimental */ export const DELEGATION_STATUS_DESCRIPTION = [ 'Poll the status of an async delegation. Returns the current state', '(pending | running | completed | failed | cancelled), optional progress,', @@ -38,7 +38,7 @@ export const DELEGATION_STATUS_DESCRIPTION = [ '`pending` for a typo.', ].join('\n') -/** @experimental */ +/** JSON Schema for `delegation_status` tool arguments (`taskId` + optional `includeTrace`). @experimental */ export const DELEGATION_STATUS_INPUT_SCHEMA = { type: 'object', properties: { @@ -53,7 +53,7 @@ export const DELEGATION_STATUS_INPUT_SCHEMA = { additionalProperties: false, } as const -/** @experimental */ +/** Parse and validate raw MCP tool input into typed `DelegationStatusArgs`; throws `TypeError` on bad input. @experimental */ export function validateDelegationStatusArgs(raw: unknown): DelegationStatusArgs { if (raw === null || typeof raw !== 'object') { throw new TypeError('delegation_status: arguments must be an object') @@ -78,7 +78,7 @@ export interface DelegationStatusHandlerOptions { queue: DelegationTaskQueue } -/** @experimental */ +/** Build the MCP tool handler that polls a `DelegationTaskQueue` for task status. @experimental */ export function createDelegationStatusHandler( options: DelegationStatusHandlerOptions, ): (raw: unknown) => Promise { diff --git a/src/mcp/worktree.ts b/src/mcp/worktree.ts index 0ebc2bbd..018e819f 100644 --- a/src/mcp/worktree.ts +++ b/src/mcp/worktree.ts @@ -110,7 +110,7 @@ function ensureGitOk( } } -/** @experimental */ +/** Checkout a fresh git worktree for a delegation run on a new branch under `variantsDir`. @experimental */ export async function createWorktree(options: CreateWorktreeOptions): Promise { const variants = options.variantsDir ?? '.agent-worktrees' const baseRef = options.baseRef ?? 'HEAD' @@ -130,7 +130,7 @@ export async function createWorktree(options: CreateWorktreeOptions): Promise { const baseRef = options.baseRef ?? options.worktree.baseSha // Stage everything (incl. NEW/untracked files) before diffing: a plain `git diff ` @@ -170,7 +170,7 @@ function parseShortstat(text: string): DiffResult['stats'] { return out } -/** @experimental */ +/** Remove a git worktree and delete its branch; tolerates already-removed paths. @experimental */ export async function removeWorktree(options: RemoveWorktreeOptions): Promise { const force = options.force ?? true const args = ['worktree', 'remove'] diff --git a/src/model-resolution.ts b/src/model-resolution.ts index 5fa1fb96..d20759cf 100644 --- a/src/model-resolution.ts +++ b/src/model-resolution.ts @@ -39,6 +39,7 @@ export interface RouterEnv { TANGLE_ROUTER_BASE_URL?: string } +/** Default Tangle Router base URL used when no env override is set. */ export const DEFAULT_ROUTER_BASE_URL = 'https://router.tangle.tools' /** Resolve the router base URL from env, normalised — no trailing `/v1` or `/`. */ diff --git a/src/platform/auth.ts b/src/platform/auth.ts index d45e050a..cf86990c 100644 --- a/src/platform/auth.ts +++ b/src/platform/auth.ts @@ -47,6 +47,7 @@ export interface ExchangeCodeResult { } } +/** Thrown when a `PlatformAuthClient` request returns a non-success status. */ export class PlatformAuthError extends Error { constructor( message: string, @@ -58,6 +59,7 @@ export class PlatformAuthError extends Error { } } +/** HTTP client for the Tangle Platform SSO: builds authorize URLs and exchanges auth codes for API keys. */ export class PlatformAuthClient { private readonly baseUrl: string private readonly appId: string diff --git a/src/platform/integrations.ts b/src/platform/integrations.ts index cfdfa6b0..8a610072 100644 --- a/src/platform/integrations.ts +++ b/src/platform/integrations.ts @@ -129,6 +129,7 @@ export interface PlatformHubStatus { connections: { connectedProviderCount: number; unhealthyProviderCount: number } } +/** Thrown when a `PlatformHubClient` request returns a non-success status. */ export class PlatformHubError extends Error { constructor( message: string, @@ -147,6 +148,7 @@ interface PlatformEnvelope { error?: { code?: string; message?: string } | string } +/** HTTP client for the Tangle Platform Hub API: provider catalog, connection flow, and status. */ export class PlatformHubClient { private readonly baseUrl: string private readonly bearer: string diff --git a/src/profiles/coder.ts b/src/profiles/coder.ts index 8975b578..cdad87c9 100644 --- a/src/profiles/coder.ts +++ b/src/profiles/coder.ts @@ -35,7 +35,7 @@ export interface CoderTask { maxDiffLines?: number } -/** @experimental Render a `CoderTask` into the per-task instruction handed to the coder profile. */ +/** Render a `CoderTask` into the per-task instruction handed to the coder profile. @experimental */ export function coderTaskToPrompt(task: CoderTask): string { const base = task.baseBranch ?? 'main' const testCmd = task.testCmd ?? 'pnpm test --run' diff --git a/src/profiles/ui-auditor/in-process-client.ts b/src/profiles/ui-auditor/in-process-client.ts index 3fd9c45e..e9840b4d 100644 --- a/src/profiles/ui-auditor/in-process-client.ts +++ b/src/profiles/ui-auditor/in-process-client.ts @@ -186,7 +186,7 @@ function makeSandboxId(): string { return `ui-audit-${rand()}${rand()}` } -/** @experimental */ +/** Create a `SandboxClient` that drives a local Playwright browser for in-process UI audits. @experimental */ export function createInProcessUiAuditClient( options: InProcessUiAuditClientOptions, ): SandboxClient & { diff --git a/src/profiles/ui-auditor/lens-prompts.ts b/src/profiles/ui-auditor/lens-prompts.ts index 654e1cc2..d7a5f5db 100644 --- a/src/profiles/ui-auditor/lens-prompts.ts +++ b/src/profiles/ui-auditor/lens-prompts.ts @@ -14,7 +14,7 @@ import type { UiLens } from './substrate' -/** @experimental */ +/** Cross-lens rules injected into every UI audit iteration: finding quality standards and scope limits. @experimental */ export const SHARED_AUDITOR_RULES = ` You are auditing a UI for a specific class of problems. Stay strictly in your assigned lens — do not file issues that belong to another lens (a separate iteration will catch those). @@ -36,7 +36,7 @@ Required for every finding: Most findings are med or low. Reserve high/critical for genuine blockers. `.trim() -/** @experimental */ +/** Per-lens auditor briefs: concrete signals to look for and cross-lens distinctions to respect. @experimental */ export const LENS_BRIEFS: Record = { consistency: ` LENS: consistency diff --git a/src/profiles/ui-auditor/output-adapter.ts b/src/profiles/ui-auditor/output-adapter.ts index 08a01e7c..bc977520 100644 --- a/src/profiles/ui-auditor/output-adapter.ts +++ b/src/profiles/ui-auditor/output-adapter.ts @@ -29,7 +29,7 @@ function isUiLens(v: unknown): v is UiLens { return typeof v === 'string' && KNOWN_LENS_VALUES.has(v as UiLens) } -/** @experimental */ +/** Parse raw `SandboxEvent` emissions from an audit iteration into structured `UiAuditOutput`. @experimental */ export function parseAuditorEvents(events: SandboxEvent[]): UiAuditOutput { const findings: UiFinding[] = [] const captures: UiAuditCapture[] = [] diff --git a/src/profiles/ui-auditor/prompt.ts b/src/profiles/ui-auditor/prompt.ts index 58334797..24460c0f 100644 --- a/src/profiles/ui-auditor/prompt.ts +++ b/src/profiles/ui-auditor/prompt.ts @@ -22,7 +22,7 @@ import type { UiAuditTask } from './task' const ENVELOPE_BEGIN = '<>' const ENVELOPE_END = '<>' -/** @experimental */ +/** Wrap a `UiAuditTask` in a machine-readable envelope so iterations are self-describing. @experimental */ export function encodeAuditTaskEnvelope(task: UiAuditTask): string { return `${ENVELOPE_BEGIN}${JSON.stringify(task)}${ENVELOPE_END}` } @@ -52,7 +52,7 @@ export function decodeAuditTaskEnvelope(prompt: string): UiAuditTask | undefined } } -/** @experimental */ +/** Produce the user message for one audit iteration: lens, captures to take, and the task envelope. @experimental */ export function formatAuditorPrompt(task: UiAuditTask): string { const lines: string[] = [] lines.push(`# UI audit iteration — lens: ${task.lens}`) diff --git a/src/profiles/ui-auditor/validator.ts b/src/profiles/ui-auditor/validator.ts index f3b764a4..369a5b35 100644 --- a/src/profiles/ui-auditor/validator.ts +++ b/src/profiles/ui-auditor/validator.ts @@ -48,7 +48,7 @@ function isGenericTitle(title: string): boolean { return GENERIC_TITLE_PATTERNS.some((re) => re.test(t)) } -/** @experimental */ +/** Build a `Validator` that rejects off-lens findings and findings missing screenshot evidence. @experimental */ export function createUiAuditorValidator(task: UiAuditTask): Validator { return { async validate(output) { diff --git a/src/runtime-hooks.ts b/src/runtime-hooks.ts index 5a03eac3..6cb9d5ba 100644 --- a/src/runtime-hooks.ts +++ b/src/runtime-hooks.ts @@ -154,6 +154,7 @@ export function composeRuntimeHooks( } } +/** Fire `hooks.onEvent`, swallowing sync throws and surfacing async failures to `onError`. */ export function notifyRuntimeHookEvent( hooks: RuntimeHooks | undefined, event: RuntimeHookEvent, @@ -184,6 +185,7 @@ export function notifyRuntimeHookEvent( } } +/** Fire `hooks.onDecisionPoint`, swallowing sync throws and surfacing async failures to `onError`. */ export function notifyRuntimeDecisionPoint( hooks: RuntimeHooks | undefined, point: RuntimeDecisionPoint, diff --git a/src/runtime/audit-intent.ts b/src/runtime/audit-intent.ts index cbf50299..762fde0c 100644 --- a/src/runtime/audit-intent.ts +++ b/src/runtime/audit-intent.ts @@ -62,6 +62,7 @@ export interface IntentAudit { confidence: number } +/** Default system instruction for intent-auditor agents: diagnose diverged/drifting trajectories. */ export const defaultAuditorInstruction = 'You audit whether an AI agent is on the RIGHT ROUTE — not whether it works hard, but whether its ' + 'actions serve the stated intents. Infer the REVEALED intent from the action pattern (what the ' + diff --git a/src/runtime/supervise/authoring.ts b/src/runtime/supervise/authoring.ts index d94b2a61..c8ee56ed 100644 --- a/src/runtime/supervise/authoring.ts +++ b/src/runtime/supervise/authoring.ts @@ -136,6 +136,7 @@ export interface ProfileRichnessThresholds { readonly minSystemPromptLines: number } +/** Default thresholds for `ProfileRichnessThresholds` — 600 chars / 6 lines minimum system prompt. */ export const defaultProfileRichnessThresholds: ProfileRichnessThresholds = { minSystemPromptChars: 600, minSystemPromptLines: 6, diff --git a/src/runtime/waterfall.ts b/src/runtime/waterfall.ts index f2c40114..096f1701 100644 --- a/src/runtime/waterfall.ts +++ b/src/runtime/waterfall.ts @@ -55,6 +55,7 @@ export interface WaterfallCollector { reset(): void } +/** Build a `WaterfallCollector` that records agent spans and renders them as an ASCII timeline. */ export function createWaterfallCollector(): WaterfallCollector { let spans = new Map() diff --git a/src/sanitize.ts b/src/sanitize.ts index 05d20149..6d4e9f26 100644 --- a/src/sanitize.ts +++ b/src/sanitize.ts @@ -78,7 +78,7 @@ export interface SanitizedKnowledgeReadinessReport { missingRequirementIds: string[] } -/** @stable */ +/** Strip PII and large blobs from a `KnowledgeReadinessReport` for safe telemetry emission. @stable */ export function sanitizeKnowledgeReadinessReport( report: KnowledgeReadinessReport, options: RuntimeTelemetryOptions = {}, @@ -101,7 +101,7 @@ export function sanitizeKnowledgeReadinessReport( } } -/** @stable */ +/** Reduce an `AgentRuntimeEvent` to a PII-safe, serializable plain object for telemetry. @stable */ export function sanitizeAgentRuntimeEvent< TState, TAction, @@ -157,7 +157,7 @@ export function sanitizeAgentRuntimeEvent< return { ...base, status: event.status, reason: event.reason } } -/** @stable */ +/** Reduce a `RuntimeStreamEvent` to a PII-safe, serializable plain object for telemetry. @stable */ export function sanitizeRuntimeStreamEvent( event: RuntimeStreamEvent, options: RuntimeTelemetryOptions = {}, @@ -527,7 +527,7 @@ export interface RuntimeStreamEventCollector { summary(): RuntimeStreamEventSummary } -/** @stable */ +/** Build an in-memory collector that sanitizes and accumulates `AgentRuntimeEvent`s for inspection. @stable */ export function createRuntimeEventCollector< TState = unknown, TAction = unknown, diff --git a/src/sessions.ts b/src/sessions.ts index 8f43e2a8..fedcdb85 100644 --- a/src/sessions.ts +++ b/src/sessions.ts @@ -37,7 +37,7 @@ export function nowIso(): string { return new Date().toISOString() } -/** @stable */ +/** In-memory `RuntimeSessionStore` for single-process use and tests. @stable */ export class InMemoryRuntimeSessionStore implements RuntimeSessionStore { private readonly sessions = new Map() private readonly events = new Map() diff --git a/src/sse.ts b/src/sse.ts index 8ede945a..1f2df0ac 100644 --- a/src/sse.ts +++ b/src/sse.ts @@ -38,7 +38,7 @@ export function encodeServerSentEvent(data: unknown, options: ServerSentEventOpt return `${lines.join('\n')}\n\n` } -/** @stable */ +/** Serialize a `KnowledgeReadinessReport` as a Server-Sent Event string. @stable */ export function readinessServerSentEvent( report: KnowledgeReadinessReport, options: RuntimeTelemetryOptions & ServerSentEventOptions = {}, @@ -53,7 +53,7 @@ export function readinessServerSentEvent( ) } -/** @stable */ +/** Serialize a `RuntimeStreamEvent` as a Server-Sent Event string. @stable */ export function runtimeStreamServerSentEvent( event: RuntimeStreamEvent, options: RuntimeTelemetryOptions & ServerSentEventOptions = {},