@titan-design/agent 0.2.0 → 0.4.0

package/README.md

@@ -5,8 +5,8 @@ typed failure. A thin wrapper over the Claude Agent SDK's `query()` that adds th
 three things a production caller always has to add itself: a scrubbed child
 environment, mandatory circuit breakers, and a failure taxonomy you can branch on.
 
-Tier 1 of the titan-platform DAG (TP-11). Depends on
-`@anthropic-ai/claude-agent-sdk`; `zod` is a peer (v4).
+Tier 1 of the titan-platform DAG (TP-11). Depends on `@titan-design/agent-protocol`,
+`@titan-design/agent-lifecycle`, and `@anthropic-ai/claude-agent-sdk`; `zod` is a peer (v4).
 
 ## Run an agent
 
@@ -59,7 +59,9 @@ result to `options.env`. It never mutates its argument and never reads
 
 Two guards sit either side of the run. `assertAuthEnvOk` is the pre-flight: it
 refuses to start when the OAuth token is missing, or when a metered credential
-survived the scrub. The post-flight reads `apiKeySource` off the first
+survived the scrub. The claude-print harness passes `requireOAuthToken: false`,
+because the CLI's keychain login is its credential; the metered-credential check
+still applies. The post-flight reads `apiKeySource` off the first
 `system/init` message and ends the run as `auth_misconfigured` if it names the
 env API-key path. That check is a **blacklist**, not a whitelist: the SDK's
 `ApiKeySource` union grows over time, and an unknown new member is far more
@@ -104,8 +106,10 @@ with the total zeroed.
 ## Subagents and permissions
 
 `agents`, `mcpServers`, `hooks`, `allowedTools`, `disallowedTools`, `model`,
-`resumeSessionId` and `settingSources` pass straight through. Two defaults are
-chosen for headless safety:
+`resumeSessionId` and `settingSources` pass straight through. So do `tools`,
+the built-in tool set (`[]` runs with no tools, for a pure judgement call), and
+`systemPrompt`, which replaces the Claude Code default prompt. Leaving either
+unset keeps the SDK default. Two defaults are chosen for headless safety:
 
 - `permissionMode` defaults to `"dontAsk"`, so nothing runs that was not
   pre-approved.
@@ -120,6 +124,50 @@ says. Prefer `allowedTools` wildcards over a permissive mode.
 This package runs one session. It does not pool, schedule, or retry; that
 belongs to the workflow tier.
 
