agent-sh 0.15.0 → 0.15.2

package/src/agent/live-view.ts

@@ -0,0 +1,279 @@
+import type { ChatCompletionMessageParam, AgentShMessage } from "./llm-client.js";
+import type { HandlerFunctions } from "../utils/handler-registry.js";
+import type { ImageContent } from "./types.js";
+
+export interface CompactResult {
+  before: number;
+  after: number;
+  evictedCount: number;
+  [extra: string]: unknown;
+}
+
+export class LiveView {
+  private messages: ChatCompletionMessageParam[] = [];
+  private messagesDirty = true;
+  private cachedMessagesJson: string | null = null;
+
+  readonly instanceId: string;
+  private readonly handlers: HandlerFunctions | null;
+
+  private lastApiTokenCount: number | null = null;
+  private lastApiMessageCount: number = 0;
+
+  // Mid-tool-pair user/system messages are buffered and flushed after
+  // the trailing tool_result — splicing into the gap breaks
+  // reasoning_content pairing on strict providers.
+  private pendingMessages: Array<{ kind: "system" | "user"; text: string }> = [];
+
+  constructor(handlers?: HandlerFunctions, instanceId: string = "0000") {
+    this.handlers = handlers ?? null;
+    this.instanceId = instanceId;
+  }
+
+  private getMessagesJson(): string {
+    if (this.messagesDirty || this.cachedMessagesJson === null) {
+      this.cachedMessagesJson = JSON.stringify(this.messages);
+      this.messagesDirty = false;
+    }
+    return this.cachedMessagesJson;
+  }
+
+  private invalidateMessagesCache(): void {
+    this.messagesDirty = true;
+    this.cachedMessagesJson = null;
+  }
+
+  addUserMessage(text: string, images?: ImageContent[]): void {
+    if (images?.length) {
+      const parts: Array<{ type: "text"; text: string } | { type: "image_url"; image_url: { url: string } }> = [];
+      if (text) parts.push({ type: "text", text });
+      for (const img of images) {
+        parts.push({ type: "image_url", image_url: { url: `data:${img.mimeType};base64,${img.data}` } });
+      }
+      this.messages.push({ role: "user", content: parts } as unknown as ChatCompletionMessageParam);
+    } else {
+      this.messages.push({ role: "user", content: text });
+    }
+    this.invalidateMessagesCache();
+  }
+
+  addAssistantMessage(
+    content: string | null,
+    toolCalls?: { id: string; function: { name: string; arguments: string } }[],
+    extras?: Record<string, unknown>,
+  ): void {
+    const hasToolCalls = !!toolCalls?.length;
+
+    // Promote reasoning into content on reasoning-only turns; strict
+    // providers (DeepSeek native) reject content="" with no tool_calls.
+    if (!content && !hasToolCalls) {
+      const r = (extras?.reasoning_content ?? extras?.reasoning) as unknown;
+      if (typeof r === "string" && r) content = r;
+    }
+    if (!content && !hasToolCalls) return;
+
+    const base: Record<string, unknown> = {
+      role: "assistant",
+      content: hasToolCalls ? (content ?? null) : content,
+    };
+    if (hasToolCalls) {
+      base.tool_calls = toolCalls!.map((tc) => ({
+        id: tc.id,
+        type: "function" as const,
+        function: tc.function,
+      }));
+    }
+    if (extras) Object.assign(base, extras);
+    this.messages.push(base as unknown as ChatCompletionMessageParam);
+    this.invalidateMessagesCache();
+  }
+
+  addToolResult(toolCallId: string, content: string | ImageContent[], isError = false): void {
+    if (typeof content === "string") {
+      this.messages.push({ role: "tool", tool_call_id: toolCallId, content });
+    } else {
+      const parts: Array<{ type: "text"; text: string } | { type: "image_url"; image_url: { url: string } }> = [];
+      for (const img of content) {
+        parts.push({ type: "image_url", image_url: { url: `data:${img.mimeType};base64,${img.data}` } });
+      }
+      const label = isError ? `Error: [${content.length} image(s)]` : `[${content.length} image(s)]`;
+      parts.unshift({ type: "text", text: label });
+      this.messages.push({ role: "tool", tool_call_id: toolCallId, content: parts } as unknown as ChatCompletionMessageParam);
+    }
+    this.invalidateMessagesCache();
+    this.flushPendingMessages();
+  }
+
+  addToolResultInline(content: string): void {
+    this.messages.push({ role: "user", content });
+    this.invalidateMessagesCache();
+    this.flushPendingMessages();
+  }
+
+  /** Safe from any context: queues if mid-tool-pair, appends otherwise. */
+  addSystemNote(text: string): void {
+    if (this.hasOpenToolCalls()) {
+      this.pendingMessages.push({ kind: "system", text });
+      return;
+    }
+    this.messages.push({ role: "user", content: text });
+    this.invalidateMessagesCache();
+  }
+
+  appendUserMessage(text: string): void {
+    if (this.hasOpenToolCalls()) {
+      this.pendingMessages.push({ kind: "user", text });
+      return;
+    }
+    this.addUserMessage(text);
+  }
+
+  private hasOpenToolCalls(): boolean {
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      const msg = this.messages[i]!;
+      if (msg.role === "tool") continue;
+      if (msg.role !== "assistant") return false;
+      if (!("tool_calls" in msg) || !msg.tool_calls) return false;
+      const answered = new Set<string>();
+      for (let j = i + 1; j < this.messages.length; j++) {
+        const m = this.messages[j]!;
+        if (m.role !== "tool") break;
+        answered.add((m as { tool_call_id: string }).tool_call_id);
+      }
+      return msg.tool_calls.some((tc) => !answered.has(tc.id));
+    }
+    return false;
+  }
+
+  private flushPendingMessages(): void {
+    if (this.pendingMessages.length === 0) return;
+    if (this.hasOpenToolCalls()) return;
+    const pending = this.pendingMessages;
+    this.pendingMessages = [];
+    for (const m of pending) {
+      if (m.kind === "user") {
+        this.addUserMessage(m.text);
+      } else {
+        this.messages.push({ role: "user", content: m.text });
+      }
+    }
+    this.invalidateMessagesCache();
+  }
+
+  /** Send-shaped; may be longer than get() (dangling calls stubbed) — never link()/replace() by these indices. */
+  forLLM(): ChatCompletionMessageParam[] {
+    return this.normalizeReasoningConsistency(
+      this.stubDanglingToolCalls(this.dropOrphanToolMessages(this.messages)),
+    );
+  }
+
+  get(): AgentShMessage[] {
+    return this.messages as AgentShMessage[];
+  }
+
+  replace(msgs: AgentShMessage[]): void {
+    this.replaceMessages(msgs as ChatCompletionMessageParam[]);
+  }
+
+  link(index: number, entryId: string): void {
+    const m = this.messages[index];
+    if (!m) throw new Error(`LiveView.link: no message at index ${index}`);
+    const am = m as AgentShMessage;
+    am.meta = { ...am.meta, entryId };
+  }
+
+  /** DeepSeek 400s on tool messages without a matching tool_call;
+   *  compaction can leave such orphans. */
+  private dropOrphanToolMessages(
+    messages: ChatCompletionMessageParam[],
+  ): ChatCompletionMessageParam[] {
+    const knownIds = new Set<string>();
+    const result: ChatCompletionMessageParam[] = [];
+    for (const msg of messages) {
+      if (msg.role === "assistant" && "tool_calls" in msg && msg.tool_calls) {
+        for (const tc of msg.tool_calls) knownIds.add(tc.id);
+      }
+      if (msg.role === "tool" && !knownIds.has((msg as { tool_call_id: string }).tool_call_id)) {
+        continue;
+      }
+      result.push(msg);
+    }
+    return result;
+  }
+
+  /** Stub missing tool results after a mid-execution interrupt so
+   *  DeepSeek doesn't 400 on dangling tool_calls. */
+  private stubDanglingToolCalls(
+    messages: ChatCompletionMessageParam[],
+  ): ChatCompletionMessageParam[] {
+    const result: ChatCompletionMessageParam[] = [];
+    let i = 0;
+    while (i < messages.length) {
+      const msg = messages[i]!;
+      result.push(msg);
+      i++;
+      if (msg.role !== "assistant" || !("tool_calls" in msg) || !msg.tool_calls) continue;
+      const seen = new Set<string>();
+      while (i < messages.length && messages[i]!.role === "tool") {
+        const t = messages[i]! as ChatCompletionMessageParam & { role: "tool"; tool_call_id: string };
+        seen.add(t.tool_call_id);
+        result.push(t);
+        i++;
+      }
+      for (const tc of msg.tool_calls) {
+        if (!seen.has(tc.id)) {
+          result.push({ role: "tool", tool_call_id: tc.id, content: "[cancelled]" });
+        }
+      }
+    }
+    return result;
+  }
+
+  /** DeepSeek 400s if any assistant in a thinking-mode conversation
+   *  is missing `reasoning_content`. Cross-alias `reasoning` (from
+   *  OpenRouter) and stub gaps with "". */
+  private normalizeReasoningConsistency(
+    messages: ChatCompletionMessageParam[],
+  ): ChatCompletionMessageParam[] {
+    const needsNormalize = messages.some(
+      (m) => m.role === "assistant" && (
+        (m as any).reasoning !== undefined ||
+        (m as any).reasoning_content !== undefined ||
+        (m as any).reasoning_details !== undefined
+      ),
+    );
+    if (!needsNormalize) return messages;
+    return messages.map((m) => {
+      if (m.role !== "assistant") return m;
+      const a = m as any;
+      if (a.reasoning_content !== undefined) return m;
+      return { ...m, reasoning_content: a.reasoning ?? "" } as ChatCompletionMessageParam;
+    });
+  }
+
+  /** Invalidates the API token baseline since the new array's count is unknown. */
+  replaceMessages(messages: ChatCompletionMessageParam[]): void {
+    this.messages = messages;
+    this.invalidateMessagesCache();
+    this.lastApiTokenCount = null;
+    this.lastApiMessageCount = 0;
+    this.flushPendingMessages();
+  }
+
+  updateApiTokenCount(promptTokens: number): void {
+    this.lastApiTokenCount = promptTokens;
+    this.lastApiMessageCount = this.messages.length;
+  }
+
+  estimatePromptTokens(): number {
+    if (this.lastApiTokenCount === null) return this.estimateTokens();
+    const trailing = this.messages.length - this.lastApiMessageCount;
+    if (trailing <= 0) return this.lastApiTokenCount;
+    const trailingMessages = this.messages.slice(this.lastApiMessageCount);
+    return this.lastApiTokenCount + Math.ceil(JSON.stringify(trailingMessages).length / 4);
+  }
+
+  estimateTokens(): number {
+    return Math.ceil(this.getMessagesJson().length / 4);
+  }
+}

