akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/types/signal/mcp/McpProgress.d.ts

@@ -0,0 +1,40 @@
+export interface McpProgressOption {
+    /** Denominator for the ratio a client renders. Omit when the amount of work is not known up front. */
+    total?: number;
+    /** One short line describing the current step. Shown to the user, so keep it prose rather than a status code. */
+    message?: string;
+}
+export interface McpProgressReport extends McpProgressOption {
+    progress: number;
+}
+/**
+ * The progress channel for one streamed MCP call.
+ *
+ * Reached through `AsyncLocalStorage` rather than a parameter so an endpoint reports progress from wherever the
+ * work actually happens — a service, an adapter, a loop several frames down — without every signature between
+ * here and there growing a channel argument. Outside a streamed call `report` is a no-op, so the same endpoint
+ * code runs unchanged over plain HTTP, a websocket, or a test.
+ */
+export declare class McpProgress {
+    #private;
+    /**
+     * Reports progress for the call running on this stack. Silent when nothing is listening, which is every call
+     * that did not ask for a stream.
+     */
+    static report(progress: number, option?: McpProgressOption): void;
+    /** True while the caller is streaming, so an expensive progress message can be skipped when nobody reads it. */
+    static get streaming(): boolean;
+    static run<T>(channel: McpProgress, exec: () => Promise<T>): Promise<T>;
+    /** Resolves on the first report and never otherwise — a call that reports nothing has nothing to stream. */
+    readonly started: Promise<void>;
+    constructor();
+    /**
+     * Aborted when the client closes the response stream, which is how cancellation is signalled over this
+     * transport. Long-running work may watch it; the framework cannot force an `exec` already in flight to stop.
+     */
+    get signal(): AbortSignal;
+    /** Yields every report until the call finishes. Buffered ones come out first, so none is lost to a late reader. */
+    reports(): AsyncGenerator<McpProgressReport>;
+    end(): void;
+    abort(): void;
+}

package/types/signal/mcp/McpUriTemplate.d.ts

@@ -0,0 +1,26 @@
+export interface McpResourceTarget {
+    endpointKey: string;
+    args: Record<string, string | string[]>;
+}
+/**
+ * Two-way map between an `akan://` resource URI and the endpoint that answers it.
+ *
+ * Parsing is done by hand rather than through `URL`: `akan:` is a non-special scheme, and how a runtime
+ * normalizes the authority of one (case, percent-decoding) is exactly where a camelCase refName like
+ * `agentSession` would quietly stop matching its model.
+ */
+export declare class McpUriTemplate {
+    #private;
+    static readonly scheme = "akan";
+    static model(refName: string): string;
+    static light(refName: string): string;
+    /**
+     * The model's own unfiltered list is the bare `…/list`, never `…/list/<token>`. A named slice occupies the
+     * third segment, and a slice key is an author-chosen identifier — so any token put there for the root list
+     * would be one a slice could also be called, and the two would publish the same uri with only one of them
+     * readable. `list` in the *second* segment is already reserved against a model id, so there is nothing to
+     * collide with here.
+     */
+    static list(refName: string, sliceKey: string, argNames: string[]): string;
+    static parse(uri: string): McpResourceTarget | null;
+}

package/types/signal/mcp/Msg.d.ts

