akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/types/client/storage.d.ts

@@ -1,5 +1,12 @@
+/** Client key-value storage: the shell's preferences in a native app, localStorage in a browser. */
 export declare const storage: {
     getItem: (key: string) => Promise<string | null | undefined>;
-    setItem: (key: string, value: string) => Promise<void>;
-    removeItem: (key: string) => Promise<void>;
+    setItem: (key: string, value: string) => Promise<void | undefined>;
+    removeItem: (key: string) => Promise<void | undefined>;
+};
+/** Tokens: the OS credential store in a native app; a browser has none, so localStorage there. */
+export declare const secretStorage: {
+    getItem: (key: string) => Promise<string | null | undefined>;
+    setItem: (key: string, value: string) => Promise<void | undefined>;
+    removeItem: (key: string) => Promise<void | undefined>;
 };

package/types/client/types.d.ts

@@ -31,7 +31,6 @@ export declare const isFontPreloadEnabled: (font: ReactFont) => boolean;
 export declare const getFontStyles: (font: ReactFont) => ReactFontStyle[];
 export declare const getFontFaces: (font: ReactFont) => ReactFontFace[];
 export declare const getOptimizedFontSrc: (font: ReactFont, path: ReactFontPath) => string;
-/** Common props for list/zone components that render many model records. */
 export interface ModelsProps<M extends {
     id: string;
 }> {
@@ -41,7 +40,6 @@ export interface ModelsProps<M extends {
     init?: FetchInitForm<any, any>;
     onClickItem?: (model: M) => unknown;
 }
-/** Common props for unit/view components that render one named model record. */
 export type ModelProps<T extends string, L extends {
     id: string;
 }> = {
@@ -134,7 +132,6 @@ export interface ReactFont {
     adjustFontFallback?: boolean;
     optimize?: boolean;
 }
-/** Font declaration consumed by Akan layout modules and font optimization. */
 export type Font = ReactFont;
 export interface RootLayoutProps {
     children: ReactNode;

package/types/common/CodeAgentClient.d.ts

@@ -0,0 +1,20 @@
+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>;
+}
+export declare class CodeAgentClient {
+    #private;
+    constructor(transport: CodeAgentTransport);
+    /** The highest sequence accepted; a reconnecting host replays from here. */
+    get lastSeq(): number;
+    /** Call on a new session, which restarts the sequence. */
+    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,72 @@
+import type { CodeAgentApprovalRequest, CodeAgentEvent, CodeAgentQuestion, CodeAgentSessionInfo, CodeAgentStopReason, CodeAgentSubagent, 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;
+};
+export declare class CodeTranscript {
+    #private;
+    get parts(): readonly CodeTranscriptPart[];
+    get info(): CodeAgentSessionInfo | undefined;
+    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;
+    };
+    get subagents(): CodeAgentSubagent[];
+    /** Bumped on every applied event. */
+    get revision(): number;
+    /** Drops every row but keeps the session info; the model's own window is untouched. */
+    clear(): void;
+    /** A locally typed prompt, drawn before the engine echoes it back as a `message` matched by text. */
+    echo(text: string, images?: number): void;
+    note(level: "info" | "warning" | "error", text: string): void;
+    apply(event: CodeAgentEvent): void;
+}

package/types/common/Logger.d.ts

@@ -52,19 +52,14 @@ export interface LoggerEmitInput {
     context?: string;
     attrs?: LogAttrs;
 }
-/** Log-level aware logger used by Akan runtime, CLI, and application services. */
 export declare class Logger {
     #private;
-    /** `AKAN_LOG_STDOUT_LEVEL` names what the container's stdout carries; without it the console level is that. */
     static level: LogLevel;
     static fileLevel: LogLevel;
     static format: LogFormat;
-    /** Which process this is (`gateway`, `all`, `batch`, `rsc-worker`); the owner sets it at boot. */
+    /** `gateway`, `all`, `batch` or `rsc-worker`; the owner sets it at boot. */
     static role: string | null;
-    /**
-     * Whether this process writes its own lines to the terminal. Off in every server process of an ndjson
-     * deployment: the hub owner writes the one JSON stream, and a text line from anyone would corrupt it.
-     */
+    /** Off in every server process of an ndjson deployment but the hub owner, whose JSON stream a text line corrupts. */
     static consoleOutput: boolean;
     /** Set by the trace layer when a flight recorder or a per-request debug floor can be active. */
     static contextGate: boolean;
@@ -75,27 +70,16 @@ export declare class Logger {
     static removeSink(sink: LoggerSink): void;
     static isVerbose(): boolean;
     static get isNdjson(): boolean;
-    /** For hot-path callers that would otherwise build a message the level is about to discard. */
     static shouldLog(logLevel: LogLevelInput): boolean;
     static normalizeLevel(level: LogLevelInput): LogLevel;
-    /** The lowest named level whose severity is at least `sev`. */
     static levelAtOrAbove(sev: number): LogLevel;
     static render(record: LogRecord): string;
-    /** `key=value` pairs; a string with whitespace is quoted so the line stays splittable. */
     static formatAttrs(attrs: LogAttrs): string;
-    /**
-     * A record somebody asked for below the level — a failed call's flight recorder, a request carrying
-     * `x-akan-debug` — passes every floor between here and the reader; the floors exist to drop what nobody asked for.
-     */
+    /** A flight-recorder or `x-akan-debug` record passes every floor between here and the reader. */
     static isPromoted(record: LogRecord): boolean;
     static redactAttrs(attrs: LogAttrs): LogAttrs;
-    /** A structured record from a caller that has more than a sentence to say — the canonical request line. */
     static emit({ level, name, message, context, attrs }: LoggerEmitInput): void;
-    /**
-     * Writes records that were captured below the gate and are now promoted — a failed request's flight
-     * recorder. They bypass the console level, since not showing them is what the recorder was for, and reach
-     * sinks under their own floors; each is marked `flight` so a reader knows why a trace line appears at info.
-     */
+    /** Writes a failed request's flight-recorder records past the console level, each marked `flight`. */
     static replay(records: LogRecord[], { evicted }?: {
         evicted?: number;
     }): void;

package/types/common/TrustedProxy.d.ts

@@ -1,36 +1,10 @@
-/**
- * Whether the hop that connected is allowed to name the caller.
- *
- * `x-real-ip` and `x-forwarded-for` are just request headers: anyone can send them. They are the truth only when
- * the peer that sent them is a proxy we put there — otherwise a client forges its own address and walks past
- * every `.with(Ip)` guard, rate limit and audit line at once.
- *
- * The default trusts a private, loopback or link-local peer and nothing else, because that is exactly the shape
- * of a proxy on the same network: an ingress, a service mesh, the dev machine. A gateway reachable from the
- * internet sees a public peer, so a header from there is dropped rather than believed. `AKAN_TRUSTED_PROXIES`
- * takes a comma-separated CIDR list for the case the proxy is not private — and `*` for "the deployment
- * guarantees nothing untrusted can reach this port", which is the old behaviour, written down.
- */
 export declare class TrustedProxy {
     #private;
     static configure(list: string | null | undefined): void;
     static reset(): void;
     static isTrusted(address: string | null | undefined): boolean;
-    /**
-     * The caller's address as recorded by a proxy, but only when the peer is one. Falls back to the peer itself,
-     * which is the right answer for a process nothing is proxying, and `null` when there is no peer either.
-     *
-     * `null` and `undefined` mean different things here. `null` is what `Server.requestIP` answers for a socket
-     * that has no address — a unix socket, which is how a gateway reaches its children — and only a process on
-     * this machine can open one, so the headers it wrote are a local proxy's and are believed. `undefined` is
-     * "nobody asked": no resolver was registered, and a header from an unknown peer is a header the client wrote.
-     */
+    /** A `null` peer is a unix socket, which only a local proxy opens, so its headers count; `undefined` is not. */
     static clientAddress(headers: Headers, peerAddress: string | null | undefined): string | null;
-    /**
-     * Whether an address is one no public name should resolve to: the local ranges `isTrusted` reads, plus the
-     * unspecified address, the carrier-grade NAT block `100.64/10`, multicast and the reserved top of IPv4. Used
-     * to refuse a fetch whose destination a caller chose by name, so it judges the address alone and never the
-     * configured proxy list — a trusted proxy is still not somewhere to send an outbound request.
-     */
+    /** For refusing an outbound fetch to a caller-chosen name: judges the address alone, never the proxy list. */
     static isPrivateAddress(address: string): boolean;
 }

package/types/common/applyMixins.d.ts

@@ -1,3 +1,6 @@
 type Cls<T = unknown> = new (...args: never[]) => T;
+export declare const getAllPropertyDescriptors: (objRef: Cls) => {
+    [key: string]: PropertyDescriptor;
+};
 export declare const applyMixins: (derivedCtor: Cls, constructors: (Cls | undefined)[], avoidKeys?: Set<string>) => Cls<unknown>;
 export {};

package/types/common/authToken.d.ts

@@ -1,19 +1,8 @@
 /** The pre-scoping key. Read as a fallback, never written; drop it once deployments have rotated past it. */
 export declare const legacyAuthTokenKey = "jwt";
-/**
- * Cookies carry no port (RFC 6265), so every app served from one host shares a jar — which on localhost is
- * every app in the workspace at once. Under a global `jwt` key each signin overwrites the neighbour's
- * session, and the JWT's own `appName` check only turns the stolen cookie into a failing credential.
- */
 export declare const authTokenKey: () => string;
 /** Matches both spellings so a signout can sweep a jar written before and after the key was scoped. */
 export declare const isAuthTokenKey: (key: string) => boolean;
-/** Whether a raw `cookie` header carries an auth token under either spelling. */
 export declare const cookieHeaderHasAuthToken: (cookieHeader: string | null | undefined) => boolean;
-/** Whether a token was minted for this app and environment — the same pair the server's account check makes. */
 export declare const isOwnAuthToken: (jwt: string) => boolean;
-/**
- * Reads the app-scoped token, falling back to a leftover global one only when its payload names this app —
- * a neighbour's token would decode fine here and fail every guard, so adopting it is worse than none.
- */
 export declare const readAuthToken: (read: (key: string) => string | null | undefined) => string | undefined;

package/types/common/capitalize.d.ts

@@ -1,2 +1,2 @@
-/** Uppercases only the first character of a string. */
 export declare const capitalize: (str: string) => string;
+export declare const lowerlize: (str: string) => string;

package/types/common/clamp.d.ts

@@ -1,2 +1 @@
-/** Constrains a value to `[min, max]`. */
 export declare const clamp: (value: number, min: number, max: number) => number;

package/types/common/clientAddress.d.ts

@@ -1,19 +1,5 @@
-/** Headers a proxy hop writes so the next hop can still name the original caller. */
 export declare const forwardedHeaders: readonly ["x-real-ip", "x-forwarded-for", "x-forwarded-port", "x-forwarded-host", "x-forwarded-proto"];
-/**
- * An IPv4 client reaching a dual-stack listener is reported as `::ffff:203.0.113.10`. That form is not a
- * valid destination for a `udp4` socket and does not compare equal to the same address written plainly, so
- * it is unwrapped at every boundary rather than at each call site that happens to remember.
- */
 export declare const normalizeIpAddress: (address: string) => string;
-/**
- * The caller's address as the nearest proxy recorded it. `x-real-ip` is one hop's word for who the client is
- * and wins; `x-forwarded-for` is a chain appended left to right, so its *first* entry is the original client
- * and everything after it is a proxy.
- *
- * Returns `null` rather than a placeholder. A socket peer behind a proxy is the proxy, so `127.0.0.1` here
- * would be indistinguishable from a genuinely local caller — and that is the failure this exists to prevent.
- */
+/** `x-real-ip`, else the first `x-forwarded-for` entry; `null`, never a placeholder, when neither is set. */
 export declare const clientAddressFromHeaders: (headers: Headers) => string | null;
-/** The client port the nearest proxy recorded, for correlating a connection with a peer's own logs. */
 export declare const clientPortFromHeaders: (headers: Headers) => number | null;

package/types/common/codeAgentProfile.d.ts

@@ -0,0 +1,115 @@
+export type CodeAgentBuiltinTool = "read" | "write" | "edit" | "ls" | "grep" | "find" | "bash";
+/** `never` trusts the environment, `all` trusts nothing. */
+export type CodeAgentApprovalPolicy = "never" | "writes" | "commands" | "all";
+/** `await` holds the turn open; `suspend` ends it and the host reopens one carrying the answer (survives a restart). */
+export type CodeAgentInteractionMode = "await" | "suspend";
+export interface CodeAgentModelInfo {
+    id: string;
+    name: string;
+    contextWindow?: number;
+    /** The model the session is running on. */
+    current: boolean;
+}
+export interface CodeAgentProviderInfo {
+    id: string;
+    name: string;
+    authorized: boolean;
+    models: CodeAgentModelInfo[];
+}
+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>;
+    headers?: Record<string, string>;
+    /** For a server that answers `401` and whose OAuth client or scopes cannot be discovered. */
+    oauth?: {
+        clientId?: string;
+        clientSecret?: string;
+        scope?: string;
+    };
+}
+/** `required` is not a failure: the server answered correctly and said who may talk to it. */
+export type CodeAgentMcpAuthState = "none" | "authorized" | "required";
+/** One declared MCP server; one that was never reachable is listed too, with its `error`. */
+export interface CodeAgentMcpStatus {
+    name: string;
+    transport: "stdio" | "http";
+    /** The command line or the url. */
+    target: string;
+    /** Published tool names, already prefixed with the server the way the model sees them. */
+    tools: string[];
+    /** Why it published none, when it published none. */
+    error?: string;
+    auth?: CodeAgentMcpAuthState;
+}
+export interface CodeAgentSubagentBudget {
+    maxDepth: number;
+    /** Subagents a whole tree may run at once; past it the `task` tool refuses instead of queueing. */
+    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; an array discovers `.akan/code/mcp.json` plus the servers it names. */
+        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;
+    };
+    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: {
+        /** Whether the repo's `AGENTS.md` is loaded. */
+        projectFiles: boolean;
+        /** The akan skill set: only each skill's one-line description sits in the window until a task matches. */
+        skills: boolean;
+    };
+}
+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;
+    readonly pod: (root: string) => CodeAgentProfile;
+    readonly review: (root: string) => CodeAgentProfile;
+    readonly web: (root: string) => CodeAgentProfile;
+};
+export type CodeAgentPresetName = keyof typeof codeAgentPresets;
+export declare const isCodeAgentPresetName: (name: string) => name is CodeAgentPresetName;

package/types/common/codeAgentWire.d.ts

@@ -0,0 +1,279 @@
+import type { CodeAgentApprovalPolicy, CodeAgentInteractionMode, CodeAgentProfile } from "./codeAgentProfile.d.ts";
+export declare const codeAgentWireVersion = 1;
+export declare const codeAgentLabelChars = 200;
+/** Clip length of a tool result on the wire; the model's own copy is not clipped. */
+export declare const codeAgentOutputChars = 2000;
+export type CodeAgentEffort = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export interface CodeAgentSessionInfo {
+    sessionId: string;
+    cwd: string;
+    profile: string;
+    model: {
+        provider: string;
+        id: string;
+        name: string;
+    } | undefined;
+    tools: string[];
+    /** Absent when the model reports no window, which is not a window of zero. */
+    contextTokens: number | undefined;
+    /** Absent when the model does no reasoning at all, which is not reasoning turned `off`. */
+    effort: CodeAgentEffort | undefined;
+    /** Absent until the session has been asked something. */
+    name: string | undefined;
+    /** `await` keeps a question inside its turn; `suspend` ends the turn (`awaiting`) and the answer opens a new one. */
+    interaction: {
+        question: CodeAgentInteractionMode;
+        approval: CodeAgentInteractionMode;
+    };
+}
+/**
+ * `awaiting` only comes from a profile whose `interaction` suspends; `truncated` is a partial success (keep the text,
+ * offer "continue"); only a host with its own ceiling emits `maxTurns`. A turn's `message` precedes its `turn_end`.
+ */
+export type CodeAgentStopReason = "done" | "aborted" | "truncated" | "error" | "awaiting" | "maxTurns";
+/** A `blocked` call never executed, so it is not an `error`. */
+export type CodeAgentToolOutcome = "ok" | "error" | "blocked";
+export type CodeAgentToolOp = "read" | "write" | "delete" | "list" | "search" | "execute" | "other";
+/** Carried on both the start and the end frame; a host folding by `toolCallId` keeps the end frame's. */
+export interface CodeAgentToolSummary {
+    toolCallId: string;
+    name: string;
+    op: CodeAgentToolOp;
+    /** Progress, not a change list: a `bash` edit names no path and a `blocked` call names one it never wrote. */
+    path?: string;
+    /** Clipped to {@link codeAgentLabelChars}. */
+    title: string;
+}
+export interface CodeAgentQuestionOption {
+    key: string;
+    label: string;
+    detail?: string;
+    /** The one to take when the user says "you decide". */
+    recommended?: boolean;
+}
+export interface CodeAgentQuestion {
+    questionId: string;
+    prompt: string;
+    kind: "text" | "select" | "confirm";
+    options?: CodeAgentQuestionOption[];
+    multiSelect?: boolean;
+    freeText?: boolean;
+}
+/** Structured so a reconnecting client can restore a multi-select; the prose is {@link codeAgentRenderAnswer}. */
+export interface CodeAgentAnswer {
+    keys?: string[];
+    text?: string;
+}
+export interface CodeAgentApprovalRequest {
+    approvalId: string;
+    toolCallId: string;
+    name: string;
+    /** Rendered and clipped. */
+    summary: string;
+    policy: CodeAgentApprovalPolicy;
+}
+/** A running `task` sub-agent; `tokens` is read when the frame is made, and a finished one leaves the list. */
+export interface CodeAgentSubagent {
+    /** The `toolCallId` of the `task` call that opened it. */
+    id: string;
+    kind: string;
+    description: string;
+    startedAt: number;
+    tokens: number;
+}
+export type CodeAgentEventBody = {
+    type: "session";
+    info: CodeAgentSessionInfo;
+} | {
+    type: "turn_start";
+    turnId: string;
+} | {
+    type: "turn_end";
+    turnId: string;
+    stopReason: CodeAgentStopReason;
+} | {
+    type: "text_delta";
+    turnId: string;
+    text: string;
+} | {
+    type: "thinking_delta";
+    turnId: string;
+    text: string;
+} | {
+    type: "message";
+    turnId: string;
+    role: "user" | "assistant";
+    text: string;
+} | {
+    type: "tool_start";
+    turnId: string;
+    tool: CodeAgentToolSummary;
+} | {
+    type: "tool_progress";
+    turnId: string;
+    toolCallId: string;
+    text: string;
+} | {
+    type: "tool_end";
+    turnId: string;
+    tool: CodeAgentToolSummary;
+    outcome: CodeAgentToolOutcome;
+    output: string;
+    truncated: boolean;
+} | {
+    type: "question";
+    question: CodeAgentQuestion;
+} | {
+    type: "question_resolved";
+    questionId: string;
+    answer: CodeAgentAnswer;
+    rendered: string;
+}
+/** A question nobody could be asked — no host attached — answered with nothing; the model continued on its own. */
+ | {
+    type: "question_skipped";
+    question: CodeAgentQuestion;
+    reason: "no-host";
+} | {
+    type: "approval";
+    request: CodeAgentApprovalRequest;
+} | {
+    type: "approval_resolved";
+    approvalId: string;
+    approved: boolean;
+} | {
+    type: "context";
+    used: number;
+    max: number | undefined;
+}
+/** An `end` carrying neither `error` nor `aborted` is the only one that compacted anything. */
+ | {
+    type: "compaction";
+    phase: "start" | "end";
+    reason: "manual" | "threshold" | "overflow";
+    error?: string;
+    aborted?: boolean;
+} | {
+    type: "retry";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    message: string;
+} | {
+    type: "queue";
+    steering: string[];
+    followUp: string[];
+} | {
+    type: "notice";
+    level: "info" | "warning" | "error";
+    message: string;
+}
+/** The whole list of running sub-agents, re-sent on every change and on a slow tick while any runs. */
+ | {
+    type: "subagent";
+    agents: CodeAgentSubagent[];
+} | {
+    type: "error";
+    message: string;
+    fatal: boolean;
+} | {
+    type: "idle";
+}
+/** A host-made frame in the core's sequence: `kind` is opaque, a client upserts by `id`, `persist` defaults false. */
+ | {
+    type: "host";
+    kind: string;
+    id?: string;
+    persist?: boolean;
+    payload: unknown;
+};
+export type CodeAgentEvent = CodeAgentEventBody & {
+    seq: number;
+};
+export type CodeAgentEventType = CodeAgentEventBody["type"];
+/** A `host` row is only the default: the frame's own `persist` decides, via {@link codeAgentShouldPersist}. */
+export declare const codeAgentEventPersistence: {
+    [key in CodeAgentEventType]: "live" | "persist";
+};
+export type CodeAgentImage = {
+    path: string;
+} | {
+    data: string;
+    mime: string;
+};
+export declare const codeAgentSessionName: (text: string, max?: number) => string;
+export type CodeAgentCommand = {
+    type: "prompt";
+    message: string;
+    images?: CodeAgentImage[];
+    deliverAs?: "steer" | "followUp";
+} | {
+    type: "answer";
+    questionId: string;
+    answer: CodeAgentAnswer;
+} | {
+    type: "approve";
+    approvalId: string;
+    approved: boolean;
+} | {
+    type: "abort";
+} | {
+    type: "compact";
+    instructions?: string;
+} | {
+    type: "set_model";
+    provider: string;
+    modelId: string;
+} | {
+    type: "fork";
+    entryId: string;
+} | {
+    type: "new_session";
+}
+/** Current state, plus every frame after `sinceSeq` when one is given. */
+ | {
+    type: "get_state";
+    sinceSeq?: number;
+} | {
+    type: "shutdown";
+};
+export type CodeAgentCommandType = CodeAgentCommand["type"];
+export interface CodeAgentRequest {
+    id: string;
+    command: CodeAgentCommand;
+}
+export interface CodeAgentReply {
+    type: "reply";
+    id: string;
+    ok: boolean;
+    error?: string;
+    data?: unknown;
+}
+export type CodeAgentFrame = ({
+    type: "event";
+} & {
+    event: CodeAgentEvent;
+}) | CodeAgentReply;
+export declare const isCodeAgentReply: (frame: CodeAgentFrame) => frame is CodeAgentReply;
+export declare const codeAgentShouldPersist: (event: CodeAgentEventBody) => boolean;
+export declare const codeAgentClip: (text: string, max: number) => string;
+export declare const codeAgentRenderAnswer: (question: CodeAgentQuestion, answer: CodeAgentAnswer) => string;
+export declare const codeAgentEventLabel: (event: CodeAgentEventBody) => string;
+export interface CodeAgentState {
+    info: CodeAgentSessionInfo;
+    streaming: boolean;
+    /** Present only when `get_state` asked for a replay; empty when nothing was missed. */
+    frames?: CodeAgentEvent[];
+    /** How far back a replay reaches; a client behind this reloads the transcript instead. */
+    replayFrom: number;
+}
+export interface CodeAgentStartOptions {
+    cwd: string;
+    profile: CodeAgentProfile;
+    model?: {
+        provider: string;
+        id: string;
+    };
+    /** Resume this session instead of opening a new one. */
+    sessionId?: string;
+}