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

package/types/service/predefinedAdaptor/deepseekLlm.d.ts

@@ -0,0 +1,64 @@
+import type { AgentWireMessage, LlmAdaptor, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
+interface DeepseekToolCall {
+    id?: string;
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+}
+interface DeepseekAnswer {
+    choices?: {
+        message?: {
+            content?: string | null;
+            tool_calls?: DeepseekToolCall[];
+        };
+        finish_reason?: string;
+    }[];
+}
+interface DeepseekMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    tool_calls?: {
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }[];
+    tool_call_id?: string;
+}
+declare const DeepseekLlm_base: import("..").AdaptorCls<{}, {
+    llmOption: import("..").InjectInfo<"use", LlmOption, never, never>;
+}>;
+export declare class DeepseekLlm extends DeepseekLlm_base implements LlmAdaptor {
+    #private;
+    chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
+    /**
+     * The dialect streams `data: {chunk}` SSE lines ending with `data: [DONE]`. Tool calls arrive fragmented — the
+     * first fragment of an index carries id/name, later ones append to the arguments string — so they are assembled
+     * by index and parsed once at the end; only assistant text is worth reporting as it arrives.
+     */
+    static consumeStream(body: ReadableStream<Uint8Array>, onDelta: (delta: string) => void): Promise<LlmTurnAnswer>;
+    /** DeepSeek speaks the OpenAI chat-completions dialect, so the wire→provider mapping lives here in one place. */
+    static requestBody(model: string, request: LlmTurnRequest, stream?: boolean): {
+        tools?: {
+            type: "function";
+            function: {
+                parameters: Record<string, unknown>;
+                description?: string | undefined;
+                name: string;
+            };
+        }[] | undefined;
+        messages: DeepseekMessage[];
+        stream?: boolean | undefined;
+        model: string;
+    };
+    /** Context rides below the instructions framed as data — screen state must never read as directives. */
+    static systemPrompt({ instructions, context }: LlmTurnRequest): string;
+    static providerMessages(message: AgentWireMessage): DeepseekMessage[];
+    static turnAnswer(answer: DeepseekAnswer): LlmTurnAnswer;
+    /** The provider sends arguments as a JSON string; an unparsable one becomes an empty call rather than a crash. */
+    static parsedArgs(raw: string | undefined): Record<string, unknown>;
+}
+export {};

package/types/service/predefinedAdaptor/index.d.ts

@@ -1,6 +1,9 @@
 export * from "./cache.adaptor";
 export * from "./compress.adaptor";
 export * from "./database.adaptor";
+export * from "./deepseekLlm.d.ts";
+export * from "./insightQuery.d.ts";
+export * from "./llm.adaptor";
 export * from "./logging.adaptor";
 export * from "./queue.adaptor";
 export * from "./role.adaptor";

package/types/service/predefinedAdaptor/insightQuery.d.ts

@@ -0,0 +1,50 @@
+import type { AkanSqlClient } from "./database.adaptor";
+export interface InsightQueryOptions {
+    /** Rows to return at most. Clamped to `InsightQuery.maxRows`, which no caller can raise. */
+    limit?: number;
+    /** How long to wait for the driver, in ms. See the note on `#raced` for which dialects this can actually stop. */
+    timeoutMs?: number;
+}
+export interface InsightQueryResult {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    /** The ceiling cut the answer short, so the caller knows not to read it as complete. */
+    truncated: boolean;
+}
+/**
+ * One read-only SQL statement, for an agent or an operator asking a question the domain endpoints cannot express.
+ *
+ * This is the layer-bypassing read, and every safeguard the framework has is bypassed with it — guards, soft delete,
+ * cascade, `_postRemove`, and the `hidden`/`secret` masking every other response path performs. So it is read-only
+ * by construction rather than by convention, and it is deliberately *not* wired to an endpoint here: the framework
+ * owns no guard strong enough to sit in front of it. An app that wants it writes the endpoint with its own
+ * `SuperAdmin`, the same way guards ship with the library that owns the model.
+ *
+ * Three things enforce read-only, and only the third is ours:
+ *
+ * 1. The statement is wrapped as a derived table — `SELECT * FROM (<sql>) AS "akanInsight" LIMIT ?`. Nothing but a
+ *    query is legal in that position, in either dialect, so a write is a syntax error from the engine rather than a
+ *    pattern this code had to recognise. A second statement smuggled behind `;` is a syntax error for the same
+ *    reason, and the row ceiling rides along on the same wrapper.
+ * 2. A rejection before execution, so the caller reads why rather than a syntax error. It runs on the statement with
+ *    comments and string literals removed, because that is what makes `-- ` and `'…'` unable to hide anything.
+ * 3. **`_doc` never crosses the boundary.** Every non-base field lives in that one JSON column, which is where the
+ *    plan's "re-apply schema-based masking" runs into the fact that an arbitrary SELECT has no model to mask by. So
+ *    the enforceable rule is the column itself: unnameable in the statement, dropped from the rows, and any cell
+ *    that still arrives holding a JSON object or array is refused. An insight is made of scalars; a value that is
+ *    not one is either a document or indistinguishable from it.
+ *
+ * What that costs is real and worth saying: this answers "how many, since when, grouped how" over base columns and
+ * the search mirror, and it cannot read a domain field. Field-level reads go through the domain tools, which mask.
+ */
+export declare class InsightQuery {
+    #private;
+    /** Not an option. A caller asking for more gets this, because the point is that no caller sets the ceiling. */
+    static readonly maxRows = 1000;
+    constructor(client: AkanSqlClient);
+    run(sql: string, { limit, timeoutMs }?: InsightQueryOptions): Promise<{
+        columns: string[];
+        rows: Record<string, unknown>[];
+        truncated: boolean;
+    }>;
+}