+## The claude-print harness
+
+`harness: "claude-print"` makes `runAgent` spawn the `claude` CLI in print mode
+instead of calling the SDK. Use it for one-turn structured answers, such as a
+triage or judgement step, on a machine where the CLI is already logged in. The
+CLI's own keychain login is the credential, so `CLAUDE_CODE_OAUTH_TOKEN` is not
+required. `harness` defaults to `"claude-code"`, and the SDK path is unchanged.
+
+```ts
+const result = await runAgent({
+  harness: "claude-print",
+  model: "sonnet",
+  prompt: "Is this diff a refactor? Answer as JSON.",
+  outputSchema: z.object({ refactor: z.boolean() }),
+  cwd: process.cwd(),
+  maxTurns: 1,
+  maxBudgetUsd: 0.5,
+});
+```
+
+| Aspect | claude-print behaviour |
+|---|---|
+| Binary | `CLAUDE_BIN`, else the first executable file named `claude` on the scrubbed env's `PATH`; never a shell function or alias |
+| Fixed flags | `-p --output-format json --tools "" --strict-mcp-config --mcp-config '{"mcpServers":{}}' --setting-sources "" --max-turns 1 --max-budget-usd <maxBudgetUsd>` |
+| Prompt | written to stdin, so large prompts avoid the argv size cap |
+| `model` | `--model <model>` |
+| `systemPrompt` | `--system-prompt <text>`, which replaces the default Claude Code prompt |
+| `outputSchema` | `--json-schema <schema>` without the `$schema` header, which the CLI rejects; `structured_output` is then re-parsed with the zod schema and a mismatch is `schema_invalid` |
+| `inactivityTimeoutMs` | a wall deadline, because JSON output arrives only at the end; SIGTERM to the process group, then SIGKILL after `CLAUDE_PRINT_KILL_GRACE_MS` |
+| `signal` | kills the process group the same way and returns `aborted` |
+| `allowApiKeyBilling` | same scrub as the SDK path: `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` are stripped unless it is set |
+| Result | the JSON result has the SDK result-message shape, so `classifyResult` and `usageFromResult` apply unchanged; `onMessage` receives that one message |
+| `init` | only `model` is known, taken from `modelUsage`; the JSON output carries no init message, so there is no `apiKeySource` post-flight |
+| Logged-out CLI | an error result that says to log in becomes `auth_misconfigured` |
+| Rejected options | `tools` (other than `[]`), `allowedTools`, `disallowedTools`, `permissionMode`, `resumeSessionId`, `agents`, `mcpServers`, `hooks` and a non-empty `settingSources` throw a `TypeError` before anything spawns |
+
+`claudePrintCapabilities()` reports the same limits in the shared capability
+vocabulary: fresh runs, structured output, external cancellation and token
+reporting are supported; resume, tools and every interactive capability are not.
+There is no `HarnessAdapter<"claude-print">` yet, so `dispatchHarnessRun` and the
+durable dispatcher cannot use it; claude-print is selectable only through `runAgent`.
+Without `systemPrompt` the default Claude Code prompt costs about 7,600 input
+tokens per call. A short `systemPrompt` brings that down to about 1,000.
+
 ## Explicit multi-harness contracts
 
 `dispatchHarnessRun(request, adapter)` is the new, explicit contract for Claude

package/dist/index.d.ts

@@ -1,123 +1,13 @@
 import { PermissionMode, AgentDefinition, McpServerConfig, HookEvent, HookCallbackMatcher, SettingSource, SDKMessage, ModelUsage, query, SDKResultMessage } from '@anthropic-ai/claude-agent-sdk';
-import { ZodError, ZodType } from 'zod';
+import { ZodType, ZodError } from 'zod';
 import { ConversationIdentity, ExecutionIdentity, UsageMeasurement, ExecutionRecord, ExecutionTerminal, AgentIdentity, ExecutionReconcileOutcome } from '@titan-design/agent-protocol';
 import { ExecutionLedger } from '@titan-design/agent-lifecycle';
 
