ankka 0.10.0 → 0.11.0

package/dist/agent.js

@@ -5,7 +5,9 @@
 //   static readonly tools = { lookup: tool("lookup", "Looks up a cart by id.", CartLookup, (a: Assistant, input) => a.lookup(input.cartId)) }
 //   static readonly guardrails = { noSecrets: guardrail("no-secrets", (stage, text) => text.includes("sk-") ? "a key leaked" : null) }
 //   static readonly handlers = { ask: command("ask", s.string, s.string, (a: Assistant, q) => a.ask(q)), chat: stream("chat", s.string, (a: Assistant, q) => a.ask(q)) }
+import { secretsFor } from "./client.js";
 import { AgentEffects } from "./effects/agent.js";
+import { servicesFor } from "./services.js";
 export class Agent {
     effects = new AgentEffects();
     #sessionId = "";
@@ -23,6 +25,24 @@ export class Agent {
             throw new Error("client is only available inside a handler, a tool or a guardrail");
         return this.#client;
     }
+    #secrets;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets() {
+        return this.#secrets ?? secretsFor(this.client);
+    }
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store) {
+        this.#secrets = store;
+    }
+    #services;
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services() {
+        return this.#services ?? servicesFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services) {
+        this.#services = services;
+    }
     /** @internal */
     get _kind() {
         return "agent";

package/dist/approvals.d.ts

@@ -0,0 +1,47 @@
+import type { ApprovalAwaited as ApprovalAwaitedProto, ApprovalRequest as ApprovalRequestProto } from "./_proto/ankka/protocol/v1/client_pb.ts";
+/** The protocol version that carries approvals: a runtime before it cannot record a decision. */
+export declare const APPROVALS_SINCE = "1.11";
+/** That a tool, or every tool of an MCP server, waits for a person; with `withinMs`, the platform refuses it when that much time passes undecided. */
+export type Approval = true | {
+    readonly withinMs: number;
+};
+/** A problem with an approval as declared, or undefined. */
+export declare function approvalProblem(approval: Approval | undefined): string | undefined;
+/** The discovery form: absent for none, empty for no time limit. */
+export declare function approvalToProto(approval: Approval | undefined): {
+    withinMillis?: bigint;
+} | undefined;
+/** What an agent records when the model calls a tool that requires approval: the id a decision names, the tool and the model's arguments. */
+export interface ApprovalRequest {
+    readonly id: string;
+    readonly tool: string;
+    readonly arguments: unknown;
+    readonly requestedAt: number;
+    readonly expiresAt?: number;
+}
+export declare function requestFromProto(pb: ApprovalRequestProto): ApprovalRequest;
+/** A request as an autonomous agent's record holds it. */
+export declare function requestFromJson(body: Record<string, any>): ApprovalRequest;
+/** What a turn that may wait came to: the model's answer, or the requests it waits on. */
+export type AgentOutcome<R> = {
+    readonly kind: "answered";
+    readonly value: R;
+} | {
+    readonly kind: "awaiting-approval";
+    readonly requests: readonly ApprovalRequest[];
+};
+export declare function awaitingOf(pb: ApprovalAwaitedProto): AgentOutcome<never>;
+/**
+ * Thrown by the calls that answer only with a value — `invoke` and `stream` — when the turn waits. Use
+ * `ask`, `streamParts` or `decide` to be answered with the requests instead.
+ */
+export declare class ApprovalAwaited extends Error {
+    readonly requests: readonly ApprovalRequest[];
+    constructor(requests: readonly ApprovalRequest[]);
+}
+/** A person's decision: `by` names who decided and is required; a refusal may carry a note the model is told. */
+export interface DecisionInput {
+    readonly approved: boolean;
+    readonly by: string;
+    readonly note?: string;
+}

package/dist/approvals.js

@@ -0,0 +1,57 @@
+// Approvals: a tool that waits for a person's decision before it runs.
+//
+// A tool declared with `approval` is never run when the model calls it. The sidecar records an approval
+// request and answers the caller with it instead of an answer; the turn goes on when a person decides,
+// through `decide`. Approved, the tool runs once and the model is told its result; refused, the model is
+// told who refused it and why, and the tool never runs. Who decided is required and recorded; who *may*
+// decide is the ACL of whatever route sends the decision.
+/** The protocol version that carries approvals: a runtime before it cannot record a decision. */
+export const APPROVALS_SINCE = "1.11";
+/** A problem with an approval as declared, or undefined. */
+export function approvalProblem(approval) {
+    if (approval === undefined || approval === true)
+        return undefined;
+    if (!Number.isFinite(approval.withinMs) || approval.withinMs <= 0)
+        return `a time limit for approval must be positive, not ${approval.withinMs}ms`;
+    return undefined;
+}
+/** The discovery form: absent for none, empty for no time limit. */
+export function approvalToProto(approval) {
+    if (approval === undefined)
+        return undefined;
+    return approval === true ? {} : { withinMillis: BigInt(Math.trunc(approval.withinMs)) };
+}
+export function requestFromProto(pb) {
+    return Object.freeze({
+        id: pb.id,
+        tool: pb.tool,
+        arguments: pb.argumentsJson ? JSON.parse(pb.argumentsJson) : {},
+        requestedAt: Number(pb.requestedAtMillis),
+        ...(pb.expiresAtMillis !== undefined ? { expiresAt: Number(pb.expiresAtMillis) } : {}),
+    });
+}
+/** A request as an autonomous agent's record holds it. */
+export function requestFromJson(body) {
+    return Object.freeze({
+        id: String(body.id),
+        tool: String(body.tool),
+        arguments: body.arguments ?? {},
+        requestedAt: Number(body.requestedAt ?? 0),
+        ...(body.expiresAt !== undefined ? { expiresAt: Number(body.expiresAt) } : {}),
+    });
+}
+export function awaitingOf(pb) {
+    return Object.freeze({ kind: "awaiting-approval", requests: pb.requests.map(requestFromProto) });
+}
+/**
+ * Thrown by the calls that answer only with a value — `invoke` and `stream` — when the turn waits. Use
+ * `ask`, `streamParts` or `decide` to be answered with the requests instead.
+ */
+export class ApprovalAwaited extends Error {
+    requests;
+    constructor(requests) {
+        super(`approval awaited for ${requests.map((r) => `'${r.tool}' (${r.id})`).join(", ")}`);
+        this.name = "ApprovalAwaited";
+        this.requests = requests;
+    }
+}

package/dist/autonomous.d.ts

@@ -1,6 +1,9 @@
-import type { ComponentClient } from "./client.ts";
+import { type ApprovalRequest, type DecisionInput } from "./approvals.ts";
+import type { McpServerRef, ResultGuardrailRef } from "./mcp.ts";
+import { type ComponentClient, type Secrets } from "./client.ts";
 import type { GuardrailRef, ToolRef } from "./handlers.ts";
 import type { Schema } from "./schema.ts";
+import { type Services } from "./services.ts";
 type MaybePromise<T> = T | Promise<T>;
 export declare const COMPLETE_TASK = "complete_task";
 export declare const FAIL_TASK = "fail_task";
@@ -51,6 +54,14 @@ export declare abstract class AutonomousAgent {
     /** The task a tool, a guardrail or a rule is running for. */
     get taskId(): string;
     get client(): ComponentClient;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets(): Secrets;
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store: Secrets);
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services(): Services;
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services: Services);
     /** @internal */
     get _kind(): "autonomous-agent";
     /** @internal */
