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

package/signal/agent/AgentCatalogue.ts

@@ -0,0 +1,165 @@
+import { mcpBaseVerbOf } from "akanjs/common";
+import { FetchClient } from "akanjs/fetch";
+import type { SerializedEndpoint, SerializedSignal, SerializedSlice } from "../types";
+
+/** 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 class AgentCatalogue {
+  /**
+   * 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 = ["base"] }: { excludeSignals?: string[] } = {},
+  ): AgentCandidate[] {
+    const excluded = new Set(excludeSignals);
+    const candidates: AgentCandidate[] = [];
+    for (const [refName, signal] of Object.entries(serializedSignal)) {
+      if (excluded.has(refName)) continue;
+      for (const [key, endpoint] of Object.entries(FetchClient.getBaseEndpoint(refName, signal))) {
+        const baseVerb = mcpBaseVerbOf(refName, key);
+        if (baseVerb) candidates.push({ refName, key, endpoint, origin: "base", signal, baseVerb });
+      }
+      for (const [suffix, slice] of Object.entries(signal.slice ?? {})) {
+        for (const [key, endpoint] of Object.entries(FetchClient.getEndpointFromSlice(refName, suffix, slice)))
+          candidates.push({ refName, key, endpoint, origin: "slice", signal, slice });
+      }
+      for (const [key, endpoint] of Object.entries(signal.endpoint))
+        candidates.push({ refName, key, endpoint, origin: "endpoint", signal });
+    }
+    return candidates.sort((a, b) => a.refName.localeCompare(b.refName) || a.key.localeCompare(b.key));
+  }
+
+  /**
+   * 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[] = [];
+
+  readonly #options: AgentCatalogueOptions;
+  readonly #claimed = new Set<string>();
+  /** Keyed so an entry read twice — once as a tool and again as a template — is reported once. */
+  readonly #undescribedByKey = new Map<string, string>();
+
+  constructor(options: AgentCatalogueOptions = {}) {
+    this.#options = options;
+  }
+
+  /**
+   * 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[] {
+    return [...this.#undescribedByKey].map(([key, reason]) => ({ key, reason }));
+  }
+
+  /**
+   * 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 {
+    if (this.#claimed.has(key)) {
+      this.refuse(key, "another endpoint is already published under this name.");
+      return false;
+    }
+    this.#claimed.add(key);
+    return true;
+  }
+
+  refuse(key: string, reason: string) {
+    this.refusals.push({ key, reason });
+  }
+
+  texts(titleKey: string, descKey = `${titleKey}.desc`) {
+    const title = this.#options.resolveDescription?.(titleKey);
+    const description = this.#options.resolveDescription?.(descKey);
+    return { ...(title ? { title } : {}), ...(description ? { description } : {}) };
+  }
+
+  /**
+   * 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) {
+    const borrowed = `its only text is the model's own, and \`${refName}\` has no \`.desc()\` to lend it.`;
+    if (key === `${refName}List` || key === `${refName}Insight`) {
+      const texts = this.texts(`${refName}.modelName`, `${refName}.modelDesc`);
+      if (!texts.description) this.#undescribedByKey.set(key, borrowed);
+      return texts;
+    }
+    const texts = this.texts(`${refName}.signal.${key}`);
+    if (!mcpBaseVerbOf(refName, key)) {
+      if (!texts.description)
+        this.#undescribedByKey.set(key, "it has no dictionary `.desc()`, so an agent has its name and nothing else.");
+      return texts;
+    }
+    const modelDesc = this.#options.resolveDescription?.(`${refName}.modelDesc`);
+    if (!modelDesc) this.#undescribedByKey.set(key, borrowed);
+    const generated = texts.description ?? texts.title;
+    return modelDesc ? { ...texts, description: generated ? `${generated} — ${modelDesc}` : modelDesc } : texts;
+  }
+}

package/signal/agent/index.ts

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

package/signal/agent.signal.ts

@@ -0,0 +1,42 @@
+import { Any } from "akanjs/base";
+import type { AgentWireContext, AgentWireMessage, AgentWireTool, LlmTurnRequest } from "akanjs/service";
+import { srv } from "akanjs/service";
+import { AgentTurn } from "./agentTurn";
+import { AgentTurnStream } from "./agentTurnStream";
+import { endpoint } from "./endpoint";
+import { AgentRelayAccess } from "./guards";
+import { internal } from "./internal";
+import { Req } from "./internalArg";
+import { serverSignal } from "./serverSignal";
+import { SignalRegistry } from "./signalRegistry";
+
+export class AgentInternal extends internal(srv.agent, ({ initialize }) => ({
+  warnOpenRelay: initialize().exec(() => {
+    AgentRelayAccess.warnIfOpen();
+  }),
+})) {}
+
+export class AgentEndpoint extends endpoint(srv.agent, ({ mutation }) => ({
+
+  runAgentTurn: mutation(AgentTurn, { guards: [AgentRelayAccess] })
+    .body("messages", [Any])
+    .body("tools", [Any])
+    .body("context", [Any])
+    .body("instructions", String, { nullable: true })
+    .with(Req)
+    .exec(async function (messages, tools, context, instructions, request) {
+      const turn: LlmTurnRequest = {
+        messages: messages as unknown as AgentWireMessage[],
+        tools: tools as unknown as AgentWireTool[],
+        context: context as unknown as AgentWireContext[],
+        ...(instructions ? { instructions } : {}),
+      };
+      if (AgentTurnStream.wants(request as Bun.BunRequest))
+        
+        return AgentTurnStream.response((onDelta) => this.agentService.runTurn(turn, onDelta)) as unknown as AgentTurn;
+      return await this.agentService.runTurn(turn);
+    }),
+})) {}
+
+export class Agent extends serverSignal(AgentEndpoint, AgentInternal) {}
+export const agent = SignalRegistry.registerService("agent" as const, AgentInternal, AgentEndpoint, Agent);

package/signal/agentTurn.ts

@@ -0,0 +1,8 @@
+import { by, DatabaseRegistry } from "akanjs/document";
+import { AgentTurn } from "akanjs/fetch";
+
+export { AgentStop, AgentTurn, agentTurnConstant } from "akanjs/fetch";
+
+export class AgentTurnDocument extends by(AgentTurn) {}
+
+export const agentTurnDocument = DatabaseRegistry.buildScalar("agentTurn" as const, AgentTurnDocument);

package/signal/agentTurnStream.ts

@@ -0,0 +1,48 @@
+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 class AgentTurnStream {
+  static wants(request: Bun.BunRequest): boolean {
+    return !!request.headers.get("accept")?.includes("text/event-stream");
+  }
+
+  static response(run: (onDelta: (delta: string) => void) => Promise<StreamedTurn>): Response {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream<Uint8Array>({
+      async start(controller) {
+        const send = (event: object) => controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
+        try {
+          let streamed = 0;
+          const turn = await run((delta) => {
+            if (!delta) return;
+            streamed += delta.length;
+            send({ type: "text", delta });
+          });
+          
+          if (!streamed && turn.text) send({ type: "text", delta: turn.text });
+          const toolCalls = turn.toolCalls ?? [];
+          for (const call of toolCalls) send({ type: "toolCall", id: call.id, name: call.name, args: call.args });
+          send({ type: "done", stop: turn.stop === "toolUse" || toolCalls.length ? "toolUse" : "end" });
+        } catch (error) {
+          
+          send({ type: "error", message: error instanceof Error ? error.message : String(error) });
+        } finally {
+          controller.close();
+        }
+      },
+    });
+    return new Response(stream, {
+      headers: { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" },
+    });
+  }
+}

package/signal/base.signal.ts

@@ -1,5 +1,6 @@
 import { FetchClient } from "akanjs/fetch";
 import { srv } from "akanjs/service";
+import { agent } from "./agent.signal";
 import { endpoint } from "./endpoint";
 import { internal } from "./internal";
 import { serverSignal } from "./serverSignal";
@@ -28,7 +29,7 @@ export class BaseEndpoint extends endpoint(srv.base, ({ query, mutation, message
 export class Base extends serverSignal(BaseEndpoint, BaseInternal) {}
 export const base = SignalRegistry.registerService("base" as const, BaseInternal, BaseEndpoint, Base);
 
-const createBaseFetch = () => FetchClient.from(base);
+const createBaseFetch = () => FetchClient.from(base, agent);
 type BaseFetch = ReturnType<typeof createBaseFetch>;
 
 let fetchCache: BaseFetch | undefined;

package/signal/endpointInfo.ts

@@ -1,4 +1,5 @@
 import {
+  Any,
   arraiedModel,
   type Cls,
   type Dayjs,
@@ -19,9 +20,22 @@ import type {
 } from "akanjs/constant";
 import type { ServiceModel } from "akanjs/service";
 import type { InternalArgCls } from "./internalArg";
+import type { PromptResult } from "./mcp";
 import type { ArgType, SignalOption, SrvMap } from "./types";
 
-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.
+ */
+const promptCarrier = Any;
 
 export interface EndpointArgProps<Optional extends boolean = false> {
   nullable?: Optional;
@@ -140,6 +154,7 @@ export class EndpointInfo<
     _ServerArg = DocumentModel<_ArgType>,
   >(name: ArgName, arg: Arg, option?: EndpointArgProps<Optional>) {
     if (this.execFn) throw new Error("Query function is already set");
+    this.#assertPromptArg("body");
     this.argNames.push(name);
     this.args.push(EndpointInfo.getArgInfo("body", name, arg, option));
     return this as unknown as EndpointInfo<
@@ -165,6 +180,7 @@ export class EndpointInfo<
   >(name: string, arg: Arg, option?: Omit<EndpointArgProps, "nullable">) {
     if (this.execFn) throw new Error("Query function is already set");
     else if (this.args.at(-1)?.option?.nullable) throw new Error("Last argument is nullable");
+    this.#assertPromptArg("room");
     this.argNames.push(name);
     this.args.push(EndpointInfo.getArgInfo("room", name, arg, option));
     return this as unknown as EndpointInfo<
@@ -191,6 +207,7 @@ export class EndpointInfo<
   >(name: string, arg: Arg, option?: EndpointArgProps<Optional>) {
     if (this.execFn) throw new Error("Query function is already set");
     else if (this.args.at(-1)?.option?.nullable) throw new Error("Last argument is nullable");
+    this.#assertPromptArg("msg");
     this.argNames.push(name);
     this.args.push(EndpointInfo.getArgInfo("msg", name, arg, option));
     return this as unknown as EndpointInfo<
@@ -230,6 +247,14 @@ export class EndpointInfo<
       Nullable
     >;
   }
+  /**
+   * `prompts/get` sends `arguments` as `{ [key: string]: string }` — there is no place in the request for an
+   * object body, and no socket behind a prompt for a room or a message. `param` and `search` survive because
+   * both already travel as text in a URL.
+   */
+  #assertPromptArg(argType: ArgType) {
+    if (this.type === "prompt") throw new Error(`A prompt takes .param() and .search() only, not .${argType}()`);
+  }
   _addArgs(args: ArgInfo<EndpointArgProps<boolean>>[]) {
     for (const arg of args) {
       const argRef = arraiedModel(arg.enum ?? arg.argRef, arg.arrDepth);
@@ -284,7 +309,9 @@ export class EndpointInfo<
       ...args: [...ServerArgs, ...InternalArgs]
     ) => ReqType extends "pubsub"
       ? Promise<void> | void
-      : PromiseOrObject<DocumentModel<FieldToValue<Returns>> | (Nullable extends true ? null | undefined : never)>,
+      : ReqType extends "prompt"
+        ? PromiseOrObject<PromptResult>
+        : PromiseOrObject<DocumentModel<FieldToValue<Returns>> | (Nullable extends true ? null | undefined : never)>,
   >(
     execFn: ExecFn,
   ): EndpointInfo<
@@ -342,6 +369,13 @@ export type BuildEndpoint<SrvModule extends ServiceModel = ServiceModel> = {
     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 const buildEndpoint = {
@@ -361,6 +395,8 @@ export const buildEndpoint = {
     returnRef: Returns,
     signalOption?: SignalOption<Returns, Nullable>,
   ) => new EndpointInfo("message", returnRef, signalOption),
+  prompt: (signalOption?: SignalOption<typeof promptCarrier, false>) =>
+    new EndpointInfo("prompt", promptCarrier, signalOption),
 } as unknown as BuildEndpoint<any>;
 
 export type EndpointBuilder<SrvModule extends ServiceModel = ServiceModel> = (builder: BuildEndpoint<SrvModule>) => {

package/signal/guard.ts

@@ -5,12 +5,24 @@ export interface Guard {
   canPass(context: SignalContext): PromiseOrObject<boolean>;
 }
 
-export type GuardCls<Name extends string = string> = Cls<Guard, { readonly name: Name }>;
+/**
+ * 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 const guard = <T extends string>(name: T): GuardCls<T> => {
   return class Guard {
     static name = name;
+    static scope: GuardScope = "account";
     canPass(context: SignalContext): PromiseOrObject<boolean> {
       return true;
     }

package/signal/guards.ts

@@ -1,8 +1,10 @@
-import type { Guard } from "./guard";
+import { Logger } from "akanjs/common";
+import type { Guard, GuardScope } from "./guard";
 import type { SignalContext } from "./signalContext";
 
 export class Public implements Guard {
   static name = "Public";
+  static scope: GuardScope = "account";
   canPass(context: SignalContext): boolean {
     return true;
   }
@@ -10,7 +12,56 @@ export class Public implements Guard {
 
 export class None implements Guard {
   static name = "None";
+  static scope: GuardScope = "account";
   canPass(context: SignalContext): boolean {
     return false;
   }
 }
+
+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 class AgentRelayAccess implements Guard {
+  
+  static name = "AgentRelayAccess";
+  
+  static scope: GuardScope = "account";
+  static #policy: AgentRelayPolicy | null = null;
+  static #logger = new Logger("AgentRelayAccess");
+
+  static use(policy: AgentRelayPolicy | null) {
+    AgentRelayAccess.#policy = policy;
+  }
+
+  static get hasPolicy() {
+    return !!AgentRelayAccess.#policy;
+  }
+
+  /** Runs at boot, after the app entry has evaluated — a module-scope check would fire before `use()` could. */
+  static warnIfOpen() {
+    if (AgentRelayAccess.#policy) return;
+    AgentRelayAccess.#logger.warn(
+      'runAgentTurn is open to every caller — anyone can spend the LLM key. Register a policy at boot: AgentRelayAccess.use((context) => !!context.get("account")), or set AKAN_AGENT=false.',
+    );
+  }
+
+  async canPass(context: SignalContext): Promise<boolean> {
+    const policy = AgentRelayAccess.#policy;
+    if (!policy) return true;
+    try {
+      return await policy(context);
+    } catch (error) {
+      AgentRelayAccess.#logger.warn(
+        `agent relay policy threw, failing closed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return false;
+    }
+  }
+}

package/signal/index.ts

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