package/types/service/predefinedAdaptor/llm.adaptor.d.ts

@@ -0,0 +1,68 @@
+export interface AgentWireToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface AgentWireToolResult {
+    id: string;
+    name: string;
+    result?: unknown;
+    changes?: unknown[];
+    error?: string;
+}
+/**
+ * One transcript message of the in-page agent wire (`use-agentic`'s WIRE.md), typed at both ends independently —
+ * the wire is the contract, so the server never imports the client package.
+ */
+export interface AgentWireMessage {
+    role: "user" | "assistant" | "tool";
+    text?: string;
+    toolCalls?: AgentWireToolCall[];
+    toolResults?: AgentWireToolResult[];
+    error?: string;
+}
+export interface AgentWireTool {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    effect?: string;
+    needsConfirm?: boolean;
+}
+export interface AgentWireContext {
+    kind: string;
+    [key: string]: unknown;
+}
+export interface LlmTurnRequest {
+    messages: AgentWireMessage[];
+    tools: AgentWireTool[];
+    context: AgentWireContext[];
+    instructions?: string;
+}
+export interface LlmTurnAnswer {
+    text?: string;
+    toolCalls?: AgentWireToolCall[];
+    stop: "end" | "toolUse";
+}
+/**
+ * The provider seam for one stateless agent turn: the whole transcript in, one assistant answer out. The server
+ * relays — it never executes a client tool — so this is the only surface a provider integration fills. An
+ * implementation is an `adapt()` class in a lib's `srvkit/` and follows the adapter convention: failures are
+ * logged and answered as `null`, and the calling service decides what that means.
+ */
+export interface LlmAdaptor {
+    /**
+     * `onDelta` opts into streaming: the adapter reports assistant text as it arrives and still resolves the full
+     * answer. An adapter may ignore it — the caller treats zero reported deltas as "answered whole".
+     */
+    chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
+}
+/**
+ * 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.
+ */
+export interface LlmOption {
+    apiKey?: string;
+    model?: string;
+    host?: string;
+}

package/types/service/predefinedAdaptor/role.adaptor.d.ts

@@ -2,6 +2,7 @@ import { type AdaptorCls } from "../adapt.d.ts";
 import type { CacheAdaptor } from "./cache.adaptor";
 import type { CompressAdaptor } from "./compress.adaptor";
 import type { DatabaseAdaptor } from "./database.adaptor";
+import type { LlmAdaptor } from "./llm.adaptor";
 import type { LoggingAdaptor } from "./logging.adaptor";
 import type { QueueAdaptor } from "./queue.adaptor";
 import type { ScheduleAdaptor } from "./schedule.adaptor";
@@ -15,3 +16,4 @@ export declare const ScheduleAdaptorRole: AdaptorCls<ScheduleAdaptor>;
 export declare const LoggingAdaptorRole: AdaptorCls<LoggingAdaptor>;
 export declare const WebsocketAdaptorRole: AdaptorCls<WebsocketAdaptor>;
 export declare const CompressAdaptorRole: AdaptorCls<CompressAdaptor>;
+export declare const LlmAdaptorRole: AdaptorCls<LlmAdaptor>;

