akanjs 3.0.0-beta.2 → 3.0.0-beta.20

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;
+}

package/types/{server/routing → common}/eventStream.d.ts

@@ -3,11 +3,6 @@ export interface EventStreamOptions {
     /** What the keep-alive sends; a line starting with `:` is a comment every SSE client discards. */
     keepAliveChunk?: string;
 }
-/**
- * One `text/event-stream` response. `write` frames a JSON `data:` event, with an `id:` when the caller has one
- * so a client can resume with `Last-Event-ID`; `retry` tells it how long to wait before doing so. A keep-alive
- * comment goes out on an interval below common proxy idle timeouts, so a quiet stream is not reaped mid-life.
- */
 export declare class EventStream {
     #private;
     static readonly defaultKeepAliveMs = 15000;

package/types/common/fileUpload.d.ts

@@ -1,11 +1,3 @@
-interface FileUploadSerializedEndpoint {
-    fileUpload?: boolean;
-}
-interface FileUploadSerializedSignal {
-    prefix?: string;
-    endpoint: Record<string, FileUploadSerializedEndpoint>;
-}
-/** Framework-owned file-upload contract shared by client-safe packages. */
 export declare const fileUploadContract: {
     readonly fields: {
         readonly files: "files";
@@ -23,6 +15,9 @@ export interface FileUploadCapability {
     endpointKey: string;
     prefix?: string;
 }
-/** Discovers the upload endpoint marked with `{ fileUpload: true }` from the serialized signal. */
-export declare const resolveFileUploadCapability: (serializedSignal: Record<string, FileUploadSerializedSignal>) => FileUploadCapability | null;
-export {};
+export declare const resolveFileUploadCapability: (serializedSignal: Record<string, {
+    prefix?: string;
+    endpoint: Record<string, {
+        fileUpload?: boolean;
+    }>;
+}>) => FileUploadCapability | null;

package/types/common/index.d.ts

@@ -1,43 +1,44 @@
-export { applyMixins } from "./applyMixins.d.ts";
+export { applyMixins, getAllPropertyDescriptors } from "./applyMixins.d.ts";
 export { authTokenKey, cookieHeaderHasAuthToken, isAuthTokenKey, isOwnAuthToken, legacyAuthTokenKey, readAuthToken, } from "./authToken.d.ts";
-export { capitalize } from "./capitalize.d.ts";
+export { CodeAgentClient, type CodeAgentTransport } from "./CodeAgentClient.d.ts";
+export { CodeTranscript, type CodeTranscriptPart } from "./CodeTranscript.d.ts";
+export { capitalize, lowerlize } from "./capitalize.d.ts";
 export { clamp } from "./clamp.d.ts";
 export { clientAddressFromHeaders, clientPortFromHeaders, forwardedHeaders, normalizeIpAddress, } from "./clientAddress.d.ts";
-export { deepObjectify } from "./deepObjectify.d.ts";
-export type { DynamicRecord } from "./dynamicRecord.d.ts";
+export { type CodeAgentApprovalPolicy, type CodeAgentBuiltinTool, type CodeAgentInteractionMode, type CodeAgentMcpAuthState, type CodeAgentMcpServerRef, type CodeAgentMcpStatus, type CodeAgentModelInfo, type CodeAgentPresetName, type CodeAgentProfile, type CodeAgentProviderInfo, type CodeAgentSubagentBudget, codeAgentDeniedPaths, codeAgentPresets, codeAgentReadOnlyBuiltins, isCodeAgentPresetName, } from "./codeAgentProfile.d.ts";
+export { type CodeAgentAnswer, type CodeAgentApprovalRequest, type CodeAgentCommand, type CodeAgentCommandType, type CodeAgentEffort, type CodeAgentEvent, type CodeAgentEventBody, type CodeAgentEventType, type CodeAgentFrame, type CodeAgentImage, type CodeAgentQuestion, type CodeAgentQuestionOption, type CodeAgentReply, type CodeAgentRequest, type CodeAgentSessionInfo, type CodeAgentStartOptions, type CodeAgentState, type CodeAgentStopReason, type CodeAgentSubagent, type CodeAgentToolOp, type CodeAgentToolOutcome, type CodeAgentToolSummary, codeAgentClip, codeAgentEventLabel, codeAgentEventPersistence, codeAgentLabelChars, codeAgentOutputChars, codeAgentRenderAnswer, codeAgentSessionName, codeAgentShouldPersist, codeAgentWireVersion, isCodeAgentReply, } from "./codeAgentWire.d.ts";
+export { EventStream, type EventStreamOptions } from "./eventStream.d.ts";
 export { type FileUploadCapability, fileUploadContract, resolveFileUploadCapability, } from "./fileUpload.d.ts";
 export { formatNumber } from "./formatNumber.d.ts";
-export { formatPhone } from "./formatPhone.d.ts";
-export { getAllPropertyDescriptors } from "./getAllPropertyDescriptors.d.ts";
 export { type AkanHmrPhase, getAkanHmrPhase, isAkanHmrApplying } from "./hmrPhase.d.ts";
 export { interpolateTranslation } from "./interpolateTranslation.d.ts";
 export { isDayjs } from "./isDayjs.d.ts";
 export { isEmail } from "./isEmail.d.ts";
-export { isPhoneNumber } from "./isPhoneNumber.d.ts";
 export { isQueryEqual } from "./isQueryEqual.d.ts";
+export { isRecord } from "./isRecord.d.ts";
 export { isThenable } from "./isThenable.d.ts";
 export { isValidDate } from "./isValidDate.d.ts";
 export { decodeJwtPayload } from "./jwtDecode.d.ts";
 export { type LogAttrs, type LogAttrValue, type LogFormat, Logger, type LoggerEmitInput, type LoggerSink, type LoggerSinkEntry, type LoggerSinkOptions, type LogLevel, type LogLevelInput, type LogRecord, logFormats, logLevels, logSeverity, } from "./Logger.d.ts";
 export { type AkanI18nConfig, type AkanI18nConfigInput, DEFAULT_AKAN_I18N, parseAkanI18nEnv, resolveAkanI18nConfig, } from "./localeConfig.d.ts";
 export { type LogContextReader, type LogContextSnapshot, type LogFlightRecorder, readLogContext, registerLogContextReader, } from "./logContext.d.ts";
-export { lowerlize } from "./lowerlize.d.ts";
+export { type MarkdownBlock, MarkdownBlocks, type MarkdownItem } from "./markdownBlocks.d.ts";
+export { type MarkdownSpan, MarkdownSpans } from "./markdownSpans.d.ts";
+export { type Align, MarkdownTable, type TableBlock } from "./markdownTable.d.ts";
 export { isMcpDescribableArg, type McpExposureEndpoint, type McpExposureOption, mcpBaseVerbOf, mcpHintsOf, mcpRefusalOf, } from "./mcpExposure.d.ts";
-export { mergeVersion } from "./mergeVersion.d.ts";
-export { objectify } from "./objectify.d.ts";
-export { pathGet } from "./pathGet.d.ts";
-export { pathGetLoose } from "./pathGetLoose.d.ts";
-export { pathSet } from "./pathSet.d.ts";
-export { plainFieldsOf } from "./plainFieldsOf.d.ts";
-export { randomPick } from "./randomPick.d.ts";
-export { randomPicks } from "./randomPicks.d.ts";
+export { deepObjectify, objectify, plainFieldsOf } from "./objectify.d.ts";
+export { pathGet, pathGetLoose, pathSet, toPathSegments } from "./objectPath.d.ts";
+export { formatPhone, isPhoneNumber } from "./phone.d.ts";
+export { randomPick, randomPicks } from "./randomPick.d.ts";
 export { hostFromRequest, isJsonContentType, originFromRequest } from "./requestOrigin.d.ts";
 export { RestClient, type RestClientOptions, type RestRequestOptions } from "./restClient.d.ts";
+export { round } from "./round.d.ts";
 export { assertUniqueRoutePatterns, compareRouteSpecificity, getPageSourceFileViolation, getRouteExports, isRouteSourceFile, isSpecialRouteLeaf, LAYOUT_ROUTE_EXPORTS, matchRoutePattern, normalizeRoutePattern, PAGE_ROUTE_EXPORTS, type ParsedRouteModuleKey, parseRouteModuleKey, RESERVED_ROUTE_CONFIG_EXPORTS, ROOT_LAYOUT_ROUTE_EXPORTS, type RouteModuleKind, routeSegmentToPatternPart, routeSegmentToTreePath, tryParseRouteModuleKey, type ValidatePageSourceFileOptions, type ValidateSubRoutePageKeyOptions, validatePageSourceFile, validateSubRoutePageKey, } from "./routeConvention.d.ts";
 export { sleep } from "./sleep.d.ts";
-export { splitVersion } from "./splitVersion.d.ts";
 export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute.d.ts";
 export { TrustedProxy } from "./TrustedProxy.d.ts";
+export { toError } from "./toError.d.ts";
+export { type TunnelAgentIdentity, type TunnelAttachedFrame, type TunnelAttachFrame, type TunnelByeFrame, type TunnelCloseCode, type TunnelControlFromAgent, type TunnelControlFromGateway, type TunnelDataFromAgent, type TunnelDataFromGateway, type TunnelDemandFrame, type TunnelEndFrame, type TunnelFrame, type TunnelHeaderList, type TunnelHeadFrame, type TunnelHelloFrame, type TunnelOpenFrame, type TunnelPingFrame, type TunnelPongFrame, type TunnelReadyFrame, type TunnelReleaseFrame, type TunnelResetCode, type TunnelResetFrame, type TunnelStreamKind, type TunnelWsPayloadKind, tunnelCloseCode, tunnelForwardedHeaders, tunnelHopByHopHeaders, tunnelWireContract, tunnelWsPayload, } from "./tunnelWire.d.ts";
 export type * from "./types.d.ts";
-export { type WebsocketAuthAckData, type WebsocketAuthRequest, websocketAuthContract, } from "./websocketAuth.d.ts";
-export { type WebsocketBinaryFrame, websocketBinaryFrameContract } from "./websocketBinaryFrame.d.ts";
+export { mergeVersion, splitVersion } from "./version.d.ts";
+export { type WebsocketAuthAckData, type WebsocketAuthRequest, type WebsocketBinaryFrame, type WebsocketHeartbeatAckData, type WebsocketHeartbeatRequest, websocketAuthContract, websocketBinaryFrameContract, websocketHeartbeatContract, } from "./websocketContract.d.ts";

package/types/common/interpolateTranslation.d.ts

@@ -1,7 +1,2 @@
-/**
- * Fills `{name}` placeholders in a translated string.
- *
- * A placeholder whose value is absent is left as written: the author's `{name}` reads as a bug in the UI, while
- * the string "undefined" reads as content, and a partially supplied `data` must not corrupt the rest of the line.
- */
+/** A `{name}` placeholder whose value is absent is left as written, never replaced by "undefined". */
 export declare const interpolateTranslation: (message: string, data: Record<string, unknown> | undefined) => string;

package/types/common/isEmail.d.ts

@@ -1,2 +1 @@
-/** Returns true when the value matches the email format accepted by Akan forms. */
 export declare const isEmail: (email?: string | null) => boolean;

package/types/common/isRecord.d.ts

@@ -0,0 +1 @@
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;

package/types/common/isThenable.d.ts

@@ -1,9 +1 @@
-/**
- * Whether a value is awaitable. Duck-typed rather than `instanceof Promise` so a thenable produced by a
- * different realm or promise implementation still counts — a same-realm check silently misses those.
- *
- * `<Button>` uses this to decide whether a click handler is asynchronous: a handler that returns a
- * thenable gets the pending/success states, a plain one renders as an ordinary button. That makes the
- * distinction impossible to forget, unlike an explicit flag.
- */
 export declare const isThenable: (value: unknown) => value is PromiseLike<unknown>;

package/types/common/logContext.d.ts

@@ -1,5 +1,5 @@
 import type { LogRecord } from "./Logger.d.ts";
-/** A per-request ring the Logger hands every record to; the trace decides at its end whether any of it is shown. */
+/** A per-request ring of every record; the trace decides at its end whether any of it is shown. */
 export interface LogFlightRecorder {
     minSev: number;
     capture(record: LogRecord, written: boolean): void;

package/types/{ui/Agent → common}/markdownBlocks.d.ts

@@ -25,9 +25,6 @@ export type MarkdownBlock = {
     kind: "para";
     text: string;
 } | TableBlock;
-/**
- * Block scanner for assistant chat text — the CommonMark subset a model actually emits over this wire.
- */
 export declare class MarkdownBlocks {
     #private;
     static of(source: string): MarkdownBlock[];

package/types/common/markdownSpans.d.ts

@@ -0,0 +1,30 @@
+export type MarkdownSpan = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "code";
+    text: string;
+} | {
+    kind: "strong";
+    text: string;
+} | {
+    kind: "em";
+    text: string;
+} | {
+    kind: "del";
+    text: string;
+} | {
+    kind: "link";
+    text: string;
+    href: string;
+}
+/** A link whose href was refused, or an image: rendered as its label, by every host. */
+ | {
+    kind: "plain";
+    text: string;
+};
+export declare class MarkdownSpans {
+    static of(text: string): MarkdownSpan[];
+    static isSafeHref(href: string): boolean;
+    static plain(text: string): string;
+}

package/types/{ui/Agent → common}/markdownTable.d.ts

@@ -5,8 +5,6 @@ export interface TableBlock {
     head: string[];
     rows: string[][];
 }
-/** GFM table scan, kept out of the block scanner because the delimiter row makes it the one shape that has to
- *  read the line after the one it starts on. */
 export declare class MarkdownTable {
     #private;
     static at(lines: string[], at: number): {

package/types/common/mcpExposure.d.ts

@@ -1,13 +1,3 @@
-/**
- * What MCP says about one endpoint: whether it is published, why it is not, and the hints it carries.
- *
- * Structurally typed like the rest of `common/` so the same rules answer on both sides — the server builds its
- * catalogue from them and the browser API explorer badges an endpoint from them. A second implementation would
- * eventually disagree, and an audit surface that disagrees with the catalogue is worse than none.
- *
- * Every rejection returns the sentence an author reads, at boot in the server log and in the explorer. Fail-closed
- * with no reason leaves an author whose endpoint is missing from the catalogue nowhere to look but the source.
- */
 export interface McpExposureEndpoint {
     type: string;
     returns: {
@@ -27,26 +17,17 @@ export interface McpExposureEndpoint {
     agents?: boolean;
 }
 export interface McpExposureOption {
-    /** The model the endpoint belongs to and the name it is published under: one rule reads the key, not the shape. */
     refName: string;
     key: string;
-    /**
-     * The read-only deployment valve, which is server configuration. The browser explorer cannot know it and so
-     * badges what the code decided; the boot log is where a read-only deployment says what it dropped.
-     */
+    /** The read-only deployment valve: server configuration the browser explorer cannot know. */
     readOnly?: boolean;
 }
-/** `Any` publishes as the empty schema, which tells a model nothing — so it is left out rather than described. */
+/** `Any` publishes as the empty schema, which tells a model nothing, so it is left out. */
 export declare const isMcpDescribableArg: (arg: {
     refName: string;
 }) => boolean;
-/** Which CRUD verb a generated endpoint key is, or `null` when the key is not one of the five. */
 export declare const mcpBaseVerbOf: (refName: string, key: string) => "get" | "create" | "update" | "remove" | null;
-/**
- * The hints a client renders beside a tool. Hints only — clients are told to distrust them, so they inform a UI
- * and never stand in for a guard. `openWorldHint` is always false: every endpoint reaches this app's own
- * database, not the wider internet.
- */
+/** Hints never stand in for a guard; `openWorldHint` is false: every endpoint reaches this app's own database. */
 export declare const mcpHintsOf: (key: string, endpoint: {
     type: string;
 }) => {
@@ -55,5 +36,4 @@ export declare const mcpHintsOf: (key: string, endpoint: {
     idempotentHint: boolean;
     openWorldHint: boolean;
 };
-/** The sentence explaining why this endpoint is not in the catalogue, or `null` when it is. */
 export declare const mcpRefusalOf: (endpoint: McpExposureEndpoint, { refName, key, readOnly }: McpExposureOption) => string | null;

package/types/common/objectPath.d.ts

@@ -0,0 +1,10 @@
+type PathSegment = string | number;
+type Indexable = Record<PathSegment, unknown>;
+export declare const isIndexable: (value: unknown) => value is Indexable;
+/** `a.0.b` and `a[0].b` are the same segments, for writes and reads alike. */
+export declare const toPathSegments: (path: string | readonly PathSegment[]) => any[];
+export declare const pathGet: (path: string | (string | number)[], obj: unknown, separator?: string, fallback?: unknown) => unknown;
+export declare const pathSet: <T>(obj: T, path: string | readonly PathSegment[], value: unknown) => T;
+/** Also tries joined prefixes, for keys whose segments contain the separator (an enum value like `gpt-5.6-terra`). */
+export declare const pathGetLoose: (path: string | readonly string[], obj: unknown, separator?: string, fallback?: unknown) => unknown;
+export {};

package/types/common/objectify.d.ts

@@ -1 +1,8 @@
 export declare const objectify: <T extends object>(obj: T, keys?: (keyof T)[]) => Partial<T>;
+export declare const plainFieldsOf: (source: object) => Record<string, unknown>;
+interface DeepObjectifyOption {
+    serializable?: boolean;
+    convertDate?: "string" | "number";
+}
+export declare const deepObjectify: <T = unknown>(obj: T | null | undefined, option?: DeepObjectifyOption) => T;
+export {};

package/types/common/phone.d.ts

@@ -0,0 +1,2 @@
+export declare const isPhoneNumber: (phone?: string | null) => boolean;
+export declare const formatPhone: (value: string) => string;

package/types/common/randomPick.d.ts

@@ -1 +1,2 @@
 export declare const randomPick: <T = unknown>(arr: T[] | readonly T[]) => T;
+export declare const randomPicks: <T>(arr: T[] | readonly T[], count?: number, allowDuplicate?: boolean) => T[];