-/** Why a run ended without a usable answer. One kind per recovery strategy. */
-type AgentFailure = {
-    kind: "rate_limited";
-    reason: string;
-    retryAt?: Date;
-    raw?: unknown;
-} | {
-    kind: "budget_exceeded";
-    reason: string;
-    raw?: unknown;
-} | {
-    kind: "schema_invalid";
-    reason: string;
-    error?: ZodError;
-    raw?: unknown;
-} | {
-    kind: "max_turns";
-    reason: string;
-    raw?: unknown;
-} | {
-    kind: "refusal";
-    reason: string;
-    raw?: unknown;
-} | {
-    kind: "auth_misconfigured";
-    reason: string;
-    hint?: string;
-    raw?: unknown;
-} | {
-    kind: "runtime_error";
-    reason: string;
-    raw?: unknown;
-} | {
-    kind: "aborted";
-    reason: string;
-} | {
-    kind: "inactivity_timeout";
-    reason: string;
-    timeoutMs: number;
-};
-type AgentFailureKind = AgentFailure["kind"];
-/** What the first `system/init` message told us about the session we actually got. */
-interface AgentInit {
-    apiKeySource: string | undefined;
-    model: string | undefined;
-    tools: string[];
-    permissionMode: string | undefined;
-    claudeCodeVersion: string | undefined;
-}
-/**
- * Client-side estimates. The SDK prices from a bundled table, so treat these as
- * a budget signal and never as a billing statement.
- */
-interface AgentUsage {
-    totalCostUsd: number;
-    modelUsage: Record<string, ModelUsage>;
-    turns: number;
-    durationMs: number;
-}
-interface AgentRunConfig<T = string> {
-    prompt: string;
-    cwd: string;
-    /** Required: the SDK's own default is unlimited. Must be positive. */
-    maxTurns: number;
-    /** Required: the SDK's own default is unlimited. Must be positive. */
-    maxBudgetUsd: number;
-    model?: string;
-    /** Turns on the SDK's `json_schema` output format, which retries on its own until the answer validates. */
-    outputSchema?: ZodType<T>;
-    allowedTools?: string[];
-    disallowedTools?: string[];
-    /** Defaults to `dontAsk`: nothing is pre-approved, so nothing runs unprompted. */
-    permissionMode?: PermissionMode;
-    resumeSessionId?: string;
-    agents?: Record<string, AgentDefinition>;
-    mcpServers?: Record<string, McpServerConfig>;
-    hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
-    signal?: AbortSignal;
-    /** Ends the run when no message arrives for this long. Defaults to 600_000. */
-    inactivityTimeoutMs?: number;
-    /** Keeps `ANTHROPIC_API_KEY` in the child env and bills the API account. */
-    allowApiKeyBilling?: boolean;
-    /** Defaults to `[]`: nothing is read off the filesystem unless asked for. */
-    settingSources?: SettingSource[];
-    onMessage?: (message: SDKMessage) => void;
-}
-type AgentRunResult<T = string> = {
-    ok: true;
-    output: T;
-    sessionId: string;
-    usage: AgentUsage;
-    init: AgentInit;
-} | {
-    ok: false;
-    failure: AgentFailure;
-    sessionId?: string;
-    usage?: AgentUsage;
-};
-
-declare const DEFAULT_INACTIVITY_MS = 600000;
-interface AgentRunDeps {
-    /** Injection seam for tests; defaults to the SDK's own `query`. */
-    query?: typeof query;
-    /** Base environment to scrub; defaults to `process.env`. */
-    env?: NodeJS.ProcessEnv;
-    now?: () => number;
-}
-/**
- * Run one headless Claude Code session to completion and return either its
- * answer or a typed failure. Never throws for anything the agent does; the only
- * throws are caller mistakes caught before the session starts.
- */
-declare function runAgent<T = string>(config: AgentRunConfig<T>, deps?: AgentRunDeps): Promise<AgentRunResult<T>>;
-
 type Harness = "claude-code" | "codex";
+/** Harnesses `runAgent` can drive. `claude-print` is headless `claude -p` on the CLI's own login. */
+type AgentRunHarness = "claude-code" | "claude-print";
+/** `AgentRunConfig` fields claude-print cannot honour: it runs one turn with no tools, hooks, MCP or resume. */
+declare const CLAUDE_PRINT_UNSUPPORTED_OPTIONS: readonly ["allowedTools", "disallowedTools", "permissionMode", "resumeSessionId", "agents", "mcpServers", "hooks"];
 declare const CODEX_SANDBOXES: readonly ["read-only", "workspace-write", "danger-full-access"];
 declare const CODEX_APPROVAL_POLICIES: readonly ["untrusted", "on-failure", "on-request", "never"];
 type CodexSandbox = (typeof CODEX_SANDBOXES)[number];
@@ -148,7 +38,7 @@ interface LimitCapability {
     assessment: CapabilityAssessment;
 }
 /** A factual report supplied by an adapter implementation, not a promise made by the core. */
