akanjs 3.0.0-beta.13 → 3.0.0-beta.15

package/service/predefinedAdaptor/index.ts

@@ -2,7 +2,6 @@ export * from "./anthropicLlm";
 export * from "./cache.adaptor";
 export * from "./compress.adaptor";
 export * from "./database.adaptor";
-export * from "./deepseekLlm";
 export * from "./insightQuery";
 export * from "./llm.adaptor";
 export * from "./logging.adaptor";

package/service/predefinedAdaptor/llm.adaptor.ts

@@ -131,7 +131,12 @@ export interface LlmAccepts {
 /**
  * Settings for whichever adaptor fills `LlmAdaptorRole`, registered with `option.setLlm(...)` and injected as the
  * `llmOption` use. It belongs to the role rather than to one provider: swapping the default for another `adapt()`
- * class re-reads the same three fields under that provider's own defaults.
+ * class re-reads the same fields under that provider's own defaults.
+ *
+ * It is the floor, not the whole shape. `setLlm` keeps whatever else it is handed, so an adaptor an app or a
+ * library wrote declares its own interface extending this one and reads it with `use<MyLlmOption>()` — a region,
+ * a project id, a deployment name reach it through the same channel the fields below do, instead of a second
+ * `option.use({...})` key beside it.
  */
 export interface LlmOption {
   apiKey?: string;
@@ -156,3 +161,18 @@ export interface LlmOption {
    */
   maxTokens?: number;
 }
+
+/**
+ * What the chat prints as the party that refused a turn, carried on `agent.error.llmRequestFailed`.
+ *
+ * It is the host rather than the adaptor's own name because one adaptor speaks one dialect to whatever host it
+ * is pointed at — an OpenAI-dialect class aimed at a gateway would otherwise credit OpenAI for that gateway's
+ * refusal. A host that is not a URL is printed as written; there is nothing better to say about it.
+ */
+export const llmProviderOf = (host: string): string => {
+  try {
+    return new URL(host).hostname;
+  } catch {
+    return host;
+  }
+};

package/service/predefinedAdaptor/openaiLlm.ts

@@ -1,18 +1,27 @@
 import { Err } from "akanjs/dictionary";
 import { adapt } from "../adapt";
-import type { LlmAccepts, LlmAdaptor, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
+import {
+  type LlmAccepts,
+  type LlmAdaptor,
+  type LlmOption,
+  type LlmTurnAnswer,
+  type LlmTurnRequest,
+  llmProviderOf,
+} from "./llm.adaptor";
 import { type OpenaiAnswer, OpenaiDialect } from "./openaiDialect";
 
 /**
- * OpenAI's chat-completions endpoint, and every gateway that serves the same dialect — `host` is what points it
- * at one. It is `DeepseekLlm`'s sibling rather than its replacement: same wire, and the difference that earns a
- * second class is that this one declares `accepts`, so an attached image reaches the model as an image part
- * instead of a note saying it could not be read.
+ * The OpenAI chat-completions dialect, pointed at a host — and the framework's default fill for `LlmAdaptorRole`.
+ *
+ * One class rather than one per vendor: DeepSeek, Groq, Together, OpenRouter, Ollama and a self-hosted vLLM all
+ * serve this same wire, so what distinguishes them is `option.setLlm({ host, model })` and not a protocol. A
+ * provider that speaks its own wire — Anthropic's blocks, Bedrock's signed requests — is a different adaptor
+ * class, in this package or in the app's own `srvkit/`, applied with
+ * `option.applyAdaptor(LlmAdaptorRole, TheClass)`.
  *
  * `model` is required and has no default. A default would be a model name that ages out of the provider's
- * catalogue into a 404 at the first turn, and — worse here than for a text-only adaptor — it would decide the
- * vision claim below on the app's behalf. Name the model in `option.setLlm({ model })`, and name
- * `accepts: { image: false }` beside it when that model is one of the provider's text-only ones.
+ * catalogue into a 404 at the first turn, and — worse — it would decide the vision claim below on the app's
+ * behalf.
  */
 export class OpenaiLlm
   extends adapt("openaiLlm" as const, ({ use }) => ({
@@ -20,13 +29,22 @@ export class OpenaiLlm
   }))
   implements LlmAdaptor
 {
+  static readonly defaultHost = "https://api.openai.com/v1";
+
   get #host() {
-    return this.llmOption.host ?? "https://api.openai.com/v1";
+    return this.llmOption.host ?? OpenaiLlm.defaultHost;
   }
 
-  /** The endpoint takes image parts, so that is the provider's answer; a model that does not takes the override. */
-  get accepts(): LlmAccepts {
-    return this.llmOption.accepts ?? { image: true };
+  /**
+   * OpenAI's own endpoint takes image parts, so that is what is claimed for the default host. A host the app
+   * named is a gateway this class knows nothing about, and claiming vision for one is the worst guess available:
+   * the bytes reach a model that cannot decode them and the whole turn dies on a 400, where text-only degrades
+   * them to a note the model can repeat back. So a named host is text-only until `option.setLlm({ accepts })`
+   * says otherwise — as is the OpenAI model that reads no image.
+   */
+  get accepts(): LlmAccepts | undefined {
+    if (this.llmOption.accepts) return this.llmOption.accepts;
+    return this.llmOption.host ? undefined : { image: true };
   }
 
   async chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null> {
@@ -52,8 +70,8 @@ export class OpenaiLlm
       );
       return await OpenaiDialect.consumeStream(body, onDelta);
     } catch (error) {
-      
-      this.logger.error(`OpenAI turn failed: ${error instanceof Error ? error.message : String(error)}`);
+
+      this.logger.error(`LLM turn failed: ${error instanceof Error ? error.message : String(error)}`);
       throw error;
     }
   }
@@ -66,7 +84,7 @@ export class OpenaiLlm
       
       signal: AbortSignal.timeout(120_000),
     });