package/types/service/predefinedAdaptor/schedule.adaptor.d.ts

@@ -1,9 +1,13 @@
-import { Cron } from "croner";
+/** The scheduler's own job handle, so the cron backend stays behind this interface. `Bun.cron` satisfies it. */
+export interface AkanCronJob {
+    readonly cron: string;
+    stop(): void;
+}
 export interface ScheduleAdaptor {
-    getCron(key: string): Cron | undefined;
+    getCron(key: string): AkanCronJob | undefined;
     registerCron(key: string, cronStr: string, callback: () => Promise<void>, option?: {
         lock?: boolean;
-    }): Cron;
+    }): AkanCronJob;
     unregisterCron(key: string): void;
     getInterval(key: string): NodeJS.Timeout | undefined;
     registerInterval(key: string, scheduleTime: number, callback: () => Promise<void>, option?: {
@@ -29,15 +33,15 @@ declare const Scheduler_base: import("..").AdaptorCls<{}, {
 }>;
 export declare class Scheduler extends Scheduler_base implements ScheduleAdaptor {
     readonly lockMap: Map<string, boolean>;
-    readonly cronMap: Map<string, Cron<undefined>>;
+    readonly cronMap: Map<string, AkanCronJob>;
     readonly intervalMap: Map<string, NodeJS.Timeout>;
     readonly timeoutMap: Map<string, NodeJS.Timeout>;
     readonly initMap: Map<string, () => Promise<void>>;
     readonly destroyMap: Map<string, () => Promise<void>>;
-    getCron(key: string): Cron<undefined> | undefined;
+    getCron(key: string): AkanCronJob | undefined;
     registerCron(key: string, cronStr: string, callback: () => Promise<void>, { lock }?: {
         lock?: boolean;
-    }): Cron<undefined>;
+    }): Bun.CronJob;
     unregisterCron(key: string): void;
     getInterval(key: string): NodeJS.Timeout | undefined;
     registerInterval(key: string, scheduleTime: number, callback: () => Promise<void>, { lock }?: {

package/types/service/types.d.ts

@@ -1,7 +1,7 @@
 import type { Cls, MergeAllTypes, PromiseOrObject } from "akanjs/base";
 import type { Logger } from "akanjs/common";
 import type { QueryOf } from "akanjs/constant";
-import type { CRUDEventType, DatabaseModel, DataInputOf, FilterInstance, FindQueryOption, GetDocObject, ListQueryOption, QueryMethodPart, SaveEventType, UpdateResult } from "akanjs/document";
+import type { CRUDEventType, DatabaseModel, DataInputOf, DocumentUpdateInput, FilterInstance, FindQueryOption, GetDocObject, ListQueryOption, QueryMethodPart, SaveEventType, UpdateResult } from "akanjs/document";
 type ServiceMixinOmitKey = "onInit" | "onDestroy" | "_libsOnInit" | "_libsOnDestroy" | "_preCreate" | "_postCreate" | "_preUpdate" | "_postUpdate" | "_preRemove" | "_postRemove" | "_libsPreCreate" | "_libsPostCreate" | "_libsPreUpdate" | "_libsPostUpdate" | "_libsPreRemove" | "_libsPostRemove";
 type DatabaseQueryMethods<Query, Sort, Obj, Doc, Insight, FindQueryOption, ListQueryOption, DocQuery> = QueryMethodPart<Query, Sort, Obj, Doc, Insight, FindQueryOption, ListQueryOption, DocQuery>;
 type DocumentLike = {
@@ -32,6 +32,9 @@ export type DatabaseService<T extends string = string, Input = any, Doc = any, O
     __update: (id: string, data: Partial<Doc>) => Promise<Doc>;
     __remove: (id: string) => Promise<Doc>;
     __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;
+    __removeOne: (query: _QueryOfDoc) => Promise<UpdateResult>;
+    __updateMany: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
+    __updateOne: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
     __list(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<Doc[]>;
     __listIds(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<string[]>;
     __find(query?: _QueryOfDoc, queryOption?: _FindQueryOption): Promise<Doc | null>;

package/types/signal/agent/AgentCatalogue.d.ts

@@ -0,0 +1,100 @@
+import { mcpBaseVerbOf } from "akanjs/common";
+import type { SerializedEndpoint, SerializedSignal, SerializedSlice } from "../types.d.ts";
+/** Where an endpoint came from, which is what decides where an audience's opt-in for it can be written. */
+export type AgentOrigin = "base" | "slice" | "endpoint";
+/** Which generated CRUD verb a `base` candidate is. Its opt-in lives on the signal, not on the endpoint. */
+export type AgentBaseVerb = NonNullable<ReturnType<typeof mcpBaseVerbOf>>;
+/** One endpoint a signal registry holds, before any audience has decided anything about it. */
+export interface AgentCandidate {
+    refName: string;
+    key: string;
+    endpoint: SerializedEndpoint;
+    origin: AgentOrigin;
+    /** The signal it belongs to. A generated verb carries no option of its own, so its opt-in is written here. */
+    signal: SerializedSignal;
+    /** The slice this key was generated from, where the opt-in for a `slice` candidate is written. */
+    slice?: SerializedSlice;
+    baseVerb?: AgentBaseVerb;
+}
+/** An opt-in a catalogue did not honour, with the reason it did not. */
+export interface AgentRefusal {
+    key: string;
+    reason: string;
+}
+/** A published entry carrying no description its author wrote, and what to write so that it does. */
+export interface AgentUndescribed {
+    key: string;
+    reason: string;
+}
+export interface AgentCatalogueOptions {
+    resolveDescription?: (key: string) => string | undefined;
+    excludeSignals?: string[];
+}
+/**
+ * The half of an agent catalogue that does not depend on who is asking.
+ *
+ * Enumerating what a signal registry holds, keeping that order stable, holding one name per entry, and resolving
+ * the words a module wrote in its dictionary are the same work for every audience — an external MCP client, an
+ * in-page agent driving the store, a transport that does not exist yet. What differs is only which option admits
+ * an endpoint and what shape it is published in, and both of those stay with the audience that decides them.
+ *
+ * Separated while exactly one audience existed. The cost then is moving code between two files; the cost later is
+ * telling two audiences apart inside one class that never expected a second.
+ */
+export declare class AgentCatalogue {
+    #private;
+    /**
+     * Everything a registry holds, in an order that does not move between boots: clients cache a catalogue, and an
+     * LLM prompt cache keys on its exact text, so an order that depends on object iteration is a cache that misses.
+     *
+     * Every endpoint is listed, including ones no audience will take. Deciding is the caller's half.
+     */
+    static candidates(serializedSignal: Record<string, SerializedSignal>, { excludeSignals }?: {
+        excludeSignals?: string[];
+    }): AgentCandidate[];
+    /**
+     * What opted in and was refused anyway. Collected rather than merely dropped so a server can say so at boot:
+     * the rejections an audience makes are fail-closed by design, and an author whose deliberate opt-in vanished
+     * from the catalogue otherwise has nowhere to look but the framework source.
+     */
+    readonly refusals: AgentRefusal[];
+    constructor(options?: AgentCatalogueOptions);
+    /**
+     * What is published with no description of its own. Description is the one field a model picks an entry by, so
+     * one without it is a broken entry rather than an untidy one — and a source scanner cannot answer this: it
+     * reads files, where an opt-in is visible only as a literal in a builder call and where the model `.desc()`
+     * every generated entry borrows is not written as a description of the entry at all.
+     */
+    get undescribed(): AgentUndescribed[];
+    /**
+     * Takes the name for this entry, or refuses it because something else already holds it.
+     *
+     * A name must be unique within a catalogue, across every kind of entry it publishes. Keys are globally unique
+     * by construction, so a collision means two signals disagree — the first in candidate order keeps it, which is
+     * what makes the catalogue the same on the next boot either way.
+     */
+    claim(key: string): boolean;
+    refuse(key: string, reason: string): void;
+    texts(titleKey: string, descKey?: string): {
+        description?: string | undefined;
+        title?: string | undefined;
+    };
+    /**
+     * Every entry the framework generates borrows the model's own words, because none of them has any of its own.
+     *
+     * `slice()` generates the root slice under the empty key and `baseSliceDictionary` fills its text, so
+     * `<model>List` and `<model>Insight` publish as "Slice List - Universal" whatever the dictionary says. The five
+     * base CRUD entries are no better off: `getBaseSignalDictionary` writes "Get Banner" as both title and
+     * description, and both are assigned last, so a module author has nowhere to write over either one.
+     *
+     * That matters more here than anywhere else — description is the one field a model picks an entry by, and "Get
+     * Banner" says nothing about what a Banner is. So the model's `.desc()` is appended rather than substituted:
+     * on `removeBanner` a bare model description would read as if the tool returned one. And when the model has no
+     * `.desc()` either, the entry is recorded as undescribed — its only possible text is missing, and that is the
+     * one thing a source scanner cannot see.
+     */
+    entryTexts(refName: string, key: string): {
+        description?: string | undefined;
+        title?: string | undefined;
+    };
+}

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

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

package/types/signal/agent.d.ts

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

package/types/signal/agent.signal.d.ts

@@ -0,0 +1,29 @@
+import { Any } from "akanjs/base";
+import { AgentTurn } from "./agentTurn.d.ts";
+declare const AgentInternal_base: import("./internal.d.ts").InternalCls<import("akanjs/service").ServiceModel<typeof import("akanjs/service").AgentService, any, any, {
+    agentService: import("akanjs/service").AgentService;
+}>, {
+    warnOpenRelay: import("./internalInfo.d.ts").InternalInfo<"init", {
+        agentService: import("akanjs/service").AgentService;
+    }, [], [], [], typeof Any, void, false>;
+}>;
+export declare class AgentInternal extends AgentInternal_base {
+}
+declare const AgentEndpoint_base: import("./endpoint.d.ts").EndpointCls<import("akanjs/service").ServiceModel<typeof import("akanjs/service").AgentService, any, any, {
+    agentService: import("akanjs/service").AgentService;
+}>, {
+    runAgentTurn: import("./endpointInfo.d.ts").EndpointInfo<"mutation", {
+        agentService: import("akanjs/service").AgentService;
+    }, ["messages", "tools", "context", "instructions"], [arg: unknown[], arg: unknown[], arg: unknown[], arg?: string | null | undefined], [arg: Bun.BunRequest<string>], [arg: unknown[], arg: unknown[], arg: unknown[], arg: string | undefined], typeof AgentTurn, AgentTurn, Promise<AgentTurn | {
+        text: string;
+        toolCalls: import("akanjs/service").AgentWireToolCall[];
+        stop: "end" | "toolUse";
+    }>, false>;
+}>;
+export declare class AgentEndpoint extends AgentEndpoint_base {
+}
+declare const Agent_base: import("./serverSignal.d.ts").ServerSignalCls<typeof AgentEndpoint, typeof AgentInternal>;
+export declare class Agent extends Agent_base {
+}
+export declare const agent: import("./signalRegistry.d.ts").ServiceSignal<typeof AgentInternal, typeof AgentEndpoint, typeof Agent>;
+export {};

package/types/signal/agentTurn.d.ts

@@ -0,0 +1,9 @@
+export { AgentStop, AgentTurn, agentTurnConstant } from "akanjs/fetch";
+declare const AgentTurnDocument_base: import("akanjs/document").DatabaseCls<{
+    text: string;
+    toolCalls: unknown[];
+    stop: NonNullable<"end" | "toolUse">;
+} & {}>;
+export declare class AgentTurnDocument extends AgentTurnDocument_base {
+}
+export declare const agentTurnDocument: import("akanjs/document").DatabaseCls<AgentTurnDocument>;

package/types/signal/agentTurnStream.d.ts

@@ -0,0 +1,16 @@
+import type { AgentWireToolCall } from "akanjs/service";
+interface StreamedTurn {
+    text?: string;
+    toolCalls?: AgentWireToolCall[];
+    stop?: "end" | "toolUse";
+}
+/**
+ * The streaming half of the agent turn wire (use-agentic WIRE.md): the same endpoint answers `text/event-stream`
+ * when the request asks for it, one RunnerEvent JSON per SSE `data:` line, ending with `done`. The signal layer
+ * passes a raw `Response` through untouched, which is what lets one mutation serve both shapes.
+ */
+export declare class AgentTurnStream {
+    static wants(request: Bun.BunRequest): boolean;
+    static response(run: (onDelta: (delta: string) => void) => Promise<StreamedTurn>): Response;
+}
+export {};

package/types/signal/base.signal.d.ts

@@ -31,7 +31,7 @@ declare const Base_base: import("./serverSignal.d.ts").ServerSignalCls<typeof Ba
 export declare class Base extends Base_base {
 }
 export declare const base: import("./signalRegistry.d.ts").ServiceSignal<typeof BaseInternal, typeof BaseEndpoint, typeof Base>;
-export declare const fetch: import("akanjs/fetch").FetchClientType<[import("./signalRegistry.d.ts").ServiceSignal<typeof BaseInternal, typeof BaseEndpoint, typeof Base>]>;
+export declare const fetch: import("akanjs/fetch").FetchClientType<[import("./signalRegistry.d.ts").ServiceSignal<typeof BaseInternal, typeof BaseEndpoint, typeof Base>, import("./signalRegistry.d.ts").ServiceSignal<typeof import("./agent.signal").AgentInternal, typeof import("./agent.signal").AgentEndpoint, typeof import("./agent.signal").Agent>]>;
 export declare const getSerializedSignal: () => {
     [key: string]: import("./types.d.ts").SerializedSignal;
 };

package/types/signal/endpointInfo.d.ts

@@ -1,9 +1,21 @@
-import { type Dayjs, type EnumInstance, type PromiseOrObject } from "akanjs/base";
+import { Any, type Dayjs, type EnumInstance, type PromiseOrObject } from "akanjs/base";
 import type { ConstantFieldType, ConstantFieldTypeInput, DocumentModel, FieldToValue, ParamFieldType, PlainTypeToFieldType, PurifiedModel, UploadableClientArg } from "akanjs/constant";
 import type { ServiceModel } from "akanjs/service";
 import type { InternalArgCls } from "./internalArg.d.ts";
+import type { PromptResult } from "./mcp.d.ts";
 import type { ArgType, SignalOption, SrvMap } from "./types.d.ts";
-export type EndpointType = "query" | "mutation" | "pubsub" | "message";
+export type EndpointType = "query" | "mutation" | "pubsub" | "message" | "prompt";
+/**
+ * A prompt travels as `Any` because `PrimitiveRegistry.has(Any)` is true, so `resolveReturn` and `makeResponse`
+ * hand the messages back untouched. Registering a scalar for `PromptMessage` would buy nothing the builder's
+ * `exec` constraint does not already give, and would push a client-side model into every app that never uses one.
+ *
+ * It does not follow that a prompt's payload is unmasked. What a return ref masks is the value's own fields, and
+ * a prompt's are fixed by the protocol; the document inside an attachment is a JSON string by the time any return
+ * ref could reach it. So masking is declared at the attachment instead — `Msg.mask` — where the model is named
+ * and a payload that lost its class on the way still masks correctly.
+ */
+declare const promptCarrier: typeof Any;
 export interface EndpointArgProps<Optional extends boolean = false> {
     nullable?: Optional;
     example?: string | number | boolean | Dayjs;
@@ -34,6 +46,7 @@ export declare class EndpointInfo<ReqType extends EndpointType = EndpointType, S
 } = {
     [key: string]: any;
 }, ArgNames extends string[] = any, Args extends any[] = any, InternalArgs extends any[] = any, ServerArgs extends any[] = any, Returns extends ConstantFieldTypeInput = ConstantFieldTypeInput, ClientReturns = never, ServerReturns = never, Nullable extends boolean = boolean> {
+    #private;
     readonly type: ReqType;
     readonly argNames: ArgNames;
     readonly args: ArgInfo<EndpointArgProps<boolean>>[];
@@ -52,7 +65,7 @@ export declare class EndpointInfo<ReqType extends EndpointType = EndpointType, S
     _addArgs(args: ArgInfo<EndpointArgProps<boolean>>[]): this;
     with<ArgType, Optional extends boolean = false>(argRef: InternalArgCls<ArgType>, option?: InternalArgProps<Optional>): EndpointInfo<ReqType, Srvs, ArgNames, Args, [...InternalArgs, arg: NonNullable<ArgType> | (Optional extends true ? null : never)], ServerArgs, Returns, ClientReturns, ServerReturns, Nullable>;
     _addInternalArgs(args: InternalArgInfo<boolean>[]): this;
-    exec<ExecFn extends (this: Srvs, ...args: [...ServerArgs, ...InternalArgs]) => ReqType extends "pubsub" ? Promise<void> | void : PromiseOrObject<DocumentModel<FieldToValue<Returns>> | (Nullable extends true ? null | undefined : never)>>(execFn: ExecFn): EndpointInfo<ReqType, Srvs, ArgNames, Args, InternalArgs, ServerArgs, Returns, FieldToValue<Returns>, ReturnType<ExecFn>, Nullable>;
+    exec<ExecFn extends (this: Srvs, ...args: [...ServerArgs, ...InternalArgs]) => ReqType extends "pubsub" ? Promise<void> | void : ReqType extends "prompt" ? PromiseOrObject<PromptResult> : PromiseOrObject<DocumentModel<FieldToValue<Returns>> | (Nullable extends true ? null | undefined : never)>>(execFn: ExecFn): EndpointInfo<ReqType, Srvs, ArgNames, Args, InternalArgs, ServerArgs, Returns, FieldToValue<Returns>, ReturnType<ExecFn>, Nullable>;
     getPath(key: string): string;
 }
 export type BuildEndpoint<SrvModule extends ServiceModel = ServiceModel> = {
@@ -60,6 +73,11 @@ export type BuildEndpoint<SrvModule extends ServiceModel = ServiceModel> = {
     mutation: <Returns extends ConstantFieldTypeInput = ConstantFieldTypeInput, Nullable extends boolean = false>(returnRef: Returns, signalOption?: SignalOption<Returns, Nullable>) => EndpointInfo<"mutation", SrvMap<SrvModule>, [], [], [], [], Returns, never, never, Nullable>;
     pubsub: <Returns extends ConstantFieldTypeInput = ConstantFieldTypeInput, Nullable extends boolean = false>(returnRef: Returns, signalOption?: SignalOption<Returns, Nullable>) => EndpointInfo<"pubsub", SrvMap<SrvModule>, [], [], [], [], Returns, never, never, Nullable>;
     message: <Returns extends ConstantFieldTypeInput = ConstantFieldTypeInput, Nullable extends boolean = false>(returnRef: Returns, signalOption?: SignalOption<Returns, Nullable>) => EndpointInfo<"message", SrvMap<SrvModule>, [], [], [], [], Returns, never, never, Nullable>;
+    /**
+     * Declares an MCP prompt. It takes no return type because the return is always `PromptMessage[]`, and no
+     * `.body()` because `prompts/get` sends its arguments as a flat string map — see `param`.
+     */
+    prompt: (signalOption?: SignalOption<typeof promptCarrier, false>) => EndpointInfo<"prompt", SrvMap<SrvModule>, [], [], [], [], typeof promptCarrier, never, never, false>;
 };
 export declare const buildEndpoint: BuildEndpoint<any>;
 export type EndpointBuilder<SrvModule extends ServiceModel = ServiceModel> = (builder: BuildEndpoint<SrvModule>) => {

package/types/signal/guard.d.ts

@@ -3,8 +3,19 @@ import type { SignalContext } from "./signalContext.d.ts";
 export interface Guard {
     canPass(context: SignalContext): PromiseOrObject<boolean>;
 }
+/**
+ * What a guard needs in order to answer. `account` reads the caller and nothing else, so it can be evaluated
+ * with no arguments — which is what lets a catalogue hide what the caller certainly cannot use. `resource` needs
+ * the call's arguments and fails closed without them, so evaluating one early would erase legitimate entries.
+ *
+ * Required, with no default. Exposure is decided by a guard rather than by an opt-in, so an unmarked guard would
+ * silently take the `resource` path and list its endpoint to every caller — the whole guarded surface's names,
+ * refused only at call time. There is no safe guess here, so the author states it.
+ */
+export type GuardScope = "account" | "resource";
 export type GuardCls<Name extends string = string> = Cls<Guard, {
     readonly name: Name;
+    readonly scope: GuardScope;
 }>;
 /** Creates a named guard base class for signal access checks. */
 export declare const guard: <T extends string>(name: T) => GuardCls<T>;

package/types/signal/guards.d.ts

@@ -1,10 +1,31 @@
-import type { Guard } from "./guard.d.ts";
+import type { Guard, GuardScope } from "./guard.d.ts";
 import type { SignalContext } from "./signalContext.d.ts";
 export declare class Public implements Guard {
     static name: string;
+    static scope: GuardScope;
     canPass(context: SignalContext): boolean;
 }
 export declare class None implements Guard {
     static name: string;
+    static scope: GuardScope;
     canPass(context: SignalContext): boolean;
 }
+export type AgentRelayPolicy = (context: SignalContext) => boolean | Promise<boolean>;
+/**
+ * Gate for the `runAgentTurn` relay. Every tool runs in the caller's own browser session, so the LLM key is the
+ * one thing this endpoint spends — ungated, any visitor can bill the app's provider through fetch alone.
+ *
+ * The framework has no account model to gate on, so with no policy registered it allows everyone — what `Public`
+ * said before, but with a seam: a product hardens it at boot, e.g.
+ * `AgentRelayAccess.use((context) => !!context.get("account"))`. The policy is the app's; the framework cannot know it.
+ */
+export declare class AgentRelayAccess implements Guard {
+    #private;
+    static name: string;
+    static scope: GuardScope;
+    static use(policy: AgentRelayPolicy | null): void;
+    static get hasPolicy(): boolean;
+    /** Runs at boot, after the app entry has evaluated — a module-scope check would fire before `use()` could. */
+    static warnIfOpen(): void;
+    canPass(context: SignalContext): Promise<boolean>;
+}

package/types/signal/index.d.ts

@@ -1,3 +1,7 @@
+export * from "./agent.d.ts";
+export * from "./agent.signal";
+export * from "./agentTurn.d.ts";
+export * from "./agentTurnStream.d.ts";
 export * from "./base.signal";
 export * from "./endpoint.d.ts";
 export * from "./endpointInfo.d.ts";
@@ -8,8 +12,10 @@ export * from "./intercept.d.ts";
 export * from "./internal.d.ts";
 export * from "./internalArg.d.ts";
 export * from "./internalInfo.d.ts";
+export * from "./mcp.d.ts";
 export * from "./middleware.d.ts";
 export * from "./openapi.d.ts";
+export * from "./schema.d.ts";
 export * from "./serializer.d.ts";
 export * from "./serverSignal.d.ts";
 export * from "./signalContext.d.ts";

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

@@ -0,0 +1,65 @@
+import { type AgentRefusal, type AgentUndescribed } from "../agent.d.ts";
+import type { SerializedEndpoint, SerializedSignal } from "../types.d.ts";
+import type { McpPrompt, McpResource, McpResourceTemplate, McpTool } from "./mcpProtocol.d.ts";
+export interface McpDocumentOptions {
+    resolveDescription?: (key: string) => string | undefined;
+    excludeSignals?: string[];
+    /**
+     * Drops every mutation from the catalogue regardless of what it opted into. Off by default: the endpoint's own
+     * an endpoint's guards are the decision, and a second switch that silently unlists a published endpoint gives
+     * its author no way to see why. This is the read-only-deployment valve.
+     */
+    readOnly?: boolean;
+}
+export interface McpExposedEndpoint {
+    refName: string;
+    key: string;
+    endpoint: SerializedEndpoint;
+}
+/**
+ * A candidate this catalogue did not publish. The bookkeeping is audience-independent and lives on
+ * `AgentCatalogue`; these are the MCP names for it.
+ */
+export type McpRefusal = AgentRefusal;
+export type McpUndescribed = AgentUndescribed;
+/**
+ * Turns the serialized signal registry into the three MCP catalogues and answers the lookups `tools/call` and
+ * `resources/read` need. Pure: no IO and no DI — the sibling of `createOpenApiDocument`.
+ */
+export declare class McpDocument {
+    #private;
+    /**
+     * An array cannot be `structuredContent` — the spec types it as an object — so a list result is wrapped under
+     * this key and `outputSchema` is shaped to match. Both halves must agree, which is why they live together.
+     */
+    static readonly listKey = "items";
+    readonly tools: McpTool[];
+    readonly prompts: McpPrompt[];
+    readonly resourceTemplates: McpResourceTemplate[];
+    /** Every readable thing is addressed by a template, so there are no fixed resources to enumerate. */
+    readonly resources: McpResource[];
+    /**
+     * Every candidate that was not published, with the sentence saying why — the rejections are fail-closed by
+     * design, and an author whose endpoint is missing otherwise has nowhere to look but the framework source.
+     */
+    readonly refusals: McpRefusal[];
+    /** What is published with no description of its own, which is the field a model picks a tool by. */
+    readonly undescribed: McpUndescribed[];
+    constructor(serializedSignal: Record<string, SerializedSignal>, options?: McpDocumentOptions);
+    findTool(name: string): McpExposedEndpoint | undefined;
+    /** Returns the catalogue entry alongside the endpoint: `prompts/get` validates against the published one. */
+    findPrompt(name: string): {
+        exposed: McpExposedEndpoint;
+        prompt: McpPrompt;
+    } | undefined;
+    /**
+     * Resolves a URI only when the endpoint behind it was published as a template. An endpoint that was never
+     * advertised has to fail here rather than fall through to its guards: opting out of MCP means keeping a thing
+     * off the wire entirely, not merely making it refuse.
+     */
+    resolveResource(uri: string): {
+        exposed: McpExposedEndpoint;
+        args: Record<string, string | string[]>;
+    } | null;
+    static structuredContent(endpoint: SerializedEndpoint, value: unknown): {} | undefined;
+}