package/src/agent/llm-client.ts

@@ -0,0 +1,111 @@
+/**
+ * Thin, stateless wrapper around the OpenAI SDK.
+ * No agent-sh knowledge — just a configured client.
+ *
+ * Used by both AgentLoop (full tool loop) and fast-path features
+ * (command suggestions, completions).
+ */
+import OpenAI from "openai";
+import type {
+  ChatCompletionMessageParam,
+  ChatCompletionTool,
+  ChatCompletionCreateParamsStreaming,
+  ChatCompletionCreateParamsNonStreaming,
+} from "openai/resources/chat/completions.js";
+
+export type { ChatCompletionMessageParam, ChatCompletionTool };
+
+export type AgentShMessage = ChatCompletionMessageParam & {
+  meta?: Record<string, unknown>;
+};
+
+export function stripMeta(m: ChatCompletionMessageParam): ChatCompletionMessageParam {
+  if (!("meta" in m)) return m;
+  const { meta: _meta, ...rest } = m as ChatCompletionMessageParam & { meta?: unknown };
+  return rest as ChatCompletionMessageParam;
+}
+
+export interface LlmClientConfig {
+  apiKey: string;
+  baseURL?: string;
+  model: string;
+  /** Sent as OpenRouter X-Title; ignored by other providers. */
+  appName?: string;
+  /** Sent as OpenRouter HTTP-Referer; ignored by other providers. */
+  appUrl?: string;
+}
+
+function attributionHeaders(config: LlmClientConfig): Record<string, string> {
+  return {
+    "HTTP-Referer": config.appUrl ?? "https://agent-sh.dev",
+    "X-Title": config.appName ?? "agent-sh",
+    "X-OpenRouter-Categories": "cli-agent,programming-app",
+  };
+}
+
+export class LlmClient {
+  private client: OpenAI;
+  public model: string;
+
+  constructor(private config: LlmClientConfig) {
+    this.client = new OpenAI({
+      apiKey: config.apiKey,
+      baseURL: config.baseURL,
+      defaultHeaders: attributionHeaders(config),
+    });
+    this.model = config.model;
+  }
+
+  /** Swap the underlying client config at runtime (e.g. provider switch). */
+  reconfigure(newConfig: LlmClientConfig): void {
+    this.config = newConfig;
+    this.client = new OpenAI({
+      apiKey: newConfig.apiKey,
+      baseURL: newConfig.baseURL,
+      defaultHeaders: attributionHeaders(newConfig),
+    });
+    this.model = newConfig.model;
+  }
+
+  stream(opts: StreamOpts) {
+    const { signal, messages, tools, model, max_tokens, ...rest } = opts;
+    const body = {
+      ...rest,
+      model: model ?? this.model,
+      messages: messages.map(stripMeta),
+      tools: tools?.length ? tools : undefined,
+      max_tokens: max_tokens ?? 65536,
+      stream: true as const,
+      stream_options: { include_usage: true },
+    };
+    return this.client.chat.completions.create(body as ChatCompletionCreateParamsStreaming, { signal });
+  }
+
+  async complete(opts: CompleteOpts): Promise<string> {
+    const { messages, model, max_tokens, ...rest } = opts;
+    const body = {
+      ...rest,
+      model: model ?? this.model,
+      messages: messages.map(stripMeta),
+      max_tokens: max_tokens ?? 1024,
+    };
+    const response = await this.client.chat.completions.create(body as ChatCompletionCreateParamsNonStreaming);
+    return response.choices[0]?.message?.content ?? "";
+  }
+}
+
+/** Known fields are typed; extras are forwarded verbatim to the SDK so
+ *  provider hooks can ship non-standard params (thinking, reasoning, …). */
+export type StreamOpts = {
+  messages: ChatCompletionMessageParam[];
+  tools?: ChatCompletionTool[];
+  model?: string;
+  max_tokens?: number;
+  signal?: AbortSignal;
+} & Record<string, unknown>;
+
+export type CompleteOpts = {
+  messages: ChatCompletionMessageParam[];
+  model?: string;
+  max_tokens?: number;
+} & Record<string, unknown>;