@@ -0,0 +1,143 @@
+import { type MaskModel } from "akanjs/constant";
+import type { JsonSchema } from "../schema.d.ts";
+export type PromptRole = "user" | "assistant";
+/**
+ * What a client may do with a block when it cannot keep all of them.
+ *
+ * `priority` is the field that matters here: a prompt this server assembles is often mostly context — a document
+ * embedded beside the one line asking for something — and a client with a full window drops blocks by this number
+ * rather than by position. Leaving it off means every block is equally droppable, so the instruction can go and
+ * the attachment stay.
+ */
+export interface PromptAnnotations {
+    /** Who the block is for. A note meant only for the model is `["assistant"]`, so a UI need not render it. */
+    audience?: PromptRole[];
+    /** 0 is "drop this first", 1 is "this is the point of the prompt". Anything outside the range is refused. */
+    priority?: number;
+    /** ISO 8601. Lets a client tell a re-fetched resource from the copy it already holds. */
+    lastModified?: string;
+}
+export interface PromptTextContent {
+    type: "text";
+    text: string;
+    annotations?: PromptAnnotations;
+}
+export interface PromptBinaryContent {
+    type: "image" | "audio";
+    data: string;
+    mimeType: string;
+    annotations?: PromptAnnotations;
+}
+export interface PromptResourceLinkContent {
+    type: "resource_link";
+    uri: string;
+    /** Required by the spec: `ResourceLink` extends `BaseMetadata`, whose `name` is not optional. */
+    name: string;
+    description?: string;
+    mimeType?: string;
+    annotations?: PromptAnnotations;
+}
+export interface PromptEmbeddedResourceContent {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType: string;
+        text: string;
+    };
+    annotations?: PromptAnnotations;
+}
+export type PromptContent = PromptTextContent | PromptBinaryContent | PromptResourceLinkContent | PromptEmbeddedResourceContent;
+export interface PromptMessage {
+    role: PromptRole;
+    content: PromptContent;
+}
+/** What a `prompt()` exec may return. A bare string is the 80% case and is wrapped into one user message. */
+export type PromptResult = string | PromptMessage[];
+/** Enough of the `File` model to link or inline it, structural so the framework does not depend on the lib. */
+export interface PromptFileSource {
+    url: string;
+    filename?: string;
+    mimetype?: string;
+}
+/**
+ * A model class, named by the caller so an attachment can be masked by what it *is* rather than by what it still
+ * carries at runtime. The same model any other audience masks by — see `mask` in `akanjs/constant`.
+ */
+export type PromptModel = MaskModel;
+/**
+ * Builds the messages a `prompt()` endpoint returns.
+ *
+ * Named `Msg` rather than `msg` because `akanjs/dictionary` already exports a `msg` for toasts.
+ *
+ * Every attachment builder carries the `user` role. Content the server assembles is context handed *to* the
+ * model, which is what the user role means; an assistant-role attachment would be the server putting words in the
+ * model's mouth. That is only meaningful for few-shot text, which `Msg.assistant` covers.
+ */
+export declare class Msg {
+    #private;
+    /**
+     * What every `prompt()` route answers with, as JSON Schema, for the app's OpenAPI document.
+     *
+     * A prompt declares `Any` on the wire, so the generated response schema was `{}` — a documented `GET` whose body
+     * the document could not describe, which is half of the agreement the HTTP route was mounted for. The shape is
+     * fixed by the protocol rather than by the endpoint, so it is written once, here: the block types and the fields
+     * each must carry come off `contentFields`, so a type added to one cannot describe itself out of the other.
+     */
+    static readonly schema: JsonSchema;
+    static user(text: string, annotations?: PromptAnnotations): PromptMessage;
+    static assistant(text: string, annotations?: PromptAnnotations): PromptMessage;
+    /**
+     * Embeds the value itself. The payload travels in the prompt, so prefer `link` for anything large.
+     *
+     * Name the model it is an instance of and the `hidden`/`secret` fields are stripped before it goes out:
+     * `Msg.resource(uri, order, { model: cnst.Order })`. A payload you assembled yourself needs no model and is
+     * embedded as given — but one that still carries a document's secret fields is refused rather than sent, so
+     * the rule is the same either way: a document travels masked, or it does not travel.
+     */
+    static resource(uri: string, value: unknown, { model, ...annotations }?: {
+        model?: PromptModel;
+    } & PromptAnnotations): PromptMessage;
+    /**
+     * Strips what a model marks `hidden` or `secret`, by the model the caller names rather than by the one the
+     * value happens to still carry.
+     *
+     * That distinction is the whole fix. A check that reads the class off the value can only mask what arrives as an
+     * instance, so a `{ ...doc }` spread, a `toJSON()`, or a round-trip through `JSON.stringify` reached the wire
+     * with the metadata already gone and nothing could be done about it. A named model is metadata the value cannot
+     * lose, so a hydrated document and a plain object copied out of one mask identically.
+     *
+     * This is the field half of `resolveReturn` and deliberately not the whole of it. That one also loads every
+     * relation it walks past, which is right for a query's return value and wrong for an attachment, where it would
+     * turn embedding one document into a fan of queries nobody asked for. So a populated relation is masked in
+     * place and one that is still an id is left as an id.
+     *
+     * Public because a payload can be an assembly of several documents — `{ order, customer }` names no single
+     * model, so each piece is masked on its way in.
+     *
+     * Returns `unknown` rather than the argument's type, because what comes back is missing fields that type still
+     * promises. The value's only destination is a JSON payload, so nothing downstream wanted the type anyway.
+     */
+    static mask(model: PromptModel, value: unknown): unknown;
+    /**
+     * Points at something without paying for it. The client decides whether to fetch, and skips what it already
+     * holds — so a prompt that references twenty documents costs twenty URIs rather than twenty payloads.
+     */
+    static link(source: string | PromptFileSource, { name, description, ...annotations }?: {
+        name?: string;
+        description?: string;
+    } & PromptAnnotations): PromptMessage;
+    static image(data: string, mimeType: string, annotations?: PromptAnnotations): PromptMessage;
+    static audio(data: string, mimeType: string, annotations?: PromptAnnotations): PromptMessage;
+    /**
+     * Inlines a file as base64, costing roughly 1.33× its bytes in the prompt. Worth it only when the client
+     * cannot fetch the URL itself — a public asset is cheaper as `Msg.link`. Fetched as this process, so a file
+     * behind a caller-scoped signed URL needs its bytes passed to `Msg.image` instead.
+     */
+    static imageOf(file: PromptFileSource, annotations?: PromptAnnotations): Promise<PromptMessage>;
+    /**
+     * The one runtime check on a prompt's return value. `prompt()` carries `Any` on the wire so the signal
+     * pipeline hands the value back untouched — nothing upstream would notice a malformed message, and the client
+     * would receive it as a valid prompt.
+     */
+    static normalize(value: unknown): PromptMessage[];
+}

