@yul-labs/agent-relay 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -128,7 +128,9 @@ interface ApiDeciderOptions {
      * Default 2048. Reasoning models emit a long chain-of-thought before the JSON
      * answer, so a too-small cap (e.g. a few hundred) truncates them mid-thought,
      * leaving an empty `content` and an unparseable reply → safe-deny. Raise it
-     * (not lower) for verbose reasoning models.
+     * (not lower) for verbose reasoning models. Values below
+     * {@link MIN_API_MAX_TOKENS} are clamped UP to it — a cap that small can't fit
+     * even the JSON answer once a reasoning model has spent budget on its CoT.
      */
     maxTokens?: number;
     temperature?: number;
@@ -259,6 +261,43 @@ interface AgentRunInput {
     /** Arbitrary extra options interpreted by specific adapters (e.g. fake). */
     options?: Record<string, unknown>;
 }
+/**
+ * Resource usage for a run, exposed under `result.meta.usage`. Every field is
+ * optional. Token counts come from the agent's own session transcript/rollout
+ * JSONL (the AUTHORITATIVE, device-independent source — written on every run
+ * regardless of TUI/status-line settings); `contextPercent` / `sessionCostUsd`
+ * are best-effort extras scraped from the TUI status line when it is enabled.
+ * `source` records which path produced the token figures.
+ */
+interface AgentUsage {
+    /**
+     * Provenance of the token counts: "transcript" = parsed from the agent's
+     * session log (authoritative); "status-line" = scraped from the TUI (only
+     * present when the user has a status line that shows usage). Token fields are
+     * trustworthy only when `source` is "transcript".
+     */
+    source?: "transcript" | "status-line";
+    /** Model id when known, e.g. "claude-opus-4-8". */
+    model?: string;
+    /** Cumulative non-cached input/prompt tokens. */
+    inputTokens?: number;
+    /** Cumulative output/completion tokens. */
+    outputTokens?: number;
+    /** Cumulative tokens served from the prompt cache (cheap reads). */
+    cachedInputTokens?: number;
+    /** Cumulative tokens spent CREATING prompt-cache entries (Claude). */
+    cacheCreationTokens?: number;
+    /** Cumulative reasoning tokens, when the model reports them (Codex / o-series). */
+    reasoningTokens?: number;
+    /** Total tokens (the agent's own total when given, else the sum of the above). */
+    totalTokens?: number;
+    /** Context-window usage as a percent, when surfaced by the status line. */
+    contextPercent?: number;
+    /** Session cost (USD) when the agent reports it; reads 0 on subscription billing. */
+    sessionCostUsd?: number;
+    /** Raw status-line snippet the scraped extras came from (status-line only). */
+    raw?: string;
+}
 /** The terminal result an adapter returns from {@link AgentAdapter.run}. */
 interface AgentRunResult {
     /** Whether the adapter believes the run finished successfully. */
@@ -1289,6 +1328,13 @@ interface PtySessionOptions {
      * think/build is never mistaken for "done".
      */
     workingPattern?: RegExp;
+    /**
+     * Optional per-adapter scrape of the (ANSI-cleaned) screen into structured
+     * usage (tokens / context / cost). Called on each settle; the latest non-empty
+     * result is merged and attached to `result.meta.usage`. Vendor-specific, so the
+     * adapter supplies it — the session loop itself stays vendor-agnostic.
+     */
+    scrapeUsage?: (cleanedText: string) => AgentUsage | undefined;
     /** Keys to send to exit the TUI on completion (e.g. double Ctrl-C). */
     quitKeys?: string;
     /** Optional text to type once the UI is ready (for TUIs needing typed input). */
@@ -1355,6 +1401,13 @@ interface InteractiveAdapterConfig {
     setup?: (input: AgentRunInput) => SetupStep[] | undefined;
     detector?: PromptDetectorOptions;
     keymap?: PtyKeymap;
+    /**
+     * Optional per-adapter scrape of the agent's TUI status line into structured
+     * usage (tokens / context / cost), surfaced as `result.meta.usage`. Heuristic
+     * and vendor-specific, so it lives in the adapter, not the vendor-agnostic
+     * session loop. Omit it for adapters with no parseable status line.
+     */
+    scrapeUsage?: (cleanedText: string) => AgentUsage | undefined;
     completionPattern?: RegExp;
     completionIdleMs?: number;
     /** "Agent is working" indicator that suppresses completion (see PtySession). */
@@ -1387,18 +1440,34 @@ declare class InteractivePtyAdapter implements AgentAdapter {
  * AUTONOMY: by default Claude runs with `--dangerously-skip-permissions` so it
  * acts without per-action prompts. The {@link Decider} still handles the prompts
  * that appear anyway (the directory-trust menu, etc.). `approvalPolicy: "gated"`
- * uses `--permission-mode acceptEdits` so Claude asks more and the decider sees
- * those; `"readonly"` uses `--permission-mode plan`. The prompt is a positional
- * arg so the session starts immediately.
+ * uses `--permission-mode default` — Claude's normal interactive mode where it
+ * ASKS before each edit/command, so those approvals are routed to the decider.
+ * (NOT `acceptEdits`, which silently auto-approves edits and so never consults
+ * the decider on them.) `"readonly"` uses `--permission-mode plan`. The prompt is
+ * a positional arg so the session starts immediately.
  */
 
 interface ClaudeInteractiveOptions {
     command?: string;
     env?: Record<string, string>;
     now?: () => Date;
+    /** Override Claude's projects root (~/.claude/projects) — for tests. */
+    projectsDir?: string;
 }
 declare class ClaudeInteractiveAdapter extends InteractivePtyAdapter {
+    private readonly clock;
+    /** Override the projects root (~/.claude/projects) for tests. */
+    private readonly projectsDir?;
     constructor(opts?: ClaudeInteractiveOptions);
+    /**
+     * Run Claude, then read AUTHORITATIVE token usage from its session transcript
+     * (~/.claude/projects/<cwd>/<id>.jsonl) and surface it as `meta.usage`. This is
+     * device-independent — it works regardless of whether the user has a usage
+     * status line — and overwrites the best-effort status-line scrape's token
+     * figures while keeping its context%/cost extras. Best-effort: if no transcript
+     * is found, the status-line usage (if any) is left as-is.
+     */
+    run(input: AgentRunInput, ctx: AdapterRunContext): Promise<AgentRunResult>;
     static fromConfig(config: AdapterConfig): ClaudeInteractiveAdapter;
 }
 
@@ -1424,11 +1493,12 @@ declare class CodexInteractiveAdapter extends InteractivePtyAdapter {
     private readonly sessionsDir?;
     constructor(opts?: CodexInteractiveOptions);
     /**
-     * Run Codex, then capture its NATIVE session id (the rollout UUID) for this
-     * cwd and attach it to the result's `sessionRef` so the runner persists it and
-     * a later resume can use `codex resume <id> "<prompt>"`. Capture is best-effort:
-     * if no rollout matches (or any I/O fails) the result is returned unchanged, so
-     * the run still resumes via the `--last` fallback.
+     * Run Codex, then read its rollout for this cwd to capture (a) the NATIVE
+     * session id (the rollout UUID) for `sessionRef` so a later resume can use
+     * `codex resume <id> "<prompt>"`, and (b) authoritative token usage for
+     * `meta.usage` (device-independent — from Codex's own log, not the TUI). Both
+     * are best-effort: if no rollout matches (or any I/O fails) the result is
+     * returned unchanged, so the run still resumes via the `--last` fallback.
      */
     run(input: AgentRunInput, ctx: AdapterRunContext): Promise<AgentRunResult>;
     static fromConfig(config: AdapterConfig): CodexInteractiveAdapter;
@@ -1695,4 +1765,4 @@ declare function cleanTerminalText(input: string): string;
 /** Return the last `n` non-empty lines of cleaned text. */
 declare function tailLines(text: string, n: number): string[];
 
-export { type AbortReason, type AdapterAvailability, type AdapterConfig, type AdapterFactory, type AdapterListItem, type AdapterMode, AdapterRegistry, type AdapterRunContext, type AgentAdapter, type AgentAdapterDefinition, type AgentErrorInfo, type AgentEvent, type AgentEventType, AgentRelayError, type AgentRunInput, type AgentRunResult, type AgentSessionRef, AlwaysApproveDecider, ApiDecider, type ApprovalMode, BUILTIN_ADAPTER_DEFINITIONS, CONFIG_FILENAME, ClaudeInteractiveAdapter, CodexInteractiveAdapter, CommandDecider, type CommandPreview, type CompletionContext, type CompletionDetector, CompositeCompletionDetector, ConfigError, type CreateSessionInput, DEFAULT_DENY_PATTERNS, type Decider, type DeciderConfig, type DeciderConfigSchema, type DeciderFlags, type DecisionAction, DefaultCompletionDetector, DefaultKeymap, type DetectedPrompt, type DoctorReport, type FakeAdapterOptions, FakeAgentAdapter, FunctionDecider, type HooksConfig, type InitResult, type InteractionDecision, type InteractionKind, type InteractionRequest, type InteractiveAdapterConfig, InteractivePtyAdapter, OutputPatternDetector, PromptDetector, type PromptDetectorOptions, type PruneOptions, type PruneResult, type PtyKeymap, type PtySessionOptions, type RelayConfig, type RelayDefaults, type ResumeCommandResult, RuleDecider, type RunHooks, RunLogger, type RunLoggerOptions, type RunOutcome, type RunnerOptions, type SandboxLevel, type SessionListItem, SessionManager, type SessionMetadata, SessionNotFoundError, type SessionStatus, type ShellHookContext, type ShellHooks, UnknownAdapterError, adapterConfigSchema, approvalPolicySchema, cleanTerminalText, configPath, configSchema, createAdapterFactory, createDecider, createDefaultConfig, deciderConfigFromFlags, deciderSchema, defaultRegistry, defaultsSchema, hooksSchema, listAdapters, listSessions, loadConfig, loadConfigOrDefault, parseCheckbox, parseConfig, parseDecisionReply, pruneSessions, renderDecisionPrompt, resolveApprovalMode, resolvePrompt, resolveSandbox, resumeCommand, runAgent, runCommand, runDoctor, runInit, runPtySession, runShellHook, sandboxSchema, saveConfig, stringifyConfig, stripAnsi, tailLines };
+export { type AbortReason, type AdapterAvailability, type AdapterConfig, type AdapterFactory, type AdapterListItem, type AdapterMode, AdapterRegistry, type AdapterRunContext, type AgentAdapter, type AgentAdapterDefinition, type AgentErrorInfo, type AgentEvent, type AgentEventType, AgentRelayError, type AgentRunInput, type AgentRunResult, type AgentSessionRef, type AgentUsage, AlwaysApproveDecider, ApiDecider, type ApprovalMode, BUILTIN_ADAPTER_DEFINITIONS, CONFIG_FILENAME, ClaudeInteractiveAdapter, CodexInteractiveAdapter, CommandDecider, type CommandPreview, type CompletionContext, type CompletionDetector, CompositeCompletionDetector, ConfigError, type CreateSessionInput, DEFAULT_DENY_PATTERNS, type Decider, type DeciderConfig, type DeciderConfigSchema, type DeciderFlags, type DecisionAction, DefaultCompletionDetector, DefaultKeymap, type DetectedPrompt, type DoctorReport, type FakeAdapterOptions, FakeAgentAdapter, FunctionDecider, type HooksConfig, type InitResult, type InteractionDecision, type InteractionKind, type InteractionRequest, type InteractiveAdapterConfig, InteractivePtyAdapter, OutputPatternDetector, PromptDetector, type PromptDetectorOptions, type PruneOptions, type PruneResult, type PtyKeymap, type PtySessionOptions, type RelayConfig, type RelayDefaults, type ResumeCommandResult, RuleDecider, type RunHooks, RunLogger, type RunLoggerOptions, type RunOutcome, type RunnerOptions, type SandboxLevel, type SessionListItem, SessionManager, type SessionMetadata, SessionNotFoundError, type SessionStatus, type ShellHookContext, type ShellHooks, UnknownAdapterError, adapterConfigSchema, approvalPolicySchema, cleanTerminalText, configPath, configSchema, createAdapterFactory, createDecider, createDefaultConfig, deciderConfigFromFlags, deciderSchema, defaultRegistry, defaultsSchema, hooksSchema, listAdapters, listSessions, loadConfig, loadConfigOrDefault, parseCheckbox, parseConfig, parseDecisionReply, pruneSessions, renderDecisionPrompt, resolveApprovalMode, resolvePrompt, resolveSandbox, resumeCommand, runAgent, runCommand, runDoctor, runInit, runPtySession, runShellHook, sandboxSchema, saveConfig, stringifyConfig, stripAnsi, tailLines };