package/src/agent/llm-facade.ts

@@ -0,0 +1,43 @@
+/**
+ * ctx.agent.llm facade — delegates to an `llm:invoke` handler defined
+ * by the ash backend. Other backends (claude-code, pi, opencode) bring
+ * their own LLM and do not define this handler; `available` is false
+ * under those backends and calls reject.
+ */
+import type { LlmInterface, LlmMessage, LlmSession } from "./host-types.js";
+
+interface HandlerGate {
+  list: () => string[];
+  call: (name: string, ...args: unknown[]) => unknown;
+}
+
+export function createLlmFacade(handlers: HandlerGate): LlmInterface {
+  const invoke = (messages: LlmMessage[], maxTokens?: number, model?: string, reasoningEffort?: string): Promise<string> => {
+    const result = handlers.call("llm:invoke", messages, { maxTokens, model, reasoningEffort });
+    if (result === undefined) return Promise.reject(new Error("ctx.agent.llm: no LLM backend available"));
+    return result as Promise<string>;
+  };
+  return {
+    get available() { return handlers.list().includes("llm:invoke"); },
+    ask: ({ query, system, maxTokens, model, reasoningEffort }) => {
+      const messages: LlmMessage[] = [];
+      if (system) messages.push({ role: "system", content: system });
+      messages.push({ role: "user", content: query });
+      return invoke(messages, maxTokens, model, reasoningEffort);
+    },
+    session: (opts = {}) => {
+      const messages: LlmMessage[] = [];
+      if (opts.system) messages.push({ role: "system", content: opts.system });
+      const session: LlmSession = {
+        async send(message) {
+          messages.push({ role: "user", content: message });
+          const reply = await invoke(messages, opts.maxTokens, opts.model, opts.reasoningEffort);
+          messages.push({ role: "assistant", content: reply });
+          return reply;
+        },
+        history: () => messages.slice(),
+      };
+      return session;
+    },
+  };
+}