@@ -67,6 +78,10 @@ export interface AutonomousAgentClass<C extends AutonomousAgent = AutonomousAgen
     readonly guardrails?: Readonly<Record<string, GuardrailRef>>;
     readonly accepts: readonly TaskAcceptance[];
     readonly settings?: AutonomousSettings;
+    /** MCP servers whose tools are offered beside the agent's own, as `mcp__<server>__<tool>`. */
+    readonly mcpServers?: Readonly<Record<string, McpServerRef>>;
+    /** Checks on what an MCP server's tool answered, before the model is told it. */
+    readonly resultGuardrails?: Readonly<Record<string, ResultGuardrailRef>>;
 }
 /** The discovery form of a result schema. */
 export declare function resultSchemaJson(type: TaskType<any>): string | undefined;
@@ -94,6 +109,8 @@ export interface AgentState {
     readonly currentTask: string | undefined;
     readonly iteration: number;
     readonly queued: readonly string[];
+    /** The approval requests the current task's tool calls await; while any does, the instance calls no model. */
+    readonly awaiting: readonly ApprovalRequest[];
 }
 /** One thing an instance did: `type` names it, and the rest of its fields are as sent. */
 export interface Notification {
@@ -148,6 +165,11 @@ export declare class AutonomousAgentCalls {
     /** Stops the instance for good; its tasks go back to pending for another to take. */
     terminate(): Promise<void>;
     state(): Promise<AgentState>;
+    /**
+     * Decides one of the instance's approval requests. `by` names who decided and is required. Approved, the
+     * tool runs and the task goes on; refused, the model is told so. A request already decided is a conflict.
+     */
+    decide(approvalId: string, decision: DecisionInput): Promise<void>;
     /** What the instance does from now on, as it happens. Nothing is replayed. */
     notifications(): AsyncIterable<Notification>;
 }

package/dist/autonomous.js

@@ -14,8 +14,11 @@
 //
 // A tool may run more than once for one request of the model — after a crash, the last recorded
 // request's tools run again — so a tool with a side effect should tolerate a repeat.
+import { requestFromJson } from "./approvals.js";
+import { secretsFor } from "./client.js";
 import { decodeJsonValue, reviver } from "./json.js";
 import { toJsonSchema } from "./schema.js";
+import { servicesFor } from "./services.js";
 export const COMPLETE_TASK = "complete_task";
 export const FAIL_TASK = "fail_task";
 export const accepted = () => Object.freeze({ verdict: "accepted" });
@@ -56,6 +59,24 @@ export class AutonomousAgent {
             throw new Error("client is only available inside a tool, a guardrail or a rule");
         return this.#client;
     }
+    #secrets;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets() {
+        return this.#secrets ?? secretsFor(this.client);
+    }
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store) {
+        this.#secrets = store;
+    }
+    #services;
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services() {
+        return this.#services ?? servicesFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services) {
+        this.#services = services;
+    }
     /** @internal */
     get _kind() {
         return "autonomous-agent";
@@ -188,7 +209,15 @@ export class AutonomousAgentCalls {
         const r = (await this.#client._raw("event-sourced", INSTANCE, `${this.componentId}/${this.#instance()}`, "get"));
         const current = r.current;
         const phase = r.terminated ? "terminated" : r.suspended ? "suspended" : current ? "working" : (r.queue ?? []).length > 0 ? "waiting" : "idle";
-        return Object.freeze({ phase, currentTask: current?.taskId, iteration: current?.iteration ?? 0, queued: [...(r.queue ?? [])] });
+        const awaiting = (current?.approvals ?? []).filter((a) => a.decision === undefined || a.decision === null).map(requestFromJson);
+        return Object.freeze({ phase, currentTask: current?.taskId, iteration: current?.iteration ?? 0, queued: [...(r.queue ?? [])], awaiting });
+    }
+    /**
+     * Decides one of the instance's approval requests. `by` names who decided and is required. Approved, the
+     * tool runs and the task goes on; refused, the model is told so. A request already decided is a conflict.
+     */
+    async decide(approvalId, decision) {
+        await this.#client._decide("autonomous-agent", this.componentId, this.#instance(), "", approvalId, decision);
     }
     /** What the instance does from now on, as it happens. Nothing is replayed. */
     async *notifications() {

package/dist/client.d.ts

@@ -4,8 +4,9 @@ import { jsonCodec, type Shape } from "./codec.ts";
 import { type Metadata } from "./effects/common.ts";
 import type { HandlerRef } from "./handlers.ts";
 import { type ComponentKind } from "./kinds.ts";
-import type { Duration } from "./time.ts";
+import { Duration } from "./time.ts";
 import { AutonomousAgentCalls, TaskCalls, Tasks } from "./autonomous.ts";
+import { type AgentOutcome, type DecisionInput } from "./approvals.ts";
 /** A component class as the typed client sees it: an id and, on its prototype, its kind. */
 export interface ComponentRef {
     readonly componentId: string;
@@ -22,10 +23,25 @@ interface Connection {
 export declare class Invocation<I, R> {
     #private;
     constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string, name: string, input: Shape<I> | undefined, reply: Shape<R> | undefined);
-    /** Invokes and decodes the reply; a refusal rejects with `CommandError`. */
+    /**
+     * Invokes and decodes the reply; a refusal rejects with `CommandError`. An agent's turn that waits for a
+     * person rejects with `ApprovalAwaited`; `ask` answers it instead.
+     */
     invoke(input?: I): Promise<R>;
-    /** Invokes a streaming handler; yields tokens in order; a failure rejects with `CommandError`. */
+    /** Calls an agent's handler for its outcome: the model's answer, or the approval requests the turn waits on. */
+    ask(input?: I): Promise<AgentOutcome<R>>;
+    /**
+     * Decides one of the session's approval requests; this invocation names the handler whose turn waits.
+     * `by` names who decided and is required. When it was the turn's last awaited decision the turn goes on,
+     * and this answers as `ask` would have. A request already decided is a conflict.
+     */
+    decide(approvalId: string, decision: DecisionInput): Promise<AgentOutcome<R>>;
+    /** Invokes a streaming handler; yields tokens in order; a failure rejects with `CommandError`, a turn that waits with `ApprovalAwaited`. */
     stream(input?: I): AsyncIterable<string>;
+    /** As `stream`, ending with one awaiting part when the turn waits for a person. */
+    streamParts(input?: I): AsyncIterable<string | Extract<AgentOutcome<never>, {
+        kind: "awaiting-approval";
+    }>>;
 }
 /** Calls on one component instance, by wire name. */
 export declare class Calls {
@@ -44,10 +60,15 @@ export declare class TypedCalls<C> {
 /** View queries: rows come back as a JSON array decoded with the row shape. */
 export declare class Views {
     #private;
-    constructor(connection: Connection);
+    constructor(connection: Connection, metadata?: Metadata);
     get<Row>(viewId: string, key: string, row: Shape<Row>): Promise<Row | null>;
     all<Row>(viewId: string, row: Shape<Row>): Promise<Row[]>;
     query<Row>(viewId: string, name: string, key: string | null, row: Shape<Row>): Promise<Row[]>;
+    /**
+     * The rows of one of a view's declared queries, asked by name with the values it takes. At most
+     * `limit` rows, 1000 when it is not given, in the statement's own order.
+     */
+    ask<Row>(viewId: string, name: string, values: Readonly<Record<string, string>>, row: Shape<Row>, limit?: number): Promise<Row[]>;
 }
 /** What a timer fires: a component class and one of its handlers, or the same by name. */
 export type TimerTarget = {
@@ -61,13 +82,78 @@ export type TimerTarget = {
     readonly input?: Shape<any>;
     readonly entityId?: string;
 };
+/** What a recurring timer fires: a timed action's class and one of its handlers, or the same by name. */
+export type TimedActionTarget = {
+    readonly component: ComponentRef;
+    readonly handler: HandlerRef<any, any, any, any>;
+} | {
+    readonly componentId: string;
+    readonly name: string;
+    readonly input?: Shape<any>;
+};
 export declare class Timers {
     #private;
     constructor(connection: Connection);
     /** Schedules `target` after `delay`. Scheduling twice under one id replaces the earlier schedule. */
     schedule(timerId: string, delay: Duration, target: TimerTarget, input?: unknown): Promise<void>;
+    /**
+     * Schedules `target`, a timed action's handler, first after `delay` (zero or less is due at once) and
+     * then every `period` until it is cancelled or replaced. Setting it again with the same handler and
+     * period keeps its next due time, so a service may set its recurring timers every time it starts.
+     * A period outside 1 millisecond to 36,500 days is refused with `BAD_REQUEST` before anything is sent.
+     */
+    scheduleRecurring(timerId: string, delay: Duration, period: Duration, target: TimedActionTarget, input?: unknown): Promise<void>;
+    /** Cancels the timer under `timerId`, whether it fires once or recurs. */
     cancel(timerId: string): Promise<void>;
 }
+export declare const MAX_SECRET_NAME_LENGTH = 253;
+export declare const MAX_SECRET_VALUE_BYTES = 65536;
+/** What is wrong with a secret's name, if anything: the runtime's own rule. */
+export declare function secretNameProblem(name: string): string | undefined;
+/** What is wrong with a secret's value, if anything. Never quotes the value. */
+export declare function secretValueProblem(value: string): string | undefined;
+/**
+ * The service's secret store: named text values the runtime keeps in the service's own database,
+ * encrypted with a key this process never sees. Offered to endpoints, workflow steps, consumers,
+ * timed actions and agents; an entity and a view have no `secrets` at all.
+ *
+ * Every refusal is a `CommandError` with the runtime's code: `BAD_REQUEST` for a name or a value that
+ * breaks its rule, `INTERNAL` when the service has no secret key or a value was kept with another
+ * one, `UNAVAILABLE` when the database cannot be reached.
+ */
+export declare class Secrets {
+    #private;
+    /** The store reached through `client`'s sidecar; with none, every call throws. */
+    constructor(client?: ComponentClient);
+    /** Keeps `value` under `name`, replacing what was there. */
+    put(name: string, value: string): Promise<void>;
+    /** The value kept under `name`, or `undefined` when there is none. Never an empty string. */
+    get(name: string): Promise<string | undefined>;
+    /** Removes what is kept under `name`. Removing nothing is not an error. */
+    delete(name: string): Promise<void>;
+}
+/** A secret store for unit tests: a map, applying the runtime's rules with its words. */
+export declare class InMemorySecrets extends Secrets {
+    readonly values: Map<string, string>;
+    put(name: string, value: string): Promise<void>;
+    get(name: string): Promise<string | undefined>;
+    delete(name: string): Promise<void>;
+}
+/** A store for unit tests whose every call throws: the unit kit's default, beside `noClient()`. */
+export declare function noSecrets(): Secrets;
+/**
+ * @internal What a call to another service is sent through: `client`'s sidecar, and the metadata of
+ * the handler `client` was scoped to. Not a member of the client, which an entity holds too.
+ */
+export declare function channelOf(client: ComponentClient): {
+    stub(): ConnectClient<typeof Client>;
+    metadata: Metadata;
+} | undefined;
+/**
+ * @internal The secret store reached through `client`'s sidecar. Not a member of the client, which
+ * an entity holds too: only the component kinds that may have a store call this.
+ */
+export declare function secretsFor(client: ComponentClient): Secrets;
 export declare class ComponentClient {
     #private;
     readonly views: Views;
@@ -93,6 +179,8 @@ export declare class ComponentClient {
     } | string, instanceId?: string): AutonomousAgentCalls;
     /** @internal A call with a JSON body and a JSON reply, as the platform's own components take them. */
     _raw(kind: ComponentKind, componentId: string, entityId: string, name: string, body?: unknown): Promise<unknown>;
+    /** @internal A decision on an approval request; a refusal rejects with `CommandError`. */
+    _decide(kind: ComponentKind, componentId: string, entityId: string, name: string, approvalId: string, decision: DecisionInput): Promise<void>;
     /** @internal A streaming call whose tokens are text. */
     _rawStream(kind: ComponentKind, componentId: string, entityId: string, name: string): AsyncIterable<string>;
     /** Typed calls through a component class's handler table: `client.of(ShoppingCartEntity, cartId).call(ShoppingCartEntity.handlers.addItem).invoke(item)`. */