@khorsheed/dsh-local-agent-claude-code 0.2.0-rc.1 → 0.2.0

package/lib/types/claude-cli-provider.d.ts

@@ -14,7 +14,7 @@
  * loud, by design).
  * @module @khorsheed/dsh-local-agent-claude-code/claude-cli-provider
  */
-import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { ContentBlock, ReasoningEffortId, TokenUsage } from '@deepseek-ai/dsh-llm';
 import type { TodoItem } from '@deepseek-ai/dsh-tool-todo';
 import { type ResolvedSubagentStartRequest, type SubagentCapabilities, type SubagentProvider, type SubagentRun, type SubagentStartRequest, type SubagentStopReason } from '@deepseek-ai/dsh-subagent';
 import type { Context } from '@deepseek-ai/cordis';
@@ -22,14 +22,31 @@ import type { Session } from '@deepseek-ai/dsh-session';
 import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
 import type { DelegationExecTarget, LocalAgentToolCalls } from '@khorsheed/dsh-local-agent/types';
 import type { ClaudeLiveDriver } from './live-driver.ts';
+import type { ClaudeEndpointAuth } from './endpoint-auth.ts';
+/**
+ * The synthesized result for a call whose result the stream never recorded
+ * (a settle-pass fold after a kill or a truncated stream). The released-log
+ * contract resolves every advertised call before its step closes, so an
+ * interrupted call folds with this error result. Shared verbatim with the
+ * kimi provider (`KIMI_INTERRUPTED_TOOL_RESULT`) so the family reads one text.
+ */
+export declare const CLAUDE_INTERRUPTED_TOOL_RESULT = "\uFF08\u5DE5\u5177\u8C03\u7528\u88AB\u4E2D\u65AD\uFF0C\u672A\u80FD\u8BB0\u5F55\u8FD4\u56DE\u7ED3\u679C\uFF09";
 /** Default POSIX grace between subprocess termination tiers. */
 export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
 /**
  * Auth-shaped failure signatures in claude's result error or stderr: the
- * endpoint rejected the credential (401/403, revoked token). Narrow on
- * purpose — matched against provider-controlled error strings only.
+ * endpoint rejected the credential (401/403, revoked key). Matches the CLI's
+ * own phrasing ("Failed to authenticate. API Error: 401 …", the
+ * `authentication_failed` error tag) plus the relay phrasings seen in the
+ * wild ("invalid x-api-key" and friends). Narrow on purpose — matched against
+ * provider-controlled error strings only.
  */
 export declare const CLAUDE_AUTH_FAILURE: RegExp;
+/**
+ * The MCP tool-call bound for a member's claude process (`MCP_TOOL_TIMEOUT`,
+ * ms): a bridge call may wait up to 30 minutes for the human's answer.
+ */
+export declare const MEMBER_TOOL_TIMEOUT_MS: string;
 /**
  * Member channel registration for one claude process lifetime: mint the
  * per-run token and build the bridge MCP declaration for the spawn argv
@@ -62,7 +79,7 @@ export declare function claudeCliVersion(ctx: Context, homeDir: string): Promise
 export declare class ClaudeCliProvider implements SubagentProvider {
     private readonly ctx;
     private readonly permissionMode;
-    private readonly baseUrl?;
+    private readonly endpoint?;
     private readonly live?;
     private readonly model?;
     readonly name = "claude-local";
@@ -73,6 +90,11 @@ export declare class ClaudeCliProvider implements SubagentProvider {
      *   generation's driver per member (the settings toggle swaps generations;
      *   a resolver may return undefined to steer one member's round to exec
      *   while a retiring generation still hosts it).
+     * @param endpoint - resolver for the round's endpoint credential (endpoint-auth.ts:
+     *   the scope's endpoint-auth.json over the plugin config triple), read PER
+     *   ROUND against the round's scoped home, so a key rotation or a profile
+     *   edit takes effect on the next delegation without a reload. Absent, no
+     *   `ANTHROPIC_*` variables reach the child at all.
      * @param model - resolver for the member's effective model, read PER ROUND
      *   so a settings-card write or a composer switch takes effect on the next
      *   delegation without a reload. Receives the member (the child session id)
@@ -81,7 +103,7 @@ export declare class ClaudeCliProvider implements SubagentProvider {
      *   resolver not passed), the delegation's own model still rides, exactly
      *   as before the key existed.
      */
