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

package/types/server/tunnel/TunnelTcpStream.d.ts

@@ -0,0 +1,11 @@
+import { type TunnelOpenFrame } from "akanjs/common";
+import { type TunnelStream, type TunnelStreamLink } from "./tunnelStream.d.ts";
+/** A raw TCP stream to a local port (SSH); provider side only — nothing opens one in wire version 1 yet. */
+export declare class TunnelTcpStream implements TunnelStream {
+    #private;
+    constructor(open: TunnelOpenFrame, link: TunnelStreamLink, hostname: string);
+    run(): Promise<void>;
+    push(data: Uint8Array): void;
+    end(): void;
+    reset(): void;
+}

package/types/server/tunnel/TunnelWebsocketStream.d.ts

@@ -0,0 +1,10 @@
+import { type TunnelOpenFrame } from "akanjs/common";
+import { type TunnelStream, type TunnelStreamLink } from "./tunnelStream.d.ts";
+export declare class TunnelWebsocketStream implements TunnelStream {
+    #private;
+    constructor(open: TunnelOpenFrame, link: TunnelStreamLink, origin: string);
+    run(): Promise<void>;
+    push(data: Uint8Array): void;
+    end(): void;
+    reset(): void;
+}

package/types/server/tunnel/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./TunnelAgent.d.ts";
+export * from "./TunnelDataSocket.d.ts";
+export * from "./TunnelHttpStream.d.ts";
+export * from "./TunnelTcpStream.d.ts";
+export * from "./TunnelWebsocketStream.d.ts";
+export * from "./tunnelStream.d.ts";

package/types/server/tunnel/tunnelStream.d.ts

@@ -0,0 +1,19 @@
+import type { TunnelDataFromAgent, TunnelResetCode } from "akanjs/common";
+/** `sendPayload` resolves once the data socket has drained. */
+export interface TunnelStreamLink {
+    sendFrame: (frame: TunnelDataFromAgent) => void;
+    sendPayload: (data: Uint8Array) => Promise<void>;
+    closeSocket: () => void;
+}
+export interface TunnelStream {
+    /** Dials the local origin and answers with a `head`, then pumps until the origin is done. */
+    run: () => Promise<void>;
+    /** A payload frame from the gateway — a request body chunk, or an inner websocket/tcp message. */
+    push: (data: Uint8Array) => void;
+    /** The gateway has no more to send in its direction. */
+    end: () => void;
+    /** The gateway gave up, or the socket died under the stream. */
+    reset: () => void;
+}
+export declare const wsBytes: (data: Uint8Array) => Uint8Array<ArrayBuffer>;
+export declare const tunnelResetCodeOf: (error: unknown) => TunnelResetCode;

package/types/server/tunnel.d.ts

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

package/types/server/types.d.ts

@@ -64,18 +64,11 @@ export type BaseBuildArtifact = {
     i18n: AkanI18nConfig;
     imageConfig: AkanImageConfig;
     deepLinkAssociations?: MobileDeepLinkAssociation[];
-    /**
-     * Which surfaces this artifact was built for. Absent on an artifact written before the option existed,
-     * which is read as both on — the shape every such build actually has.
-     */
+    /** Surfaces this artifact was built for; absent (an artifact older than the option) reads as both on. */
     web?: AkanWebConfig;
 };
 export declare const resolveWebConfig: (web: Partial<AkanWebConfig> | undefined) => AkanWebConfig;
-/**
- * `AKAN_SSR` / `AKAN_CSR`, both on unless the env says otherwise — the same shape `AKAN_MCP` uses, because a
- * switch a deployment has to find before anything works is a switch most deployments never find. Read by the
- * gateway and by every replica, so both agree on what the pod serves.
- */
+/** Reads `AKAN_SSR` / `AKAN_CSR`: each is on unless set to `"false"` or `"0"`. */
 export declare const getWebConfigFromEnv: () => AkanWebConfig;
 export interface MobileDeepLinkAssociation {
     targetName: string;

package/types/server/webRouter.d.ts

@@ -7,7 +7,7 @@ import { type BuilderRpc, type RouteSeedIndex } from "./artifact.d.ts";
 import { type RouteCacheInvalidation, type RouteCacheRenderState } from "./cachePolicy.d.ts";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub.d.ts";
 import { type RscRedirectMethod, type RscRedirectStatus, type RscRenderResult, RscWorker } from "./rscWorkerHost.d.ts";
-import { type BaseBuildArtifact, type HttpRoutes, type RenderState } from "./types.d.ts";
+import { type BaseBuildArtifact, type RenderState } from "./types.d.ts";
 export declare const DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES: number;
 export declare function createRscRedirectResponse(location: string, method: RscRedirectMethod, status?: RscRedirectStatus): Response;
 export declare function createRscStreamResponse(stream: BodyInit, status?: number): Response;
@@ -26,13 +26,6 @@ export declare function resolveHtmlRouteCacheStoreTtl(input: {
         type: "redirect";
     } | null;
 }): number | null;