package/src/agent/normalize-args.ts

@@ -0,0 +1,61 @@
+/**
+ * Schema-aware tool-arg normalization.
+ *
+ * Some LLMs (notably Claude) occasionally emit nested object/array
+ * tool-call arguments as JSON-encoded strings instead of native
+ * objects, despite the schema declaring `type: "object"` /
+ * `type: "array"`. The discrepancy was diagnosed by the superash field
+ * test (2026-05-03 / commit `b9efd47`):
+ *
+ *     describe_demos: 'task' arrived as a string (length 1267)
+ *       last char code: 93 (']')
+ *       truncation suspected: true
+ *
+ * Tool handlers downstream had to add ad-hoc JSON.parse fallbacks. This
+ * helper centralizes the fix at the kernel boundary: after parsing the
+ * outer `argumentsJson`, walk each top-level field; for any field whose
+ * schema declares `object` or `array` but whose value is a string, run
+ * a single JSON.parse pass. On parse failure (e.g. truncated content),
+ * the string is left as-is — the tool can produce a clean error.
+ *
+ * Top-level only by design. Recursing into nested object schemas would
+ * change semantics for tools that legitimately accept stringified
+ * payloads as inner fields, and the observed wild cases all stringify
+ * at the top level.
+ */
+
+/** Subset of a JSON Schema root we care about: `properties` keyed by
+ *  field name, each declaring a `type`. Anything else is ignored. */
+type ToolInputSchema = {
+  properties?: Record<string, { type?: string } | unknown>;
+  [k: string]: unknown;
+};
+
+/** Normalize tool-call args against the tool's input_schema. Pure: does
+ *  not mutate `args`. Returns a new object with stringified-then-decoded
+ *  fields swapped in where applicable. */
+export function normalizeToolArgs(
+  args: Record<string, unknown>,
+  schema: unknown,
+): Record<string, unknown> {
+  if (!schema || typeof schema !== "object") return args;
+  const properties = (schema as ToolInputSchema).properties;
+  if (!properties || typeof properties !== "object") return args;
+
+  let out: Record<string, unknown> | null = null;
+  for (const [field, fieldSchema] of Object.entries(properties)) {
+    if (!fieldSchema || typeof fieldSchema !== "object") continue;
+    const expectedType = (fieldSchema as { type?: unknown }).type;
+    if (expectedType !== "object" && expectedType !== "array") continue;
+    const value = args[field];
+    if (typeof value !== "string") continue;
+    try {
+      const parsed = JSON.parse(value);
+      if (out === null) out = { ...args };
+      out[field] = parsed;
+    } catch {
+      // Leave as string — downstream tool can produce a useful error.
+    }
+  }
+  return out ?? args;
+}