agent-tempo 1.0.1

package/dist/adapters/claude-api/adapter.d.ts

@@ -0,0 +1,168 @@
+import type { AdapterDescriptor } from '../../types';
+import { SdkAttachment, type SdkDeliverResult } from '../sdk/base';
+import type { Message as TempoMessage, SentMessage } from '../../types';
+/**
+ * Descriptor for the claude-api adapter. Kept colocated with the class so
+ * `adapter.ts` has no import dependency on `index.ts` (breaks the circular
+ * module-graph cycle that QA flagged on copilot's PR-B). `index.ts` re-exports
+ * this constant alongside the class.
+ *
+ * Design reference: docs/design/131-claude-api-adapter.md §2 + ADR 0012.
+ */
+export declare const claudeApiDescriptor: AdapterDescriptor;
+/**
+ * SDK-class adapter for the Anthropic Messages API.
+ *
+ * Delivery model is pull-based (blocks on LLM turn): the adapter polls the
+ * workflow for pending messages, runs a tool-use loop against the Messages
+ * API (commit 4), and acks via `markDelivered`. `processingStart`/`End`
+ * are paired around each blocking turn so the workflow's stale detection
+ * doesn't misclassify a long tool-call sequence as a dead session.
+ */
+export declare class DirectApiAttachment extends SdkAttachment {
+    readonly descriptor: AdapterDescriptor;
+    /** AbortController stashed during invokeSdk so onSuperseded can abort the in-flight stream. */
+    private abortController;
+    /** In-process MCP bridge — server + client + cached tool list. Populated by run(). */
+    private mcp;
+    /** Anthropic SDK client (typed `unknown` because the SDK is an optional dep). Populated by run(). */
+    private apiClient;
+    /** Resolved model id (recruit-arg → env → DEFAULT_MODEL). */
+    private model;
+    /** Cached system prompt — built once at session start, stays in the cached prefix every turn. */
+    private systemPrompt;
+    /** Player id stashed for the per-turn telemetry log. */
+    private playerName;
+    constructor(opts?: {
+        model?: string;
+    });
+    /**
+     * Lease-revocation hook — fired by `SdkAttachment` when the base-class
+     * phase watcher detects another claimant stole the attachment. Aborts the
+     * in-flight `messages.create` via the AbortController wired in
+     * `invokeSdk`. Concrete abort wiring lands in commit 4.
+     */
+    protected onSuperseded(): void;
+    /**
+     * Subprocess entry point. Boots the in-process MCP bridge, connects to
+     * Temporal, claims the attachment via V2 lifecycle, and runs the poll loop.
+     */
+    run(): Promise<void>;
+    /**
+     * Poll the workflow for pending messages, drive each one through
+     * `SdkAttachment.deliver()`. Mirrors the Copilot bridge's loop shape;
+     * the LLM call lives in `invokeSdk` (commit 4).
+     *
+     * Periodic workflow-status checks detect external termination /
+     * destroy and exit cleanly so the daemon doesn't accumulate zombie
+     * adapter processes after a `destroy` from another player.
+     */
+    private pollLoop;
+    /**
+     * Whether the adapter should stop polling — true once `onTerminal` has
+     * fired (which sets `shuttingDown` indirectly via cleanup). The flag
+     * lives in cleanup's closure scope, so we read terminal state via the
+     * base class instead. `BaseAttachment` exposes lifecycle state via
+     * `this.token` — null after lease loss or graceful detach.
+     */
+    private shouldStop;
+    /**
+     * Concrete LLM-turn invocation. Rebuilds conversation state from workflow
+     * queries, calls `messages.create({ stream: true })` in a tool-use loop,
+     * dispatches tool calls through the in-process MCP bridge, and exits when
+     * the model signals `end_turn` / `max_tokens` / context overflow.
+     *
+     * Verification-addendum landmines applied here:
+     *   - **§2.1 thinking-block round-trip**: assistant turns push the FULL
+     *     content array (thinking + tool_use blocks together) so the
+     *     signature chain stays intact between sub-turns of the loop.
+     *   - **§2.2 Opus 4.7 param discipline**: no `temperature`, `top_p`,
+     *     `top_k`, or `thinking.budget_tokens` on the request body. We don't
+     *     set `thinking` at all — Opus 4.7 defaults to adaptive-omitted.
+     *   - **§2.3 cache breakpoints**: `cache_control: { type: 'ephemeral' }`
+     *     on the LAST system block and the LAST tool definition (2 of 4
+     *     breakpoints used; the marker tells the server where the cached
+     *     prefix ENDS, not where it starts).
+     *   - **§2.4 input_json_delta**: tool_use input accumulates as a string
+     *     and is only `JSON.parse`'d at `content_block_stop`.
+     *   - **§2.5 mid-stream errors**: the `for await` loop is wrapped in
+     *     try/catch; thrown errors propagate up so `SdkAttachment.deliver`'s
+     *     `finally` fires `processingEnd` and the message stays PENDING for
+     *     the next poll's retry. No turn-level retry inside the adapter
+     *     (avoids double-execution of side-effecting tool calls).
+     */
+    protected invokeSdk(_prompt: string, _timeoutMs: number): Promise<SdkDeliverResult>;
+    /**
+     * Emit a workflow-side message recommending `save_state` + `restart`
+     * when Anthropic returns `stop_reason: 'model_context_window_exceeded'`.
+     * Design §5.5 — auto-compact via #334 deferred to Phase 2.
+     */
+    private deliverContextOverflowMessage;
+}
+interface AnthropicStreamEvent {
+    type: string;
+    index?: number;
+    delta?: {
+        type?: string;
+        text?: string;
+        partial_json?: string;
+        thinking?: string;
+        signature?: string;
+        stop_reason?: string;
+    };
+    content_block?: {
+        type: string;
+        text?: string;
+        id?: string;
+        name?: string;
+        input?: unknown;
+        thinking?: string;
+    };
+    message?: {
+        usage?: Record<string, number>;
+    };
+    usage?: Record<string, number>;
+}
+interface AssistantTextBlock {
+    type: 'text';
+    text: string;
+}
+interface AssistantToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: string;
+}
+interface AssistantThinkingBlock {
+    type: 'thinking';
+    thinking: string;
+    signature?: string;
+}
+type AssistantContentBlock = AssistantTextBlock | AssistantToolUseBlock | AssistantThinkingBlock;
+/**
+ * Reduce one `MessageStreamEvent` into the assistant content-block array.
+ * Mutates `blocks` in place; same `index` slots map to the same block so
+ * interleaved deltas land in the right bucket. Tool input accumulates as
+ * a string per verification §2.4 (parsed only by the caller, after
+ * `content_block_stop`).
+ */
+export declare function handleStreamEvent(event: AnthropicStreamEvent, blocks: AssistantContentBlock[]): void;
+/**
+ * Merge workflow `Message[]` (received from others) + `SentMessage[]`
+ * (sent by this player) into the Anthropic Messages API array.
+ *
+ *   - Sort chronologically by `timestamp`
+ *   - `received` → `role: 'user'`, `sent` → `role: 'assistant'`
+ *   - Fold consecutive same-role rows into one message (Anthropic requires
+ *     strict user/assistant alternation; multiple cues stacking into the
+ *     player's queue must collapse to a single user turn)
+ *   - Tag each row with the originator (`[from: <name>]`) on user side so
+ *     the model can disambiguate when several players are talking
+ *
+ * Exported for unit testing (commit 5).
+ */
+export declare function buildAnthropicMessages(received: TempoMessage[], sent: SentMessage[]): Array<{
+    role: 'user' | 'assistant';
+    content: string;
+}>;
+export {};