-export declare function isHtmlRouteCachePathAllowed(pathname: string, env?: {
-    [key: string]: string | undefined;
-    AKAN_HTML_RESULT_CACHE_PATHS?: string;
-    AKAN_HTML_RESULT_CACHE_EXCLUDE_PATHS?: string;
-}, options?: {
-    defaultAllow?: boolean;
-}): boolean;
 export declare function createRscNavigationStreamResponse(result: Extract<RscRenderResult, {
     type: "stream";
 }>): Promise<Response>;
@@ -45,11 +38,6 @@ export declare function normalizeRscTargetUrlForHostBasePath(targetUrl: URL, opt
     url: URL;
     basePath: string | null;
 };
-export interface SsrRoutesResult {
-    renderEnvRoutes: HttpRoutes;
-    hmrHub: HmrWsHub | null;
-    builderRpc: BuilderRpc | null;
-}
 export interface SsrRoutesInputs {
     web: AkanWebConfig;
     upgradeHmrWs: (req: Request, data: HmrWsData) => boolean;
@@ -75,16 +63,11 @@ export declare class WebRouter {
     }>;
     dispose(): void;
     setLogLevel(minSev: number | null): void;
-    /** Page prompts live with the pages, in the RSC worker; the MCP router reaches them through this. */
     pagePrompts(): PagePromptSource;
     onLogRecords(listener: (records: LogRecord[], dropped: number) => void): void;
     getMetrics(): AkanMetricsReport;
-    /** @internal Clears or scopes invalidation for local route result caches owned by the host and RSC worker. */
     invalidateRouteCaches(invalidation?: string | RouteCacheInvalidation): void;
-    /**
-     * `null` when the build produced no web artifact — an api-only build, or a workspace with no `page/` at all.
-     * The caller boots without a web surface instead of failing on the missing file.
-     */
+    /** `null` when the build has no web artifact (an api-only build, or no `page/`): boot without a web surface. */
     static create({ web, upgradeHmrWs }: SsrRoutesInputs): Promise<WebRouter | null>;
 }
 export {};

package/types/service/agent.service.d.ts