-    if (!response.ok) throw await OpenaiLlm.refusal(response);
+    if (!response.ok) throw await OpenaiLlm.refusal(this.#host, response);
     return (await response.json()) as T;
   }
 
@@ -77,13 +95,14 @@ export class OpenaiLlm
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(120_000),
     });
-    if (!response.ok || !response.body) throw await OpenaiLlm.refusal(response);
+    if (!response.ok || !response.body) throw await OpenaiLlm.refusal(this.#host, response);
     return response.body;
   }
 
   /** Carried on the `Err` so the chat prints the provider's own sentence rather than a status number. */
-  static async refusal(response: Response): Promise<Error> {
-    return new Err("agent.error.openaiRequestFailed", {
+  static async refusal(host: string, response: Response): Promise<Error> {
+    return new Err("agent.error.llmRequestFailed", {
+      provider: llmProviderOf(host),
       status: String(response.status),
       reason: await OpenaiDialect.reasonOf(response),
     });

package/store/agentic/StToolBuilder.ts

@@ -9,6 +9,7 @@ import {
   type PrimitiveScalar,
 } from "akanjs/base";
 import type { ParamFieldType } from "akanjs/constant";
+import type { ReactNode } from "react";
 import {
   AgenticSurface,
   type JsonSchema,
@@ -21,6 +22,15 @@ import { tagAction } from "../actionTag";
 
 import { useEffect, useRef } from "../hooks";
 
+/**
+ * The two ways a card ends the call it is parked on. `submit`'s value is what the model reads back, `cancel` is
+ * why there is none; the first one settles it and the card leaves the screen.
+ */
+export interface StToolCardControl {
+  submit: (value: unknown) => void;
+  cancel: (reason?: string) => void;
+}
+
 export interface StToolMeta {
   /**
    * Whether the call has to be waited out before what it did to the screen is reported back to the model. `false`
@@ -184,6 +194,50 @@ export class StToolBuilder<Args extends unknown[] = []> {
     return callable.current.fn;
   }
 
+  /**
+   * The other way a chain ends, for a tool whose answer belongs to the **user**: the call parks in the chat, the
+   * card renders there, and what it submits is what the model reads back. `.exec()` runs a function; this one runs
+   * a person, which is the whole difference — a name and a phone number are theirs to type, and a model that
+   * invents them has answered its own question.
+   *
+   * The arguments arrive positional like `.exec()`'s, and they are checked **before** the card is parked rather
+   * than while it renders: a bad argument has to reach the model as a refusal it can correct, and a throw inside
+   * the render would take the chat panel down with it instead.
+   *
+   * `confirm` is not read here. The card in front of the user is already the asking.
+   */
+  card(render: (control: StToolCardControl, ...args: Args) => ReactNode): void {
+    const surface = useSurface();
+    const scope = useScopePath();
+    const live = useRef({ render, meta: this.#meta });
+    live.current = { render, meta: this.#meta };
+    const declared = useRef<{ name: string | null; desc: string; meta: StToolMeta; args: StToolArg[] } | null>(null);
+    if (declared.current?.name !== this.#name)
+      declared.current = { name: this.#name, desc: this.#desc, meta: this.#meta, args: this.#args };
+    const scopeKey = scope.join(".");
+    useEffect(() => {
+      const spec = declared.current;
+      const name = spec?.name;
+      if (!spec || !name) return;
+      return surface.registerTool(scope, {
+        name,
+        description: spec.desc,
+        settle: spec.meta.settle,
+        parameters: StToolBuilder.parametersOf(spec.args),
+        guard: (args) => {
+          try {
+            StToolBuilder.positionalOf(name, spec.args, args);
+          } catch (error) {
+            return error instanceof Error ? error.message : String(error);
+          }
+          return live.current.meta.guard?.(args) ?? true;
+        },
+        card: ({ args, submit, cancel }) =>
+          live.current.render({ submit, cancel }, ...(StToolBuilder.positionalOf(name, spec.args, args) as Args)),
+      });
+    }, [surface, scopeKey, this.#name]);
+  }
+
   static parametersOf(args: StToolArg[]): JsonSchema | undefined {
     if (!args.length) return undefined;
     const required = args.filter((arg) => !arg.optional).map((arg) => arg.name);

package/store/agentic/attachAgentic.ts

@@ -15,7 +15,8 @@ export interface StAgentic {
   /** A read-only derived value the agent can read while the component is mounted: `.desc()` then `.value()`. */
   expose: <T extends AgentFieldType>(name: string | null, type: T, meta?: StExposeMeta) => StExposeDraft<T>;
   /**
-   * A component tool: `.desc()`, then `.arg()` / `.opt()`, chained onto one `.exec()` hook.
+   * A component tool: `.desc()`, then `.arg()` / `.opt()`, chained onto one terminal hook — `.exec()` for a tool
+   * a function answers, `.card()` for one the user answers in the chat.
    *
    * A falsy name declares the tool without publishing it — the callable still drives the click a person makes.
    * Every one of these ends in a hook, so a conditional surface withholds the name rather than skipping the chain.

package/store/agentic/useFormTools.ts

@@ -68,7 +68,7 @@ export const useFormTools = (refName: string | null, write: (action: string, val
 
         for (const { entry, value } of patch) {
           const control = surface.tool(AgenticSurface.fullName(scope, entry.action), scope);
-          if (control) void control.run({ value });
+          if (control?.run) void control.run({ value });
           else live.current(entry.action, value);
         }
       },

package/types/common/CodeAgentClient.d.ts

@@ -0,0 +1,26 @@
+import { type CodeAgentCommand, type CodeAgentEvent } from "./codeAgentWire.d.ts";
+export interface CodeAgentTransport {
+    send(line: string): void | Promise<void>;
+    /** Called once with a handler that receives whole lines. */
+    onLine(handler: (line: string) => void): void;
+    close?(): void | Promise<void>;
+}
+/**
+ * Speaks the code-agent wire over any line transport — a child process's stdio, a websocket, an in-process pair.
+ *
+ * It has no dependencies because the browser holds one too. Everything host-specific (spawning, reconnecting,
+ * authenticating) belongs to whoever builds the transport.
+ */
+export declare class CodeAgentClient {
+    #private;
+    constructor(transport: CodeAgentTransport);
+    /** The highest sequence accepted. A reconnecting host replays from here. */
+    get lastSeq(): number;
+    /** A new session restarts the sequence, so the watermark has to go with it or every frame reads as a duplicate. */
+    resetSeq(): void;
+    on(listener: (event: CodeAgentEvent) => void): () => boolean;
+    send(command: CodeAgentCommand): Promise<unknown>;
+    close(): Promise<void>;
+    /** Feed raw chunks when the transport is byte-oriented rather than line-oriented. */
+    push(chunk: string): void;
+}

package/types/common/CodeTranscript.d.ts

@@ -0,0 +1,99 @@
+import type { CodeAgentApprovalRequest, CodeAgentEvent, CodeAgentQuestion, CodeAgentSessionInfo, CodeAgentStopReason, CodeAgentToolOutcome, CodeAgentToolSummary } from "akanjs/common";
+export type CodeTranscriptPart = {
+    kind: "user";
+    id: string;
+    text: string;
+    images?: number;
+} | {
+    kind: "assistant";
+    id: string;
+    text: string;
+    streaming: boolean;
+    truncated: boolean;
+} | {
+    kind: "thinking";
+    id: string;
+    text: string;
+} | {
+    kind: "tool";
+    id: string;
+    tool: CodeAgentToolSummary;
+    outcome?: CodeAgentToolOutcome;
+    output?: string;
+    progress?: string;
+} | {
+    kind: "notice";
+    id: string;
+    level: "info" | "warning" | "error";
+    text: string;
+} | {
+    kind: "question";
+    id: string;
+    question: CodeAgentQuestion;
+    rendered?: string;
+} | {
+    kind: "approval";
+    id: string;
+    request: CodeAgentApprovalRequest;
+    approved?: boolean;
+} | {
+    kind: "host";
+    id: string;
+    hostKind: string;
+    text: string;
+};
+/**
+ * Folds the akan wire into what a screen shows.
+ *
+ * It reads the contract and nothing else, so the terminal and a browser can share it — and so anything it
+ * cannot render is a hole in the contract rather than a missing feature of one host.
+ *
+ * ⚠️ **Tool and host rows are upserted by id, and the first row of a turn is index `0`.** A truthy check on the
+ * looked-up index sends that first `tool_end` down the append path, and the same call ends up on screen twice.
+ * `undefined` is the only absence here; `== null` would be wrong for the same reason.
+ */
+export declare class CodeTranscript {
+    #private;
+    get parts(): readonly CodeTranscriptPart[];
+    get info(): CodeAgentSessionInfo | undefined;
+    /**
+     * The one line that says what this session is, derived here rather than by each host.
+     *
+     * The declared context window is on it deliberately: a model descriptor that is wrong but self-consistent —
+     * a 65k window declared for a provider that serves 1M — passes every programmatic check there is, and the
+     * only thing that catches it is a person reading the number.
+     */
+    get headline(): string;
+    get context(): {
+        used: number;
+        max: number | undefined;
+    } | undefined;
+    get streaming(): boolean;
+    get compacting(): boolean;
+    get question(): CodeAgentQuestion | undefined;
+    get approval(): CodeAgentApprovalRequest | undefined;
+    get stopReason(): CodeAgentStopReason | undefined;
+    get queue(): {
+        steering: number;
+        followUp: number;
+    };
+    /** Bumped on every applied event, so a view can tell "changed" from "same" without comparing arrays. */
+    get revision(): number;
+    /**
+     * Drops every row, keeping what the session *is*.
+     *
+     * Only the screen: the model's own window is untouched, so a cleared transcript and a fresh conversation are
+     * two different things and a host that offers this has to say which one it did.
+     */
+    clear(): void;
+    /**
+     * A locally typed prompt, shown before the engine echoes it back as a `message`.
+     *
+     * Attachments ride beside the text rather than in it: the engine's echo carries the words only, and the
+     * two rows are matched by text to keep one bubble.
+     */
+    echo(text: string, images?: number): void;
+    /** Something the host has to say — a slash-command answer, a key hint — in the same column as the rest. */
+    note(level: "info" | "warning" | "error", text: string): void;
+    apply(event: CodeAgentEvent): void;
+}

package/types/common/codeAgentProfile.d.ts

@@ -0,0 +1,111 @@
+/**
+ * What a code agent is allowed to be, as one value.
+ *
+ * The profile is read by both the host and the core, so it lives here rather than in the CLI. Most of it is
+ * applied at **assembly time** — a tool outside `tools` is never constructed, so the model cannot call it and
+ * it costs no prompt tokens either. The runtime hooks (`approval`, `paths`, `limits`) are the second gate, for
+ * the things assembly cannot decide in advance.
+ */
+export type CodeAgentBuiltinTool = "read" | "write" | "edit" | "ls" | "grep" | "find" | "bash";
+/** `never` trusts the environment, `all` trusts nothing. The middle two are the useful ones. */
+export type CodeAgentApprovalPolicy = "never" | "writes" | "commands" | "all";
+/**
+ * How the core behaves while a human is being asked something.
+ *
+ * `await` holds the turn open until the answer arrives. `suspend` resolves the request with a sentinel, ends the
+ * turn, and expects the host to reopen one carrying the answer — which is the only form that survives a process
+ * restart and does not hold a shared workspace for the minutes or days a person may take to answer.
+ */
+export type CodeAgentInteractionMode = "await" | "suspend";
+export interface CodeAgentMcpServerRef {
+    name: string;
+    transport: "stdio" | "http";
+    /** stdio: the executable and its argv. http: the endpoint. */
+    command?: string;
+    args?: string[];
+    url?: string;
+    env?: Record<string, string>;
+}
+export interface CodeAgentSubagentBudget {
+    maxDepth: number;
+    maxConcurrent: number;
+    /** Tokens a whole subagent tree may spend before the `task` tool refuses to open another. */
+    budget: number;
+}
+export interface CodeAgentProfile {
+    name: string;
+    tools: {
+        builtin: CodeAgentBuiltinTool[];
+        /** Workflow, context and self-verification tools built on devkit. */
+        akan: boolean;
+        /**
+         * `"off"` reaches no server at all. An array turns discovery on: the workspace's `.akan/code/mcp.json`
+         * plus whatever the array names, so the common case is an empty array.
+         */
+        mcp: "off" | CodeAgentMcpServerRef[];
+        subagent: false | CodeAgentSubagentBudget;
+        web: {
+            fetch: boolean;
+            search: boolean;
+        };
+    };
+    approval: CodeAgentApprovalPolicy;
+    paths: {
+        root: string;
+        allow?: string[];
+        deny?: string[];
+    };
+    session: {
+        store: "file" | "memory" | "remote";
+        crossSession: boolean;
+    };
+    interaction: {
+        question: CodeAgentInteractionMode;
+        approval: CodeAgentInteractionMode;
+    };
+    network: {
+        allowHosts?: string[];
+        proxyBaseUrl?: string;
+    };
+    /** Whether the host can answer a question at all. A pod has nobody in front of it. */
+    ui: {
+        canPrompt: boolean;
+    };
+    limits: {
+        turnMs: number;
+        toolOutputBytes: number;
+        contextTokens: number;
+        /** How many times one turn-end plugin may reopen a turn with the same finding before it gives up. */
+        feedback: number;
+    };
+    context: {
+        /** The repo's `AGENTS.md` is ~26k tokens; a read-only reviewer does not need it. */
+        projectFiles: boolean;
+        /**
+         * The akan skill set — the scaffolding chain, the store surface, the validation loop.
+         *
+         * Only each skill's one-line description sits in the window; the body is read when a task matches. That
+         * makes it the cheapest context of the three, and the most valuable to a profile carrying no `AGENTS.md`.
+         */
+        skills: boolean;
+    };
+}
+/** The builtins that cannot change anything, which is what a profile is narrowed to when it must not. */
+export declare const codeAgentReadOnlyBuiltins: CodeAgentBuiltinTool[];
+/** Paths no profile may read, whatever its allowlist says. */
+export declare const codeAgentDeniedPaths: string[];
+export declare const codeAgentPresets: {
+    readonly local: (root: string) => CodeAgentProfile;
+    /**
+     * An isolated container. Everything is on because the container is the boundary, but nobody is watching it:
+     * a question that waits for an answer would hang the pod, so both interactions suspend. MCP is off because
+     * a pod's egress goes through a proxy and a stdio server started inside it is a process nobody vetted.
+     */
+    readonly pod: (root: string) => CodeAgentProfile;
+    /** A reviewer reads the repo and nothing else, so it reaches no external service. */
+    readonly review: (root: string) => CodeAgentProfile;
+    /** Isolation and approval are different axes: a pod is safe and its user may still want to be asked. */
+    readonly web: (root: string) => CodeAgentProfile;
+};
+export type CodeAgentPresetName = keyof typeof codeAgentPresets;
+export declare const isCodeAgentPresetName: (name: string) => name is CodeAgentPresetName;