-interface HarnessCapabilityDescriptor<H extends Harness = Harness> {
+interface HarnessCapabilityDescriptor<H extends string = Harness> {
     harness: H;
     adapter: {
         name: string;
@@ -318,6 +208,133 @@ interface HarnessAdapter<H extends Harness> {
     run<T>(request: HarnessRunRequestFor<H, T>): Promise<HarnessRunResult<T, H>>;
 }
 
+/** Why a run ended without a usable answer. One kind per recovery strategy. */
+type AgentFailure = {
+    kind: "rate_limited";
+    reason: string;
+    retryAt?: Date;
+    raw?: unknown;
+} | {
+    kind: "budget_exceeded";
+    reason: string;
+    raw?: unknown;
+} | {
+    kind: "schema_invalid";
+    reason: string;
+    error?: ZodError;
+    raw?: unknown;
+} | {
+    kind: "max_turns";
+    reason: string;
+    raw?: unknown;
+} | {
+    kind: "refusal";
+    reason: string;
+    raw?: unknown;
+} | {
+    kind: "auth_misconfigured";
+    reason: string;
+    hint?: string;
+    raw?: unknown;
+} | {
+    kind: "runtime_error";
+    reason: string;
+    raw?: unknown;
+} | {
+    kind: "aborted";
+    reason: string;
+} | {
+    kind: "inactivity_timeout";
+    reason: string;
+    timeoutMs: number;
+};
+type AgentFailureKind = AgentFailure["kind"];
+/** What the first `system/init` message told us about the session we actually got. */
+interface AgentInit {
+    apiKeySource: string | undefined;
+    model: string | undefined;
+    tools: string[];
+    permissionMode: string | undefined;
+    claudeCodeVersion: string | undefined;
+}
+/**
+ * Client-side estimates. The SDK prices from a bundled table, so treat these as
+ * a budget signal and never as a billing statement.
+ */
+interface AgentUsage {
+    totalCostUsd: number;
+    modelUsage: Record<string, ModelUsage>;
+    turns: number;
+    durationMs: number;
+}
+interface AgentRunConfig<T = string> {
+    /** Defaults to `claude-code` (the SDK). `claude-print` spawns `claude -p` and needs no `CLAUDE_CODE_OAUTH_TOKEN`. */
+    harness?: AgentRunHarness;
+    prompt: string;
+    cwd: string;
+    /** Required: the SDK's own default is unlimited. Must be positive. */
+    maxTurns: number;
+    /** Required: the SDK's own default is unlimited. Must be positive. */
+    maxBudgetUsd: number;
+    model?: string;
+    /** Turns on the SDK's `json_schema` output format, which retries on its own until the answer validates. */
+    outputSchema?: ZodType<T>;
+    /** The built-in tool set; `[]` runs with no tools at all. Omitted keeps the SDK default. */
+    tools?: string[];
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    /** Replaces the SDK's default Claude Code system prompt. */
+    systemPrompt?: string;
+    /** Defaults to `dontAsk`: nothing is pre-approved, so nothing runs unprompted. */
+    permissionMode?: PermissionMode;
+    resumeSessionId?: string;
+    agents?: Record<string, AgentDefinition>;
+    mcpServers?: Record<string, McpServerConfig>;
+    hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+    signal?: AbortSignal;
+    /** Ends the run when no message arrives for this long. Defaults to 600_000. */
+    inactivityTimeoutMs?: number;
+    /** Keeps `ANTHROPIC_API_KEY` in the child env and bills the API account. */
+    allowApiKeyBilling?: boolean;
+    /** Defaults to `[]`: nothing is read off the filesystem unless asked for. */
+    settingSources?: SettingSource[];
+    onMessage?: (message: SDKMessage) => void;
+}
+type AgentRunResult<T = string> = {
+    ok: true;
+    output: T;
+    sessionId: string;
+    usage: AgentUsage;
+    init: AgentInit;
+} | {
+    ok: false;
+    failure: AgentFailure;
+    sessionId?: string;
+    usage?: AgentUsage;
+};
+
+declare const DEFAULT_INACTIVITY_MS = 600000;
+interface AgentRunDeps {
+    /** Injection seam for tests; defaults to the SDK's own `query`. */
+    query?: typeof query;
+    /** Base environment to scrub; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+}
+/**
+ * Run one headless Claude Code session to completion and return either its
+ * answer or a typed failure. Never throws for anything the agent does; the only
+ * throws are caller mistakes caught before the session starts.
+ */
+declare function runAgent<T = string>(config: AgentRunConfig<T>, deps?: AgentRunDeps): Promise<AgentRunResult<T>>;
+
+/** SIGTERM alone has been ignored by the CLI in the repo-review pipeline, so SIGKILL follows. */
+declare const CLAUDE_PRINT_KILL_GRACE_MS = 5000;
+declare function claudePrintCapabilities(): HarnessCapabilityDescriptor<"claude-print">;
+/** The first executable file named `claude` on PATH, never a shell function or alias. `CLAUDE_BIN` wins. */
+declare function resolveClaudeBin(env: Record<string, string>): string | undefined;
+declare function buildClaudePrintArgs(config: AgentRunConfig<unknown>): string[];
+
 declare function preflightHarnessRun<H extends Harness, T>(request: HarnessRunRequestFor<H, T>, descriptor: HarnessCapabilityDescriptor<H>): HarnessRunFailure | undefined;
 declare function dispatchHarnessRun<H extends Harness, T>(request: HarnessRunRequestFor<H, T>, adapter: HarnessAdapter<H>): Promise<HarnessRunResult<T, H>>;
 
@@ -414,6 +431,10 @@ interface PrepareEnvOptions {
     /** Leave `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` in place and bill the API account. */
     allowApiKeyBilling?: boolean;
 }
+interface AuthEnvCheckOptions extends PrepareEnvOptions {
+    /** Defaults to true. The claude-print harness sets it false: the CLI's own keychain login is its credential. */
+    requireOAuthToken?: boolean;
+}
 declare class AuthMisconfiguredError extends Error {
     readonly hint: string | undefined;
     constructor(message: string, hint?: string);
@@ -428,7 +449,7 @@ declare function prepareEnv(env?: NodeJS.ProcessEnv, options?: PrepareEnvOptions
  * Pre-flight the scrubbed env so a misrouted run fails before it spends
  * anything, rather than mid-stream with a surprise billing source.
  */
-declare function assertAuthEnvOk(env: Record<string, string>, options?: PrepareEnvOptions): void;
+declare function assertAuthEnvOk(env: Record<string, string>, options?: AuthEnvCheckOptions): void;
 /**
  * Credential sources that mean the run went to metered API billing. A blacklist,
  * not a whitelist: the SDK's `ApiKeySource` union grows, and an unrecognised new
@@ -521,4 +542,4 @@ interface ClaudeCodeAdapterOptions {
 declare function createClaudeCodeAdapter(options: ClaudeCodeAdapterOptions): HarnessAdapter<"claude-code">;
 declare function claudeCodeCapabilities(): HarnessCapabilityDescriptor<"claude-code">;
 
-export { ANTI_NESTING_VARS, type AgentFailure, type AgentFailureKind, type AgentInit, type AgentRunConfig, type AgentRunDeps, type AgentRunResult, type AgentUsage, AuthMisconfiguredError, type BoundedRunBase, CLAUDE_CODE_PASSTHROUGH_VARS, CODEX_APPROVAL_POLICIES, CODEX_SANDBOXES, type CapabilityAssessment, type ClassifyOptions, type ClaudeCodeAdapterOptions, type ClaudeCodeNativeOptions, type ClaudeCodeRunRequest, type CodexApprovalPolicy, type CodexExecAdapterOptions, type CodexExecDeps, type CodexNativeOptions, type CodexOutputSchema, type CodexProcessExit, type CodexProcessInput, type CodexRunRequest, type CodexSandbox, type CodexSchemaFile, type CodexVersionInspectionOptions, DEFAULT_CODEX_EXECUTABLE, DEFAULT_CODEX_KILL_GRACE_MS, DEFAULT_INACTIVITY_MS, DEFAULT_MAX_RETRIES, type DurableCancelResult, type DurableDispatchAck, type DurableDispatchInput, type DurableHarnessDispatcher, type DurableHarnessDispatcherDeps, type DurableHarnessDispatcherOptions, type DurableHarnessRecord, type DurableHarnessSuccess, type DurableLiveHandle, type DurableReconcileOutcome, type DurableSettlement, EXECUTION_CAPABILITIES, type ExecutionCapability, type ExecutionLimit, FORBIDDEN_API_KEY_SOURCES, type Harness, type HarnessAdapter, type HarnessCapabilityDescriptor, type HarnessRunFailure, type HarnessRunOutput, type HarnessRunProgress, type HarnessRunRequest, type HarnessRunRequestFor, type HarnessRunResult, type LimitCapability, type LimitEnforcement, type LimitScope, type LimitUnit, type OptionalLimitUnit, type PrepareEnvOptions, type RunTarget, STRIPPED_AUTH_VARS, STRIPPED_CODEX_AUTH_VARS, STRIPPED_PROXY_VARS, SUPPORTED_CODEX_EXEC_VERSION, type SupervisedCodexProcess, type TranscriptSourceHint, assertApiKeySourceAllowed, assertAuthEnvOk, buildCodexExecArgs, classifyResult, claudeCodeCapabilities, codexExecCapabilities, createClaudeCodeAdapter, createCodexExecAdapter, createDurableHarnessDispatcher, dispatchHarnessRun, preflightHarnessRun, prepareCodexEnv, prepareEnv, runAgent, sumModelCost, usageFromResult };
+export { ANTI_NESTING_VARS, type AgentFailure, type AgentFailureKind, type AgentInit, type AgentRunConfig, type AgentRunDeps, type AgentRunHarness, type AgentRunResult, type AgentUsage, type AuthEnvCheckOptions, AuthMisconfiguredError, type BoundedRunBase, CLAUDE_CODE_PASSTHROUGH_VARS, CLAUDE_PRINT_KILL_GRACE_MS, CLAUDE_PRINT_UNSUPPORTED_OPTIONS, CODEX_APPROVAL_POLICIES, CODEX_SANDBOXES, type CapabilityAssessment, type ClassifyOptions, type ClaudeCodeAdapterOptions, type ClaudeCodeNativeOptions, type ClaudeCodeRunRequest, type CodexApprovalPolicy, type CodexExecAdapterOptions, type CodexExecDeps, type CodexNativeOptions, type CodexOutputSchema, type CodexProcessExit, type CodexProcessInput, type CodexRunRequest, type CodexSandbox, type CodexSchemaFile, type CodexVersionInspectionOptions, DEFAULT_CODEX_EXECUTABLE, DEFAULT_CODEX_KILL_GRACE_MS, DEFAULT_INACTIVITY_MS, DEFAULT_MAX_RETRIES, type DurableCancelResult, type DurableDispatchAck, type DurableDispatchInput, type DurableHarnessDispatcher, type DurableHarnessDispatcherDeps, type DurableHarnessDispatcherOptions, type DurableHarnessRecord, type DurableHarnessSuccess, type DurableLiveHandle, type DurableReconcileOutcome, type DurableSettlement, EXECUTION_CAPABILITIES, type ExecutionCapability, type ExecutionLimit, FORBIDDEN_API_KEY_SOURCES, type Harness, type HarnessAdapter, type HarnessCapabilityDescriptor, type HarnessRunFailure, type HarnessRunOutput, type HarnessRunProgress, type HarnessRunRequest, type HarnessRunRequestFor, type HarnessRunResult, type LimitCapability, type LimitEnforcement, type LimitScope, type LimitUnit, type OptionalLimitUnit, type PrepareEnvOptions, type RunTarget, STRIPPED_AUTH_VARS, STRIPPED_CODEX_AUTH_VARS, STRIPPED_PROXY_VARS, SUPPORTED_CODEX_EXEC_VERSION, type SupervisedCodexProcess, type TranscriptSourceHint, assertApiKeySourceAllowed, assertAuthEnvOk, buildClaudePrintArgs, buildCodexExecArgs, classifyResult, claudeCodeCapabilities, claudePrintCapabilities, codexExecCapabilities, createClaudeCodeAdapter, createCodexExecAdapter, createDurableHarnessDispatcher, dispatchHarnessRun, preflightHarnessRun, prepareCodexEnv, prepareEnv, resolveClaudeBin, runAgent, sumModelCost, usageFromResult };