@@ -4,47 +4,34 @@ declare const AgentService_base: import("./serve.d.ts").ServiceCls<"agent", {},
 }>;
 export declare class AgentService extends AgentService_base {
     runTurn(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<{
+        limits?: import("./predefinedAdaptor.d.ts").LlmLimits | undefined;
+        model?: string | undefined;
+        usage?: import("./predefinedAdaptor.d.ts").LlmUsage | undefined;
         text: string;
         toolCalls: import("./predefinedAdaptor.d.ts").AgentWireToolCall[];
         stop: "length" | "end" | "toolUse";
     }>;
     /**
-     * The framework's half of the system prompt, ahead of whatever the app said so the app's text stays the more
-     * specific one. Composed here rather than in an adaptor for the reason `explained` is: every adaptor would
-     * otherwise have to remember it, and forgetting is silent.
-     *
-     * The last two sentences are the load-bearing ones, and both were measured against the provider rather than
-     * guessed at (8 runs a cell, one screen, tools stubbed):
-     *
-     * - Batching. One call per turn costs a full model round trip and a resend of the whole transcript per call, and
-     *   the turn cap then parks the run on a question halfway through. Asking for it took "approve these eight" from
-     *   1.5 turns with three runs in eight that did nothing at all, to one turn in eight runs out of eight.
-     * - Not re-reading. A model that has just written something goes back to look at what it did, one read per turn,
-     *   which is where a chain of ten calls actually comes from — the change report it was already handed says the
-     *   same thing. Saying so took "read the screen, then approve what is pending" from 3.0 turns to 2.0, its floor,
-     *   in every run. It is scoped to confirmation on purpose: the read a fresh route needs after `navigate` is
-     *   acquisition, and it survived the sentence in every run of that scenario.
+     * Prepended to the app's instructions here, not per adaptor, where forgetting it would be silent. The batching and
+     * no-re-read sentences were measured to cut turns against a provider; do not shorten them.
      */
     static readonly preamble: string;
     static instructed(request: LlmTurnRequest): LlmTurnRequest;
-    /**
-     * Folds a failed turn into the message text. `error` is a field only this wire has, so a provider mapping reads
-     * `text` and drops it — leaving the model an assistant turn that says nothing, with no hint that the attempt
-     * failed, and every reason to make the same one again. Done here rather than per adaptor because every adaptor
-     * would otherwise have to remember, and forgetting is silent.
-     */
+    /** Provider mappings read `text` and drop `error`, so a failed turn is folded into its text or retried blind. */
     static explained(request: LlmTurnRequest): LlmTurnRequest;
     private static explainedMessage;
-    /**
-     * Replaces every attachment the provider cannot read with a note naming it, so no adaptor has to think about
-     * attachments it does not support and none can lose one quietly. The model has to be *told*, not merely spared:
-     * a file that vanishes on the way in is one it answers about from the filename, confidently and wrongly.
-     *
-     * The note rides in the message text because that is the one field every provider mapping already reads.
-     */
+    /** Mirrors the client's clip where nothing routes around it: a hand-built wire or an older client passes here too. */
+    static readonly referenceLimit = 20000;
+    /** As text, the one field every provider mapping reads; the heading stays out of `preamble`: most turns lack one. */
+    static referenced(request: LlmTurnRequest): LlmTurnRequest;
+    private static referencedMessage;
+    /** Not free to shorten: both halves were observed working — a re-read with a tool, else a caveat. */
+    static readonly referenceHeading: string;
+    private static referenceLine;
+    private static fenced;
+    /** Swaps an attachment the provider cannot read for a note; dropped silently, it is guessed at from its name. */
     static readable(request: LlmTurnRequest, accepts: LlmAccepts | undefined): LlmTurnRequest;
     private static readableMessage;
-    /** Extracted text is readable by every model there is; bytes and links need the provider to say so. */
     private static isReadable;
     private static note;
 }

package/types/service/injectInfo.d.ts

@@ -15,7 +15,7 @@ interface InjectBuilderOptions<ReturnType> {
     local?: boolean;
     default?: unknown;
     isMap?: boolean;
-    cacheOption?: CacheSetOptions;
+    ttl?: number;
     parentRefName: string;
 }
 export interface InjectRegistry {
@@ -43,7 +43,6 @@ export interface LiveRegistry {
     internal: Map<string, Internal>;
     sliceCls: Map<string, SliceCls>;
     endpointCls: Map<string, EndpointCls>;
-    /** The process's one live-sync router. Rooms are registered on it at subscribe and read from it on every write. */
     syncHub: LiveSyncHub;
 }
 export declare const getDefaultLiveRegistry: () => LiveRegistry;
@@ -60,7 +59,8 @@ export declare class InjectInfo<Type extends InjectType = any, ReturnType = any,
     readonly adaptor?: AdaptorCls;
     readonly default?: unknown;
     readonly isMap?: boolean;
-    readonly cacheOption?: CacheSetOptions;
+    /** How long a `memory` value lives by default, in milliseconds — a `set` that names its own `expireAt` wins. */
+    readonly ttl?: number;
     readonly parentRefName: string;
     constructor(type: Type, options: InjectBuilderOptions<ReturnType>);
     static resolveInjection(instance: Adaptor | Service, applyCls: AdaptorCls | ServiceCls, registry: InjectRegistry, env: BackendEnv): Promise<void>;
@@ -75,27 +75,38 @@ export declare const injectionBuilder: (parentRefName: string) => {
     env: <GenFactory extends (arg: never) => unknown>(generateFactory: GenFactory) => InjectInfo<"env", Awaited<ReturnType<GenFactory>>, GenFactory extends (arg: infer Env extends {
         [key: string]: any;
     }) => unknown ? Env : never, never>;
-    memory: <ExplicitType = unknown, ValueRef extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = never, DefaultValue extends GetFieldValue<ValueRef, ExplicitType> = never, GetFn extends (value: GetFieldValue<ValueRef, ExplicitType>) => unknown = never, Local extends boolean = false>(modelRef: ValueRef, opts?: {
+    memory: <ExplicitType = unknown, ValueRef extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, MapValue = never, DefaultValue extends GetFieldValue<ValueRef, ExplicitType> = never, GetFn extends (value: MapConstructor extends ValueRef ? FieldToValue<MapValue> : GetFieldValue<ValueRef, ExplicitType>) => unknown = never, Local extends boolean = false>(modelRef: ValueRef, opts?: {
         local?: Local;
         default?: DefaultValue;
         of?: MapValue;
-        expireAt?: CacheSetOptions["expireAt"];
+        /** Milliseconds each write lives unless the `set` call names its own `expireAt`. */
+        ttl?: number;
+        /** Turns the stored value — a Map's entry value — into what the code reads; `set` is its inverse. */
         get?: GetFn;
-        set?: (value: ReturnType<GetFn>) => GetFieldValue<ValueRef, ExplicitType>;
-    }) => InjectInfo<"memory", Local extends true ? MapConstructor extends ValueRef ? Map<string, FieldToValue<MapValue>> : (DefaultValue extends never ? true : false) extends true ? (never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn> : MapConstructor extends ValueRef ? {
-        get: (key: string) => Promise<(never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>) | undefined>;
-        set: (key: string, value: never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<void>;
+        set?: (value: ReturnType<GetFn>) => MapConstructor extends ValueRef ? FieldToValue<MapValue> : GetFieldValue<ValueRef, ExplicitType>;
+    }) => InjectInfo<"memory", Local extends true ? MapConstructor extends ValueRef ? Map<string, FieldToValue<MapValue>> : (DefaultValue extends never ? true : false) extends true ? ([GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : [GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn> : MapConstructor extends ValueRef ? {
+        get: (key: string) => Promise<([GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>) | undefined>;
+        set: (key: string, value: [GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<void>;
         delete: (key: string) => Promise<void>;
-        getOrInsert: (key: string, value: never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>>;
-        getOrInsertComputed: (key: string, compute: (key: string) => (never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>) | Promise<never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>>, option?: CacheSetOptions) => Promise<never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>>;
+        /** Reads and removes the entry in one step: of two callers racing for it, one gets it. */
+        getDel: (key: string) => Promise<([GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>) | undefined>;
+        /** Writes only where no live entry is stored, and answers whether this call wrote. */
+        setIfAbsent: (key: string, value: [GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<boolean>;
+        /** Adds to a numeric entry and answers the sum; an entry this call creates takes the expiry. */
+        incr: (key: string, by?: number, option?: CacheSetOptions) => Promise<number>;
+        getOrInsert: (key: string, value: [GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<[GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>>;
+        getOrInsertComputed: (key: string, compute: (key: string) => ([GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>) | Promise<[GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>>, option?: CacheSetOptions) => Promise<[GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>>;
         keys: () => Promise<string[]>;
-        entries: () => Promise<[string, never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>][]>;
-        forEach: (callback: (value: never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>, key: string) => void | Promise<void>) => Promise<void>;
+        entries: () => Promise<[string, [GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>][]>;
+        forEach: (callback: (value: [GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>, key: string) => void | Promise<void>) => Promise<void>;
         clear: () => Promise<void>;
     } : {
-        get: () => Promise<(DefaultValue extends never ? true : false) extends true ? (never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>>;
-        set: (value: (DefaultValue extends never ? true : false) extends true ? (never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<void>;
+        get: () => Promise<(DefaultValue extends never ? true : false) extends true ? ([GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : [GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>>;
+        set: (value: (DefaultValue extends never ? true : false) extends true ? ([GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : [GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<void>;
         delete: () => Promise<void>;
+        getDel: () => Promise<(DefaultValue extends never ? true : false) extends true ? ([GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : [GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>>;
+        setIfAbsent: (value: (DefaultValue extends never ? true : false) extends true ? ([GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>) | null : [GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>, option?: CacheSetOptions) => Promise<boolean>;
+        incr: (by?: number, option?: CacheSetOptions) => Promise<number>;
     }, never, ValueRef>;
 };
 export type InjectBuilder<BuildType extends InjectType = InjectType> = (builder: Pick<ReturnType<typeof injectionBuilder>, BuildType>) => {

package/types/service/ipcTypes.d.ts

@@ -1,4 +1,5 @@
 import type { LogRecord } from "akanjs/common";
+import type { LiveChange } from "./predefinedAdaptor/websocket.adaptor";
 export type AkanChildRole = "all" | "federation" | "batch";
 export type AkanChildStatus = "starting" | "ready" | "healthy" | "draining" | "unhealthy" | "exited" | "crashed";
 export type AkanUpstream = {
@@ -12,6 +13,7 @@ export type AkanUpstream = {
 export interface AkanJobOptions {
     delay?: number;
     attempts?: number;
+    /** Smaller runs sooner, and a job with none runs before every prioritized one — bullmq's reading. */
     priority?: number;
     backoff?: number | {
         type?: string;
@@ -182,6 +184,10 @@ export type AkanIpcMessage = {
     type: "pubsub.snapshot";
     rooms: string[];
     pid?: number;
+} | {
+    type: "live.change";
+    change: LiveChange;
+    origin?: string;
 } | {
     type: "queue.enqueued";
     queue: string;

package/types/service/liveSyncHub.d.ts

@@ -28,25 +28,12 @@ interface LiveRoom {
     evaluator: DocumentQueryEvaluator;
     payload: "light" | "id";
     subscribers: number;
-    /**
-     * Top-level `<path> eq <value>` conditions this room's query requires, when it is a plain conjunction of them.
-     * A change whose document disagrees with one of these cannot belong to this room, and cannot have belonged to it
-     * before either, so the room is skipped without walking its tree at all.
-     */
+    /** The query's top-level `eq` conditions when it is a plain conjunction; a document disagreeing skips the room. */
     index: Map<string, unknown> | null;
 }
 /**
- * Routes a document change to the rooms it belongs to.
- *
- * A room is one live subscription's resolved query, kept from the moment the socket subscribed. When a document
- * changes, the same query is evaluated against the version before the write and the version after it, and the pair
- * of answers is the event: appearing is `enter`, disappearing is `leave`, and staying is `update`. That is why the
- * CRUD verb never reaches a subscriber — an edit that moves a row out of a filter has to arrive as a removal from
- * that list, and a create that lands in one has to arrive as an insertion, which the verb alone cannot say.
- *
- * Every read wraps the caller's query in `removedAt` being empty (`SqlDocumentStore.findForRead`), and that wrapper
- * is added by the store rather than carried in the descriptor a slice returns. It is applied here for the same
- * reason: without it a soft delete still satisfies the query and would be routed as an ordinary update.
+ * Evaluates each room's query before and after a write: appearing is `enter`, disappearing `leave`, staying `update`.
+ * `removedAt` is wrapped in here as the store does on every read, or a soft delete would route as an update.
  */
 export declare class LiveSyncHub {
     #private;
@@ -54,14 +41,9 @@ export declare class LiveSyncHub {
     roomCountOf(refName: string): number;
     /** Idempotent: a second socket subscribing to the same room shares the one evaluation. */
     join({ refName, roomId, query, fallback, payload, fields }: LiveRoomRegistration): LiveRoom;
-    /** Every room this process currently holds, for a recovery that has to tell all of them to resynchronize. */
     roomIds(): string[];
     leave(roomId: string): void;
-    /**
-     * Which rooms this change belongs to and how it reads in each.
-     *
-     * `previous` is absent on a create, which is the same thing as having belonged to no room before.
-     */
+    /** `previous` is absent on a create — no room held the document before. */
     route(refName: string, next: Record<string, unknown>, previous?: Record<string, unknown>): LiveRoomTarget[];
 }
 export {};

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

@@ -1,4 +1,4 @@
-import type { AgentWireAttachment, AgentWireMessage, LlmAccepts, LlmAdaptor, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
+import type { AgentWireAttachment, AgentWireMessage, LlmAccepts, LlmAdaptor, LlmLimits, LlmOption, LlmTurnAnswer, LlmTurnRequest, LlmUsage } from "./llm.adaptor";
 type AnthropicSource = {
     type: "base64";
     media_type: string;
@@ -30,6 +30,12 @@ interface AnthropicMessage {
     role: "user" | "assistant";
     content: AnthropicBlock[];
 }
+interface AnthropicUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number | null;
+    cache_creation_input_tokens?: number | null;
+}
 interface AnthropicAnswer {
     content?: {
         type?: string;
@@ -39,35 +45,27 @@ interface AnthropicAnswer {
         input?: Record<string, unknown>;
     }[];
     stop_reason?: string;
+    usage?: AnthropicUsage;
 }
 declare const AnthropicLlm_base: import("..").AdaptorCls<{}, {
     llmOption: import("..").InjectInfo<"use", LlmOption, never, never>;
 }>;
-/**
- * Anthropic's Messages API — the one provider akanjs ships that reads a picture and a PDF.
- *
- * It is not the chat-completions dialect wearing a different host: the system prompt is a top-level field rather
- * than a message, tool calls and their results are content blocks rather than a parallel `tool_calls` array, the
- * results ride in a *user* turn, roles must alternate, and `max_tokens` is required. So it is its own file rather
- * than a branch in `OpenaiDialect`, and nothing is shared between them but the wire they both map from.
- *
- * `model` is required and has no default, for the reason `OpenaiLlm` gives.
- */
+/** Anthropic's Messages API, which reads images and PDFs. `model` is required and has no default. */
 export declare class AnthropicLlm extends AnthropicLlm_base implements LlmAdaptor {
     #private;
     /** Pinned rather than read from a header the API might move: a revision change is a mapping change, not config. */
     static readonly version = "2023-06-01";
+    /** The API refuses a request with no ceiling; a reasoning model may spend all of it thinking, hence `maxTokens`. */
+    static readonly defaultMaxTokens = 8192;
     /**
-     * The API refuses a request that names no ceiling, so one is always sent. An agent turn's answer is a sentence
-     * and a few tool calls, so this is slack rather than a budget — except on a model that reasons before it
-     * writes, which can spend the whole of it thinking and return nothing with a length stop. That reads as the
-     * model refusing, so it is `option.setLlm({ maxTokens })` and not a constant.
+     * Exact, not `image/*`: a phone's `image/heic` would become a block the API refuses, taking the whole turn down on a
+     * 400, and no `AttachReader` can refuse an image before it gets here.
      */
-    static readonly defaultMaxTokens = 8192;
-    /** What the API's blocks carry. A model of the family that reads neither takes the `accepts` override. */
+    static readonly imageTypes: Set<string>;
+    get limits(): LlmLimits;
     get accepts(): LlmAccepts;
     chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
-    static refusal(response: Response): Promise<Error>;
+    static refusal(host: string, response: Response): Promise<Error>;
     /** The API answers a refusal as `{ error: { type, message } }`, and the sentence is the half worth printing. */
     static reasonOf(response: Response): Promise<string>;
     static requestBody(model: string, request: LlmTurnRequest, { accepts, stream, maxTokens }?: {
@@ -88,23 +86,16 @@ export declare class AnthropicLlm extends AnthropicLlm_base implements LlmAdapto
     };
     /** Context rides below the instructions framed as data — screen state must never read as directives. */
     static systemPrompt({ instructions, context }: LlmTurnRequest): string;
-    /**
-     * The API takes strictly alternating turns, so two wire messages that map to one role are merged rather than
-     * sent as two — which is not an edge case here: a turn's tool results and the next thing the user says are both
-     * user turns, and so is the tool-result turn that follows a batch of calls.
-     */
+    /** The API takes strictly alternating roles, so tool results and the user's next ask merge into one user turn. */
     static providerMessages(messages: AgentWireMessage[], accepts?: LlmAccepts): AnthropicMessage[];
     static providerMessage(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicMessage;
     static userContent(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicBlock[];
+    static typed(source: AnthropicSource, mimeType: string): AnthropicSource;
+    /** Bytes beat a URL: the default storage serves a path only the app can resolve, so the provider cannot fetch it. */
     static sourceOf(attachment: AgentWireAttachment): AnthropicSource | null;
     static turnAnswer(answer: AnthropicAnswer): LlmTurnAnswer;
-    /** The ceiling wins over the calls that did arrive — see `OpenaiDialect.stopOf` for why. */
+    static usageOf(usage: AnthropicUsage): LlmUsage;
     static stopOf(reason: string | null | undefined, calls: number): LlmTurnAnswer["stop"];
-    /**
-     * The API streams named SSE events rather than one chunk shape. A tool call opens as `content_block_start`
-     * carrying its id and name and then arrives as `input_json_delta` fragments of a JSON string, so it is assembled
-     * by block 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>;
     /** A tool called with no arguments streams no fragment at all, so an empty string is an empty object. */
     static parsedArgs(raw: string): Record<string, unknown>;

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

@@ -1,40 +1,70 @@
-import type { BaseEnv, Dayjs, SshOptions } from "akanjs/base";
+import { type BaseEnv, type Dayjs } from "akanjs/base";
 import type { Redis } from "ioredis";
 export interface CacheSetOptions {
     expireAt?: Dayjs;
 }
+/** An object, an array or a boolean is stored as JSON and read back parsed, so a class instance returns as its JSON. */
+export type CacheValue = string | number | boolean | Uint8Array | object;
 export interface CacheAdaptor {
-    set(topic: string, key: string, value: string | number | Buffer, option?: CacheSetOptions): Promise<void>;
-    get<T extends string | number | Buffer>(topic: string, key: string): Promise<T | undefined>;
+    set(topic: string, key: string, value: CacheValue, option?: CacheSetOptions): Promise<void>;
+    get<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<T | undefined>;
     delete(topic: string, key: string): Promise<void>;
+    /** Reads and removes in one step: of two callers racing for a one-time value, one gets it and the other nothing. */
+    getDel<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<T | undefined>;
+    /** Writes only where nothing live is stored, and answers whether this call wrote. */
+    setIfAbsent(topic: string, key: string, value: CacheValue, option?: CacheSetOptions): Promise<boolean>;
+    /** Adds `by` and answers the sum. A counter this call creates takes `expireAt`; a live one keeps its own. */
+    incr(topic: string, key: string, by?: number, option?: CacheSetOptions): Promise<number>;
+    /** Takes the lease for `owner` when nobody else holds a live one; the holder calling again renews it. */
+    acquireLease(topic: string, key: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Extends a lease `owner` still holds, and answers false once it lapsed or passed to someone else. */
+    renewLease(topic: string, key: string, owner: string, ttlMs: number): Promise<boolean>;
+    releaseLease(topic: string, key: string, owner: string): Promise<void>;
     getClient?(): Redis;
-    hset(topic: string, key: string, subKey: string, value: string | number | Buffer, option?: CacheSetOptions): Promise<void>;
-    hget<T extends string | number | Buffer>(topic: string, key: string, subKey: string): Promise<T | undefined>;
+    hset(topic: string, key: string, subKey: string, value: CacheValue, option?: CacheSetOptions): Promise<void>;
+    hget<T extends CacheValue = CacheValue>(topic: string, key: string, subKey: string): Promise<T | undefined>;
     hdelete(topic: string, key: string, subKey: string): Promise<void>;
     hkeys(topic: string, key: string): Promise<string[]>;
-    hentries<T extends string | number | Buffer>(topic: string, key: string): Promise<[string, T][]>;
+    hentries<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<[string, T][]>;
     hclear(topic: string, key: string): Promise<void>;
+    hgetDel<T extends CacheValue = CacheValue>(topic: string, key: string, subKey: string): Promise<T | undefined>;
+    hsetIfAbsent(topic: string, key: string, subKey: string, value: CacheValue, option?: CacheSetOptions): Promise<boolean>;
+    hincr(topic: string, key: string, subKey: string, by?: number, option?: CacheSetOptions): Promise<number>;
 }
 interface RedisEnv extends BaseEnv {
     redis?: {
         username?: string;
         password?: string;
-        sshOptions?: SshOptions;
     };
 }
 declare const RedisCache_base: import("..").AdaptorCls<{}, {
     redis: import("..").InjectInfo<"env", Redis, RedisEnv, never>;
+    keyPrefix: import("..").InjectInfo<"env", string, {
+        [key: string]: any;
+    }, never>;
 }>;
 export declare class RedisCache extends RedisCache_base implements CacheAdaptor {
-    set(topic: string, key: string, value: string | number | Buffer, option?: CacheSetOptions): Promise<void>;
-    get<T extends string | number | Buffer>(topic: string, key: string): Promise<T | undefined>;
+    #private;
+    /** `REDIS_URI` (`rediss://` for TLS) is required outside local: a guessed host is a split brain that boots. */
+    static resolveUrl(): string;
+    set(topic: string, key: string, value: CacheValue, option?: CacheSetOptions): Promise<void>;
+    get<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<T | undefined>;
     delete(topic: string, key: string): Promise<void>;
-    hset(topic: string, key: string, subKey: string, value: string | number | Buffer, option?: CacheSetOptions): Promise<void>;
-    hget<T extends string | number | Buffer>(topic: string, key: string, subKey: string): Promise<T | undefined>;
+    getDel<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<T | undefined>;
+    setIfAbsent(topic: string, key: string, value: CacheValue, option?: CacheSetOptions): Promise<boolean>;
+    incr(topic: string, key: string, by?: number, option?: CacheSetOptions): Promise<number>;
+    acquireLease(topic: string, key: string, owner: string, ttlMs: number): Promise<boolean>;
+    renewLease(topic: string, key: string, owner: string, ttlMs: number): Promise<boolean>;
+    releaseLease(topic: string, key: string, owner: string): Promise<void>;
+    hset(topic: string, key: string, subKey: string, value: CacheValue, option?: CacheSetOptions): Promise<void>;
+    hget<T extends CacheValue = CacheValue>(topic: string, key: string, subKey: string): Promise<T | undefined>;
     hdelete(topic: string, key: string, subKey: string): Promise<void>;
     hkeys(topic: string, key: string): Promise<string[]>;
-    hentries<T extends string | number | Buffer>(topic: string, key: string): Promise<[string, T][]>;
+    hentries<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<[string, T][]>;
     hclear(topic: string, key: string): Promise<void>;
+    hgetDel<T extends CacheValue = CacheValue>(topic: string, key: string, subKey: string): Promise<T | undefined>;
+    hsetIfAbsent(topic: string, key: string, subKey: string, value: CacheValue, option?: CacheSetOptions): Promise<boolean>;
+    hincr(topic: string, key: string, subKey: string, by?: number, option?: CacheSetOptions): Promise<number>;
     getClient(): Redis;
     onDestroy(): Promise<void>;
 }

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

@@ -1,4 +1,4 @@
-import { type PromiseOrObject } from "akanjs/base";
+import type { PromiseOrObject } from "akanjs/base";
 import type { ConstantModel } from "akanjs/constant";
 import type { DatabaseModel, SchemaOf } from "akanjs/document";
 import { SearchIndex } from "./searchIndex.d.ts";
@@ -6,23 +6,16 @@ import { BunSqliteClient } from "./sql/driver/bunSqlite.d.ts";
 import { LibsqlAkanClient } from "./sql/driver/libsql.d.ts";
 import { PostgresAkanClient } from "./sql/driver/postgres.d.ts";
 import { SqlDocumentStore } from "./sql/SqlDocumentStore.d.ts";
-import type { DatabaseAdaptor, SqliteEnv } from "./sql/types.d.ts";
+import { type ConcurrentIndexBuild, type DatabaseAdaptor, type InsightSession, type SearchConfig, type SqliteEnv } from "./sql/types.d.ts";
 export { PostgresDialect } from "./sql/dialect/postgres.d.ts";
 export { SqliteDialect } from "./sql/dialect/sqlite.d.ts";
 export { SqlDocumentStore } from "./sql/SqlDocumentStore.d.ts";
-/**
- * The three SQL databases an app can mount, and nothing else. The layer underneath them — drivers, dialects,
- * the query and update compilers, and the document store they all share — lives in .
- */
-export type { AkanSqlClient, AkanSqlStatement, DatabaseAdaptor, DatabaseConfig, DocumentDatabaseOwner, DocumentStore, LibsqlDatabaseConfig, PostgresDatabaseConfig, SearchConfig, SqliteDatabaseConfig, SqlResultRows, } from "./sql/types.d.ts";
+export type { AkanSqlClient, AkanSqlStatement, DatabaseAdaptor, DatabaseConfig, DocumentDatabaseOwner, DocumentStore, InsightSession, LibsqlDatabaseConfig, PostgresDatabaseConfig, SearchConfig, SqlDialect, SqliteDatabaseConfig, SqlResultRows, } from "./sql/types.d.ts";
 declare const SqliteDatabase_base: import("..").AdaptorCls<{}, {
     scheduler: import("..").InjectInfo<"plug", import("./schedule.adaptor").ScheduleAdaptor, never, never>;
     config: import("..").InjectInfo<"env", {
         filePath: string;
-        search: {
-            enabled: boolean;
-            tokenizer: string;
-        };
+        search: Required<SearchConfig>;
         journalMode: "WAL" | "DELETE" | "TRUNCATE" | "PERSIST" | "MEMORY" | "OFF";
         busyTimeoutMs: number;
         synchronous: "OFF" | "NORMAL" | "FULL" | "EXTRA";
@@ -37,6 +30,8 @@ export declare class SqliteDatabase extends SqliteDatabase_base implements Datab
     onDestroy(): Promise<void>;
     getConnection(): BunSqliteClient;
     getSearchIndex(): SearchIndex;
+    openInsight(): Promise<InsightSession>;
+    stores(): SqlDocumentStore[];
     getStore(constant: ConstantModel, database: DatabaseModel, schema: SchemaOf): SqlDocumentStore;
     getMeta(key: string): string | undefined;
     setMeta(key: string, value: string): Promise<void>;
@@ -50,10 +45,7 @@ declare const LibsqlDatabase_base: import("..").AdaptorCls<{}, {
     config: import("..").InjectInfo<"env", {
         url: string;
         authToken: string | undefined;
-        search: {
-            enabled: boolean;
-            tokenizer: string;
-        };
+        search: Required<SearchConfig>;
     }, SqliteEnv, never>;
 }>;
 export declare class LibsqlDatabase extends LibsqlDatabase_base implements DatabaseAdaptor {
@@ -62,6 +54,8 @@ export declare class LibsqlDatabase extends LibsqlDatabase_base implements Datab
     onDestroy(): Promise<void>;
     getConnection(): LibsqlAkanClient;
     getSearchIndex(): SearchIndex;
+    openInsight(): Promise<InsightSession>;
+    stores(): SqlDocumentStore[];
     getStore(constant: ConstantModel, database: DatabaseModel, schema: SchemaOf): SqlDocumentStore;
     getMeta(key: string): Promise<string | undefined>;
     setMeta(key: string, value: string): Promise<void>;
@@ -69,6 +63,7 @@ export declare class LibsqlDatabase extends LibsqlDatabase_base implements Datab
     afterCommit(fn: () => PromiseOrObject<void>): Promise<void>;
 }
 declare const PostgresDatabase_base: import("..").AdaptorCls<{}, {
+    scheduler: import("..").InjectInfo<"plug", import("./schedule.adaptor").ScheduleAdaptor, never, never>;
     config: import("..").InjectInfo<"env", {
         url: string | undefined;
         host: string;
@@ -76,17 +71,26 @@ declare const PostgresDatabase_base: import("..").AdaptorCls<{}, {
         database: string;
         user: string;
         password: string;
+        insightUrl: string | undefined;
+        search: Required<SearchConfig>;
     }, SqliteEnv, never>;
 }>;
 export declare class PostgresDatabase extends PostgresDatabase_base implements DatabaseAdaptor {
     #private;
     onInit(): Promise<void>;
+    grantInsight(table: string): Promise<void>;
+    openInsight(): Promise<InsightSession>;
     onDestroy(): Promise<void>;
     getConnection(): PostgresAkanClient;
-    getSearchIndex(): null;
+    getSearchIndex(): SearchIndex;
+    stores(): SqlDocumentStore[];
     getStore(constant: ConstantModel, database: DatabaseModel, schema: SchemaOf): SqlDocumentStore;
     getMeta(key: string): Promise<string | undefined>;
     setMeta(key: string, value: string): Promise<void>;
     transaction<T>(fn: () => PromiseOrObject<T>): Promise<T>;
     afterCommit(fn: () => PromiseOrObject<void>): Promise<void>;
+    lockSchema<T>(fn: () => Promise<T>): Promise<T>;
+    hasTable(table: string): Promise<boolean>;
+    hasValidIndex(name: string): Promise<boolean>;
+    buildIndexConcurrently({ name, next, create, replace }: ConcurrentIndexBuild): Promise<void>;
 }