package/types/signal/mcp/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./McpDocument.d.ts";
+export * from "./McpProgress.d.ts";
+export * from "./McpUriTemplate.d.ts";
+export * from "./Msg.d.ts";
+export * from "./mcpProtocol.d.ts";

package/types/signal/mcp/mcpProtocol.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Wire vocabulary for the MCP revisions this server answers.
+ *
+ * `2026-07-28` made the protocol stateless — no `initialize`, no session id, no server-opened stream — which is
+ * what makes a single `POST /mcp` route sufficient. Everything before it is the *legacy* era, still what shipping
+ * clients speak (measured: Claude Code 2.1.226 negotiates `2025-11-25`), and supporting it costs almost nothing
+ * here because a legacy server *may* decline to issue `Mcp-Session-Id`: without one the client sends no session
+ * header and never asks to resume a stream, so both eras run over the same stateless handler.
+ *
+ * `2025-06-18` is listed for the same reason. The surface this server actually implements — POST-only Streamable
+ * HTTP, no sessions, no server-initiated requests — is wire-identical between the two legacy revisions, and a
+ * client that proposes a version the server does not list is told to disconnect. Naming only the one revision that
+ * was measured turned "we tested against this" into "we refuse everything else".
+ */
+export declare const MCP_MODERN_VERSION = "2026-07-28";
+export declare const MCP_LEGACY_VERSION = "2025-11-25";
+export declare const MCP_LEGACY_PRIOR_VERSION = "2025-06-18";
+/** Newest first — `server/discover` and `initialize` both answer with this order, and `#negotiate` reads the ends. */
+export declare const MCP_SUPPORTED_VERSIONS: readonly ["2026-07-28", "2025-11-25", "2025-06-18"];
+export type McpProtocolVersion = (typeof MCP_SUPPORTED_VERSIONS)[number];
+export type McpEra = "modern" | "legacy";
+export declare const MCP_META_PREFIX = "io.modelcontextprotocol/";
+export declare const MCP_META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+export declare const MCP_META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+export declare const MCP_META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
+export declare const MCP_META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+/**
+ * `-32020`..`-32099` is reserved by the spec, so nothing outside this table may be minted in that band.
+ * `-32002` (resource not found) is retired in the modern revision; unknown resources are `invalidParams`.
+ *
+ * The band also defines `-32021 missingRequiredClientCapability`, which is absent because this server requires
+ * none: it never samples, elicits, or reads roots. It belongs here the day one of those appears, not before — a
+ * constant nothing emits reads as a check someone forgot to write.
+ */
+export declare const McpErrorCode: {
+    readonly parse: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internal: -32603;
+    readonly headerMismatch: -32020;
+    readonly unsupportedProtocolVersion: -32022;
+};
+export type McpErrorCodeValue = (typeof McpErrorCode)[keyof typeof McpErrorCode];
+export interface McpJsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: string | number | null;
+    method?: string;
+    params?: Record<string, unknown>;
+}
+export interface McpToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+export interface McpTool {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: McpToolAnnotations;
+}
+export interface McpResourceTemplate {
+    uriTemplate: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface McpResource {
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface McpPromptArgument {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+/**
+ * A prompt is user-controlled — the client offers it as a slash command and the model never invokes it — so its
+ * `title` and `description` are read by a person, not inferred from a schema the way a tool's are.
+ */
+export interface McpPrompt {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments?: McpPromptArgument[];
+}
+export interface McpTextContent {
+    type: "text";
+    text: string;
+}
+export interface McpToolResult {
+    content: McpTextContent[];
+    structuredContent?: unknown;
+    isError?: boolean;
+}
+export interface McpResourceContents {
+    uri: string;
+    mimeType: string;
+    text: string;
+}

package/types/signal/mcp.d.ts

@@ -0,0 +1 @@
+export * from "./mcp/index.d.ts";

package/types/signal/openapi/openapi.d.ts

@@ -1,5 +1,5 @@
+import { type JsonSchema } from "../schema.d.ts";
 import type { SerializedSignal } from "../types.d.ts";
-type OpenApiSchema = Record<string, unknown>;
 type OpenApiOperation = Record<string, unknown>;
 type OpenApiPathItem = Record<string, OpenApiOperation>;
 export interface OpenApiDocumentOptions {
@@ -27,8 +27,8 @@ export interface OpenApiDocument {
     }[];
     paths: Record<string, OpenApiPathItem>;
     components: {
-        schemas: Record<string, OpenApiSchema>;
-        securitySchemes?: Record<string, OpenApiSchema>;
+        schemas: Record<string, JsonSchema>;
+        securitySchemes?: Record<string, JsonSchema>;
     };
 }
 export declare const createOpenApiDocument: (serializedSignal: Record<string, SerializedSignal>, options?: OpenApiDocumentOptions) => OpenApiDocument;

package/types/signal/schema/JsonSchemaBuilder.d.ts

@@ -0,0 +1,47 @@
+import { type ConstantCls } from "akanjs/constant";
+import type { SerializedArg, SerializedReturns } from "../types.d.ts";
+export type JsonSchema = Record<string, unknown>;
+export interface JsonSchemaBuilderOptions {
+    /**
+     * Where a model `$ref` points. OpenAPI collects every model under `components/schemas`, while MCP requires each
+     * tool schema to resolve on its own and so embeds its models in a per-schema `$defs`.
+     */
+    refPrefix?: string;
+}
+export interface JsonSchemaModelOptions {
+    /**
+     * Drops `hidden` and `secret` fields. `SignalContext.resolveReturn` strips both from every response, so naming
+     * them describes a value the caller can never read — and on a model like `user` the names are themselves the
+     * leak: `password`, `accountId`, `phone` published as readable properties of the model. This is the one place a
+     * field the framework blocks on every value path is still visible, so it is scoped to schemas that describe a
+     * *response*. A request body is a different shape and legitimately carries both.
+     */
+    readable?: boolean;
+}
+/**
+ * Turns serialized signal metadata and Akan constants into JSON Schema (2020-12 by default, which is also what
+ * OpenAPI 3.1 uses). One builder per output dialect target — `new` it at the call site, it holds no shared state.
+ */
+export declare class JsonSchemaBuilder {
+    #private;
+    constructor({ refPrefix }?: JsonSchemaBuilderOptions);
+    arg(arg: SerializedArg): JsonSchema;
+    upload(arg: SerializedArg): JsonSchema;
+    returns(returns: SerializedReturns): JsonSchema;
+    model(modelRef: ConstantCls, { readable }?: JsonSchemaModelOptions): JsonSchema;
+    /** Every registered model, keyed by schema name. Callers narrow this with `referencedSchemas`. */
+    allModelSchemas(options?: JsonSchemaModelOptions): Record<string, JsonSchema>;
+    /**
+     * The models `seed` references, plus everything those transitively reference, sorted by name.
+     *
+     * `allSchemas` is derived from the registry, so a caller that narrows many seeds against the same registry —
+     * MCP builds one per tool schema and one per output schema — passes its own copy rather than rebuilding every
+     * registered model each time. Holding it here instead would make this builder stateful, and the one in
+     * `openapi.ts` lives at module scope for the life of the process.
+     */
+    referencedSchemas(seed: unknown, allSchemas?: Record<string, JsonSchema>): {
+        [k: string]: JsonSchema;
+    };
+    collectRefNames(value: unknown): Set<string>;
+    static primitive(refName: string): JsonSchema;
+}

package/types/signal/schema/index.d.ts

@@ -0,0 +1 @@
+export * from "./JsonSchemaBuilder.d.ts";

package/types/signal/schema.d.ts

@@ -0,0 +1 @@
+export * from "./schema/index.d.ts";

package/types/signal/signalContext.d.ts

@@ -21,13 +21,19 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
     args: unknown[];
     internalArgs: unknown[];
     trace: SignalTrace | null;
-    constructor(key: string, reqOrWsReq: Bun.BunRequest | WebSocketRequest, { endpointInfo, adaptor, registry, env, live, middleware, }: {
+    constructor(key: string, reqOrWsReq: Bun.BunRequest | WebSocketRequest, { endpointInfo, adaptor, registry, env, live, middleware, ctx, }: {
         endpointInfo: EndpointInfo;
         adaptor: Adaptor;
         registry: InjectRegistry;
         env: Env;
         live: LiveRegistry;
         middleware: Map<string, MiddlewareCls>;
+        /**
+         * Runs the endpoint against a caller-built context instead of one derived from the request. MCP needs it:
+         * its arguments arrive as one named object rather than in a URL, but every guard, middleware and
+         * internalArg reads the request through this context, so the transport has to stay the same one.
+         */
+        ctx?: Ctx;
     });
     getAdaptor<T extends Adaptor>(adaptorCls: AdaptorCls<T>): T;
     getService<T>(refName: string): T;
@@ -38,6 +44,15 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
      * while endpoint middlewares (cache/timeout/retry) would observe a call that never executes.
      */
     authorize(): Promise<boolean>;
+    /**
+     * Evaluates only the guards marked `static scope = "account"` — the ones that read the caller and nothing
+     * else — so a catalogue can hide entries the caller certainly cannot use.
+     *
+     * **Never an access gate.** An endpoint whose guards are all resource-scoped passes here and is stopped later
+     * by `#checkGuards` with the arguments those guards need. Erring visible is deliberate: a resource guard fails
+     * closed with no arguments, so evaluating one here would delete every legitimate entry from the listing.
+     */
+    canListForAccount(): Promise<boolean>;
     exec(): Promise<Response | undefined>;
     static try(endpoint: Adaptor, endpointInfo: EndpointInfo, key: string, fn: () => Promise<Response | undefined>): Promise<Response | undefined>;
     static resolveReturn(value: unknown, { signalContext, returnRef, arrDepth, registry, live, }: {

package/types/signal/slice.d.ts

@@ -1,8 +1,8 @@
-import { type Assign, type Cls, type MergeAllKeyOfObjects, SLICE_DICT_SHAPE, SLICE_META } from "akanjs/base";
+import { type Assign, type MergeAllKeyOfObjects, SLICE_DICT_SHAPE, SLICE_META } from "akanjs/base";
 import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { FilterInstance } from "akanjs/document";
 import { type Adaptor, type AdaptorCls, type ServiceModel } from "akanjs/service";
-import type { Guard, GuardCls } from "./guard.d.ts";
+import type { GuardCls } from "./guard.d.ts";
 import { type SliceBuilder, type SliceInfo, type SliceInfoArgNames, type SliceInfoArgs, type SliceInfoInternalArgs, type SliceInfoServerArgs, type SliceInfoSrvs } from "./sliceInfo.d.ts";
 import type { CnstFull, CnstInput, CnstInsight, CnstLight, DbFilter, SrvMap, SrvRefName } from "./types.d.ts";
 export type SliceDictArgShape = {
@@ -33,12 +33,12 @@ export type SliceCls<SrvModule extends ServiceModel = ServiceModel, SliceInfoObj
 };
 interface RootSliceOption {
     guards?: {
-        root?: Cls<Guard> | Cls<Guard>[];
-        get?: Cls<Guard> | Cls<Guard>[];
-        cru?: Cls<Guard> | Cls<Guard>[];
-        create?: Cls<Guard> | Cls<Guard>[];
-        update?: Cls<Guard> | Cls<Guard>[];
-        remove?: Cls<Guard> | Cls<Guard>[];
+        root?: GuardCls | GuardCls[];
+        get?: GuardCls | GuardCls[];
+        cru?: GuardCls | GuardCls[];
+        create?: GuardCls | GuardCls[];
+        update?: GuardCls | GuardCls[];
+        remove?: GuardCls | GuardCls[];
     };
     prefix?: string;
 }

package/types/signal/types.d.ts

@@ -102,7 +102,7 @@ export interface SerializedArg {
     enum?: string;
 }
 export interface SerializedEndpoint extends SerializedSignalOption {
-    type: "query" | "mutation" | "pubsub" | "message";
+    type: "query" | "mutation" | "pubsub" | "message" | "prompt";
     returns: SerializedReturns;
 }
 export interface SerializedFilter {

package/types/store/actionTag.d.ts

@@ -0,0 +1,21 @@
+/** Which module declared an action. The dictionary node its words live in is named after it. */
+export interface ActionOwner {
+    refName: string;
+}
+export interface ActionTag {
+    /** The `st.do` key this function is. */
+    action: string;
+    /** The state path it writes, when it writes exactly one — `userForm.name` for a field setter. */
+    state?: string;
+}
+/**
+ * Marks a dispatcher with what it does, so a component handed one by reference can say so in the DOM.
+ *
+ * `onChange={st.do.setNameOnUser}` is the house form for every model field, which means the component already holds
+ * everything an annotation needs — it just has no way to read it off a function. This is that way, and it is why
+ * `data-akan-*` costs an app no code at all: nobody writes the attribute, the setter carries its own name.
+ *
+ * Non-enumerable, so it survives neither `{...fn}` nor `JSON.stringify` and shows up in no spread.
+ */
+export declare const tagAction: <T extends (...args: never[]) => unknown>(fn: T, tag: ActionTag) => T;
+export declare const actionTagOf: (value: unknown) => ActionTag | undefined;

package/types/store/agent/AgentBridge.d.ts

@@ -0,0 +1,77 @@
+import type { AgentRefusal, JsonSchema, SerializedSignal } from "akanjs/signal";
+import type { StoreInstance } from "../storeInstance.d.ts";
+import type { AgentVisibility } from "./AgentVisibility.d.ts";
+import type { SerializedStoreState, StoreActionEffect } from "./types.d.ts";
+export interface AgentTool {
+    name: string;
+    title?: string;
+    description?: string;
+    /** One flat named object, the shape MCP publishes. The bridge maps it onto the action's positional parameters. */
+    inputSchema: JsonSchema;
+    effect: StoreActionEffect;
+}
+/** One call the agent made, in the order it made them. */
+export interface AgentCall {
+    name: string;
+    args: Record<string, unknown>;
+    at: Date;
+    error?: string;
+}
+export interface AgentBridgeOptions {
+    /** Resolves a dictionary key to its text. Defaults to the seeded `Translator` in the active locale. */
+    resolveDescription?: (key: string) => string | undefined;
+}
+/**
+ * What an in-page agent may do to the app the user is looking at.
+ *
+ * Every call goes through `st.do`, which is the same single dispatch point a click goes through — so the agent
+ * cannot reach past what the UI already lets this user do, the app re-renders from the write, and the user watches
+ * the result rather than being told about it. That is why the exposure default here is the opposite of the MCP
+ * catalogue's: an external agent's `tools/list` is an attack surface built out of names the operator never chose to
+ * publish, while this one is the user's own session, under their own credential, with them watching.
+ *
+ * It is deliberately not an agent. There is no model, no provider, and no key here — an app wires whichever it uses
+ * to `tools`, `call`, and `read`. The framework's half is the catalogue, the argument checking, the masking, and the
+ * transcript; the conversation is the app's.
+ */
+export declare class AgentBridge {
+    #private;
+    readonly refusals: AgentRefusal[];
+    /**
+     * The bridge for the app running in this process: the one store every `st.do` goes through, and every signal any
+     * client has applied. An app needs no arguments to reach its own agent surface.
+     */
+    static of(options?: AgentBridgeOptions): AgentBridge;
+    constructor(instance: StoreInstance, serializedSignal: Record<string, SerializedSignal>, options?: AgentBridgeOptions);
+    /**
+     * The catalogued actions of the stores the rendered screen is reading right now — the live view, recomputed as
+     * components mount and unmount. Global exposure was the first cut's behavior and it published levers the screen
+     * does not respond to; the screen's own subscriptions are the honest boundary.
+     */
+    get tools(): AgentTool[];
+    /** The live view one zone session reads: owners counted from the keys that zone's own subtree subscribes. */
+    toolsFor(viewKey: string): AgentTool[];
+    get visibility(): AgentVisibility;
+    get state(): {
+        [key: string]: SerializedStoreState;
+    };
+    get transcript(): readonly AgentCall[];
+    subscribe(listener: () => void): () => void;
+    /**
+     * The value behind a state key, stripped of what the model marks `hidden` or `secret`.
+     *
+     * Masking is not optional here even though the data mostly came from the server already masked: `<model>Form`
+     * holds what the *user* typed, credentials included, and an in-page agent ships what it reads to a remote model.
+     * The mask is by the declared model rather than by the value's class, because `immerify` copies a form into a
+     * plain object and the class is gone by the time anyone can ask.
+     */
+    read(key: string, viewKey?: string): unknown;
+    /**
+     * Dispatches through `st.do`, so what happens is what happens when the user clicks.
+     *
+     * Arguments arrive named and are mapped onto the action's parameters in declared order. An omitted optional one
+     * becomes `null`, which is what the slice query builders already expect; an omitted required one is refused,
+     * because the alternative is a call that writes `undefined` into state and reports success.
+     */
+    call(name: string, args?: Record<string, unknown>, viewKey?: string): Promise<void>;
+}

package/types/store/agent/AgentContext.d.ts

@@ -0,0 +1,16 @@
+import type { ContextBlock, SurfaceView } from "../../vendor/use-agentic.d.ts";
+import type { StoreInstance } from "../storeInstance.d.ts";
+import type { AgentBridge } from "./AgentBridge.d.ts";
+/**
+ * The akan default context for a turn: where the user is (route), what is on screen (scopes and their curated
+ * resources), and which store keys the mounted components are reading (live keys). Live entries carry names and
+ * small primitives only — anything bigger is one `readState` call away, masked — so the block cannot bloat with
+ * what happens to be in the store. Base-store keys are excluded by the base store's own `agent: false`
+ * declaration, and the route block carries the three of them that matter.
+ */
+export declare class AgentContext {
+    #private;
+    static of(): AgentContext;
+    constructor(instance: StoreInstance, bridge: AgentBridge);
+    blocks(surface: SurfaceView, view?: string[]): ContextBlock[];
+}

package/types/store/agent/AgentPrompts.d.ts

@@ -0,0 +1,31 @@
+import type { PromptContent, PromptResult, SerializedSignal } from "akanjs/signal";
+import type { ChatMessage } from "../../vendor/use-agentic.d.ts";
+export interface AgentPrompt {
+    name: string;
+    refName: string;
+    description?: string;
+    args: {
+        name: string;
+        required: boolean;
+    }[];
+}
+/**
+ * The user-invokable `prompt()` endpoints of the mounted app, read off the serialized signals the client already
+ * holds — the same catalogue MCP lists them from, so a chat needs no listing endpoint. Guards are not evaluated
+ * here: a prompt's own GET enforces them at call time, and the refusal lands in the transcript like any failure.
+ */
+export declare class AgentPrompts {
+    #private;
+    static of(): AgentPrompts;
+    constructor(signals: Record<string, SerializedSignal>);
+    list(): AgentPrompt[];
+    find(name: string): AgentPrompt | null;
+    /** `/name arg1 arg2` — positional because a prompt's arguments are flat strings by protocol. */
+    static parseCommand(draft: string): {
+        name: string;
+        args: string[];
+    } | null;
+    /** The messages a prompt returns become the user's turn, the way an MCP client sends a `prompts/get` result. */
+    static messagesOf(result: PromptResult): ChatMessage[];
+    static textOf(content: PromptContent): string;
+}

package/types/store/agent/AgentVisibility.d.ts

@@ -0,0 +1,21 @@
+import type { StoreAgentExposure } from "../types.d.ts";
+/**
+ * Which stores the agent surface may show, derived from the registry: every registered store's state keys name
+ * their owner, and a store's `static agent` declaration is its own exposure decision. Liveness rides on top —
+ * `liveOwners` maps the subscribed keys back to store refNames, so the published surface follows the rendered
+ * screen instead of the whole bundle.
+ */
+export declare class AgentVisibility {
+    #private;
+    stateOwner(key: string): string | undefined;
+    /** The stores that declared an exposure of their own, for the catalogue's refusal lines. */
+    declaredExposures(): Map<string, StoreAgentExposure>;
+    visibleKey(key: string): boolean;
+    visibleAction(name: string, ownerRefName?: string): boolean;
+    /**
+     * The stores the rendered screen is reading right now: owners of the subscribed, still-visible keys. A key no
+     * registered store owns has no module to activate, and an action with no owner stays published — only fabricated
+     * stores outside the registry produce either.
+     */
+    liveOwners(liveKeys: ReadonlyMap<string, number>): Set<string>;
+}