-    constructor(ctx: Context, permissionMode?: 'skip' | 'normal', baseUrl?: string | undefined, live?: ClaudeLiveDriver | ((childSessionId: string) => ClaudeLiveDriver | undefined) | undefined, model?: ((childSessionId: string, delegationModel?: string) => string | undefined) | undefined);
+    constructor(ctx: Context, permissionMode?: 'skip' | 'normal', endpoint?: ((homeDir: string) => Promise<ClaudeEndpointAuth>) | undefined, live?: ClaudeLiveDriver | ((childSessionId: string) => ClaudeLiveDriver | undefined) | undefined, model?: ((childSessionId: string, delegationModel?: string) => string | undefined) | undefined);
     /** Resolve the live driver for one round's member, if live is on for it. */
     private liveDriver;
     /** The round's model fragment for the exec spawn spec (see {@link resolveRoundModel}). */
@@ -202,16 +224,25 @@ export type ClaudeTranscriptLine = {
     kind: 'think';
     text: string;
     streamId?: string;
+    messageId?: string;
+    usage?: TokenUsage;
 } | {
     kind: 'text';
     text: string;
     streamId?: string;
+    messageId?: string;
+    usage?: TokenUsage;
 }
 /**
  * Tool activity: one `tool_use` with its (possibly still pending)
  * `tool_result`. `id` is the stream's tool_use id when present, else a
  * synthesized position-based id — stable within a run either way, so the
- * child session's `tool/call`/`tool/result` events pair by it.
+ * child session's `tool/call`/`tool/result` events pair by it. `usage` is
+ * the API call's own accounting (claude reports it inline on every
+ * assistant event): it rides the call's LAST folded line — a tool-only
+ * call's lands on the tool line's advertising message. `messageId` groups
+ * the per-block events of ONE API call (claude emits one assistant event
+ * per content block, each repeating the message's usage).
  */
  | {
     kind: 'tool';
@@ -219,12 +250,21 @@ export type ClaudeTranscriptLine = {
     name: string;
     args?: string;
     result?: string;
+    messageId?: string;
+    usage?: TokenUsage;
 };
+/** Group the lines of one API call (consecutive lines sharing a message id).
+ * Lines without an id stay singleton units (the pre-grouping shape). */
+export declare function groupClaudeTranscriptLines(lines: readonly ClaudeTranscriptLine[]): ClaudeTranscriptLine[][];
 /** Mutable fold state shared by the batch parse and the incremental parser. */
 interface ClaudeStreamFoldState {
     readonly lines: ClaudeTranscriptLine[];
     /** tool_use id → transcript line index, so a result pairs with its own call. */
     readonly callsById: Map<string, number>;
+    /** message id → the line index its usage currently rides (per-call dedupe:
+     * claude repeats one call's usage on EVERY per-block assistant event, and
+     * only the call's last line may keep it). */
+    readonly usageStamped: Map<string, number>;
     text: string | undefined;
     usage: TokenUsage | undefined;
     sessionId: string | undefined;
@@ -302,6 +342,7 @@ export declare class ClaudeStreamParser implements ClaudeStreamFoldState {
     private buffer;
     readonly lines: ClaudeTranscriptLine[];
     readonly callsById: Map<string, number>;
+    readonly usageStamped: Map<string, number>;
     text: string | undefined;
     usage: TokenUsage | undefined;
     sessionId: string | undefined;
@@ -347,6 +388,17 @@ export declare function parseClaudeStreamJson(output: string): {
 };
 /** The placeholder think line for a `redacted_thinking` block (content is server-encrypted by design). */
 export declare const REDACTED_THINKING_TEXT = "\uFF08\u601D\u8003\u5185\u5BB9\u5DF2\u7531\u670D\u52A1\u7AEF\u9690\u85CF\uFF1Aredacted_thinking\uFF0C\u5185\u5BB9\u6309\u8BBE\u8BA1\u4E0D\u53EF\u89C1\uFF0C\u6B64\u884C\u4EC5\u6807\u793A\u5B83\u5B58\u5728\uFF09";
+/**
+ * Map claude's usage payload onto the shared usage contract. Claude's
+ * `input_tokens` is the uncached input; cache reads and cache creation are
+ * reported separately, so each maps to its own bucket with no subtraction.
+ * When the payload carries ANY cache field, `cacheReadTokens` is always
+ * written (0 when the read counter is absent or zero) — a reader can then
+ * tell "no hits" from "not reported".
+ * @param usage - the raw claude usage object.
+ * @returns the shared usage record.
+ */
+export declare function usageFromClaude(usage: unknown): TokenUsage;
 /**
  * Start the real `claude -p` child and publish its run. The claude
  * result arrives as an NDJSON event stream on stdout (`--verbose
@@ -362,6 +414,17 @@ export declare const REDACTED_THINKING_TEXT = "\uFF08\u601D\u8003\u5185\u5BB9\u5
  */
 export declare function startClaudeCliRun(request: SubagentStartRequest, spec: ClaudeCliRunSpec): Promise<SubagentRun>;
 /** One assistant-role message event, attributed to the claude route. */
+/**
+ * Write the round's request/header when the config differs from the child
+ * log's last one (the host logs changed snapshots, not per-call duplicates):
+ * the first write is `initial`, a differing one `change`, an identical one
+ * skipped. Context Lens reads the child log's config from these headers.
+ */
+export declare function appendClaudeRequestHeader(childSession: Session, config: {
+    provider: string;
+    model: string;
+    reasoningEffort?: ReasoningEffortId;
+}): void;
 export declare function assistantEvent(blocks: readonly ContentBlock[]): import("@deepseek-ai/dsh-llm").AssistantMessage;
 /**
  * Fold one transcript line into the child session as one assistant step,
@@ -371,10 +434,27 @@ export declare function assistantEvent(blocks: readonly ContentBlock[]): import(
  * the real-time view renders nothing (only a full rebuild, which mints step
  * drafts from the explicit coordinates, recovers it). Tool cards escape that
  * fate only because their definition does not consult the step location.
+ *
+ * A tool line folds the native lifecycle inside its one step: an assistant
+ * message advertising the tool-call block, the `tool/call`, and its
+ * `tool/result` — the released-log reader pairs call and result against the
+ * advertisement and resolves every advertised call before the step closes, so
+ * a line whose result the stream has not recorded yet must NOT reach this
+ * fold mid-round (the callers hold there; the result merges into the call's
+ * line in place, so a later pass sees it). A line still unresulted at settle
+ * folds with the interrupted placeholder ({@link CLAUDE_INTERRUPTED_TOOL_RESULT}).
  */
 export declare function appendClaudeTranscriptLine(childSession: Session, turn: number, step: number, line: ClaudeTranscriptLine, usage: TokenUsage | undefined): void;
 /** The delta-progress text for one transcript line. */
 export declare function claudeLineText(line: ClaudeTranscriptLine): string;
+/**
+ * Fold one API call (a message-id group) into the child session as ONE
+ * assistant step: a single assistant/message carrying the call's reasoning,
+ * text and tool-call blocks (the host's own mixed-content shape), then each
+ * call's native lifecycle, then step/end. The call's usage rides the message
+ * once — the group's own per-call stamp wins over the round-total fallback.
+ */
+export declare function appendClaudeTranscriptGroup(childSession: Session, turn: number, step: number, group: readonly ClaudeTranscriptLine[], usage: TokenUsage | undefined): void;
 /**
  * Persist the child session's mirrored events. Thin wrapper over the core's
  * {@link persistChildSession}: a live session syncs through the core's cached