ankka 0.7.1 → 0.9.0

package/dist/autonomous.js

@@ -0,0 +1,199 @@
+// Autonomous agents: a durable agent that is handed a task and works it on its own, iteration by
+// iteration, until it completes the task with a result its type's rules accept, fails it, or spends
+// its budget. This process declares the agent — what it is for, its tools and guardrails, the task
+// types it accepts — and the sidecar runs the loop, the model and every record. The process is asked
+// to run a tool, check a guardrail or check a task rule, each naming the task it is for.
+//
+//   export const ANSWER = taskType("answer", "Answer a question", { result: Answer, rules: [taskRule("cites-sources", (a) => a.sources.length ? accepted() : rejected("cite something"))] })
+//   export class Answerer extends AutonomousAgent {
+//     static readonly componentId = "answerer"
+//     static readonly description = "Answers questions"
+//     static readonly tools = { lookup: tool("lookup", "Looks a topic up", Topic, (a: Answerer, t) => a.lookup(t)) }
+//     static readonly accepts = [taskAcceptance(ANSWER, { maxIterations: 5 })]
+//   }
+//
+// 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 { decodeJsonValue, reviver } from "./json.js";
+import { toJsonSchema } from "./schema.js";
+export const COMPLETE_TASK = "complete_task";
+export const FAIL_TASK = "fail_task";
+export const accepted = () => Object.freeze({ verdict: "accepted" });
+export const rejected = (reason) => Object.freeze({ verdict: "rejected", reason });
+export function taskRule(name, check) {
+    if (typeof name !== "string" || name.trim() === "")
+        throw new TypeError("a task rule needs a name");
+    return Object.freeze({ name, check });
+}
+export function taskType(name, description, options = {}) {
+    if (typeof name !== "string" || name.trim() === "")
+        throw new TypeError("a task type needs a name");
+    if (typeof description !== "string" || description.trim() === "")
+        throw new TypeError(`task type ${name} needs a description`);
+    const rules = options.rules ?? [];
+    const names = rules.map((r) => r.name);
+    if (new Set(names).size !== names.length)
+        throw new TypeError(`task type ${name} declares a rule twice`);
+    return Object.freeze({ name, description, result: options.result, rules: Object.freeze([...rules]) });
+}
+/** Decodes a stored result as the task type's. */
+export function decodeResult(type, stored) {
+    const json = JSON.parse(stored, reviver);
+    return type.result ? decodeJsonValue(type.result, json) : json;
+}
+export function taskAcceptance(type, options = {}) {
+    return Object.freeze({ taskType: type, maxIterations: options.maxIterations ?? 10 });
+}
+export class AutonomousAgent {
+    #sessionId = "";
+    #client;
+    /** The task a tool, a guardrail or a rule is running for. */
+    get taskId() {
+        return this.#sessionId.startsWith("task:") ? this.#sessionId.slice("task:".length) : this.#sessionId;
+    }
+    get client() {
+        if (!this.#client)
+            throw new Error("client is only available inside a tool, a guardrail or a rule");
+        return this.#client;
+    }
+    /** @internal */
+    get _kind() {
+        return "autonomous-agent";
+    }
+    /** @internal */
+    _bind(sessionId, client) {
+        this.#sessionId = sessionId;
+        this.#client = client;
+    }
+}
+/** The discovery form of a result schema. */
+export function resultSchemaJson(type) {
+    return type.result ? JSON.stringify(toJsonSchema(type.result)) : undefined;
+}
+const TASK = "ankka-task";
+const INSTANCE = "ankka-agent-instance";
+const ENDED = new Set(["completed", "failed", "cancelled"]);
+/** Creates tasks: `await client.tasks.create(ANSWER, "How many?")` answers the new task's id. */
+export class Tasks {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /** A dependency that does not exist is refused before anything is written; one that has already ended cancels the new task. */
+    async create(type, instructions, options = {}) {
+        const id = options.id ?? crypto.randomUUID();
+        const dependencies = [...new Set(options.dependsOn ?? [])];
+        for (const dep of dependencies)
+            await this.#client._raw("event-sourced", TASK, dep, "get");
+        await this.#client._raw("event-sourced", TASK, id, "create", {
+            typeName: type.name,
+            instructions,
+            attachments: (options.attachments ?? []).map((a) => ({
+                name: a.name,
+                contentType: a.contentType,
+                content: a.uri !== undefined ? { type: "Reference", uri: a.uri } : { type: "Inline", text: a.content ?? "" },
+            })),
+            dependencies,
+        });
+        for (const dep of dependencies) {
+            const answer = (await this.#client._raw("event-sourced", TASK, dep, "add-dependent", { taskId: id }));
+            if (answer?.alreadyEnded) {
+                await this.#client._raw("event-sourced", TASK, id, "cancel", { reason: `dependency '${dep}' ${answer.alreadyEnded}` });
+                break;
+            }
+        }
+        return id;
+    }
+}
+/** Calls about one task. */
+export class TaskCalls {
+    #client;
+    taskId;
+    constructor(client, taskId) {
+        this.#client = client;
+        this.taskId = taskId;
+    }
+    async get(type) {
+        const record = (await this.#client._raw("event-sourced", TASK, this.taskId, "get"));
+        if (type && record.typeName !== type.name)
+            throw new TypeError(`task '${this.taskId}' is a '${record.typeName}' task, not '${type.name}'`);
+        const stored = record.result;
+        return Object.freeze({
+            id: record.id,
+            typeName: record.typeName,
+            status: record.status,
+            result: stored === undefined || stored === null ? undefined : type ? decodeResult(type, stored) : JSON.parse(stored),
+            reason: record.reason ?? undefined,
+            iterations: record.iterations ?? 0,
+            assignee: record.assignee ?? undefined,
+            record,
+        });
+    }
+    /** Waits until the task has completed, failed or been cancelled. */
+    async wait(type, options = {}) {
+        const deadline = Date.now() + (options.timeoutMs ?? 600_000);
+        for (;;) {
+            const snapshot = await this.get(type);
+            if (ENDED.has(snapshot.status))
+                return snapshot;
+            if (Date.now() > deadline)
+                throw new Error(`task '${this.taskId}' had not ended in time; it is ${snapshot.status}`);
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+    }
+    /** Cancels the task: at once when waiting, at the end of the current iteration when being worked. */
+    async cancel(reason = "cancelled by caller") {
+        await this.#client._raw("event-sourced", TASK, this.taskId, "cancel", { reason });
+        const record = (await this.#client._raw("event-sourced", TASK, this.taskId, "get"));
+        if (record.assignee) {
+            await this.#client._raw("autonomous-agent", record.assignee.componentId, record.assignee.instanceId, "dequeue", { taskId: this.taskId, reason });
+        }
+    }
+}
+/** Calls to one instance of an autonomous agent, by the id the caller chose; with no id, only `runSingleTask`. */
+export class AutonomousAgentCalls {
+    #client;
+    componentId;
+    instanceId;
+    constructor(client, componentId, instanceId) {
+        this.#client = client;
+        this.componentId = componentId;
+        this.instanceId = instanceId;
+    }
+    #instance() {
+        if (!this.instanceId)
+            throw new TypeError("this call needs an instance id: forAutonomousAgent(agent, instanceId)");
+        return this.instanceId;
+    }
+    /** Creates the task, starts an instance on it, and answers the task's id at once. */
+    async runSingleTask(type, instructions, options = {}) {
+        const taskId = await new Tasks(this.#client).create(type, instructions, options);
+        await this.#client._raw("autonomous-agent", this.componentId, crypto.randomUUID(), "run-single-task", { taskId });
+        return taskId;
+    }
+    assign(...taskIds) {
+        return this.#client._raw("autonomous-agent", this.componentId, this.#instance(), "assign", { taskIds });
+    }
+    async suspend() {
+        await this.#client._raw("autonomous-agent", this.componentId, this.#instance(), "suspend");
+    }
+    async resume() {
+        await this.#client._raw("autonomous-agent", this.componentId, this.#instance(), "resume");
+    }
+    /** Stops the instance for good; its tasks go back to pending for another to take. */
+    async terminate() {
+        await this.#client._raw("autonomous-agent", this.componentId, this.#instance(), "terminate");
+    }
+    async state() {
+        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 ?? [])] });
+    }
+    /** What the instance does from now on, as it happens. Nothing is replayed. */
+    async *notifications() {
+        for await (const text of this.#client._rawStream("autonomous-agent", this.componentId, this.#instance(), "notifications")) {
+            yield JSON.parse(text);
+        }
+    }
+}

package/dist/client.d.ts

@@ -5,6 +5,7 @@ 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 { AutonomousAgentCalls, TaskCalls, Tasks } from "./autonomous.ts";
 /** A component class as the typed client sees it: an id and, on its prototype, its kind. */
 export interface ComponentRef {
     readonly componentId: string;
@@ -82,6 +83,18 @@ export declare class ComponentClient {
     forKeyValueEntity(componentId: string, entityId: string): Calls;
     forWorkflow(componentId: string, workflowId: string): Calls;
     forAgent(componentId: string, sessionId: string): Calls;
+    /** Creates tasks for autonomous agents. */
+    get tasks(): Tasks;
+    /** Calls about one task. */
+    forTask(taskId: string): TaskCalls;
+    /** One instance of an autonomous agent, by the id the caller chose; without one, only `runSingleTask`, on an instance the platform names. */
+    forAutonomousAgent(agent: {
+        readonly componentId: string;
+    } | 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 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)`. */
     of<C>(component: ComponentRef & {
         new (): C;

package/dist/client.js

@@ -12,6 +12,7 @@ import { decodeJsonValue, reviver } from "./json.js";
 import { errorCodeFromProto, kindToProto } from "./kinds.js";
 import { metadataToProto } from "./context.js";
 import { encodePayload, decodePayload, EMPTY_PAYLOAD } from "./server/payloads.js";
+import { AutonomousAgentCalls, TaskCalls, Tasks } from "./autonomous.js";
 function stubOf(connection) {
     if (!connection.stub) {
         connection.transport = createGrpcTransport({ baseUrl: `http://${connection.address}` });
@@ -219,6 +220,54 @@ export class ComponentClient {
     forAgent(componentId, sessionId) {
         return new Calls(this.#connection, this.#metadata, "agent", componentId, sessionId);
     }
+    /** Creates tasks for autonomous agents. */
+    get tasks() {
+        return new Tasks(this);
+    }
+    /** Calls about one task. */
+    forTask(taskId) {
+        return new TaskCalls(this, taskId);
+    }
+    /** One instance of an autonomous agent, by the id the caller chose; without one, only `runSingleTask`, on an instance the platform names. */
+    forAutonomousAgent(agent, instanceId) {
+        return new AutonomousAgentCalls(this, typeof agent === "string" ? agent : agent.componentId, instanceId);
+    }
+    /** @internal A call with a JSON body and a JSON reply, as the platform's own components take them. */
+    async _raw(kind, componentId, entityId, name, body) {
+        const answer = await stubOf(this.#connection).invoke({
+            kind: kindToProto(kind),
+            componentId,
+            entityId,
+            name,
+            payload: { contentType: "application/json", manifest: "", data: body === undefined ? new Uint8Array() : new TextEncoder().encode(JSON.stringify(body)) },
+            metadata: metadataToProto(this.#metadata),
+        });
+        switch (answer.result.case) {
+            case "reply": {
+                const data = answer.result.value.payload?.data;
+                return data && data.length > 0 ? JSON.parse(new TextDecoder().decode(data), reviver) : undefined;
+            }
+            case "error":
+                throw new CommandError(errorOf(answer.result.value));
+            default:
+                throw new CommandError({ message: "the sidecar answered nothing", code: "INTERNAL" });
+        }
+    }
+    /** @internal A streaming call whose tokens are text. */
+    async *_rawStream(kind, componentId, entityId, name) {
+        const request = { kind: kindToProto(kind), componentId, entityId, name, payload: EMPTY_PAYLOAD, metadata: metadataToProto(this.#metadata) };
+        for await (const token of stubOf(this.#connection).invokeStream(request)) {
+            switch (token.token.case) {
+                case "text":
+                    yield token.token.value;
+                    break;
+                case "completed":
+                    return;
+                case "failed":
+                    throw new CommandError(errorOf(token.token.value));
+            }
+        }
+    }
     /** Typed calls through a component class's handler table: `client.of(ShoppingCartEntity, cartId).call(ShoppingCartEntity.handlers.addItem).invoke(item)`. */
     of(component, entityId) {
         return new TypedCalls(new Calls(this.#connection, this.#metadata, component.prototype._kind, component.componentId, entityId));

package/dist/context.d.ts

@@ -27,6 +27,19 @@ export interface Principal {
     readonly emailVerified: boolean;
     readonly roles: readonly string[];
 }
+/**
+ * Which workload sent a request, as the platform established it from the client certificate: the gateway
+ * (the internet), a named service, or — outside a cluster, where there is no certificate — the local machine.
+ */
+export type Caller = {
+    readonly kind: "gateway";
+} | {
+    readonly kind: "service";
+    readonly project: string;
+    readonly name: string;
+} | {
+    readonly kind: "local";
+};
 /** Query parameters in request order; a name may repeat. */
 export declare class Query {
     private readonly pairs;
@@ -52,6 +65,8 @@ export interface RequestContext<P = Readonly<Record<string, unknown>>> {
     /** The caller, when the route's access rule is `authenticated`; `null` otherwise. */
     readonly principal: Principal | null;
     readonly metadata: Metadata;
+    /** Which workload sent the request. Always present; see `Caller`. */
+    readonly caller: Caller;
 }
 /** Runs `fn` with `request` as the current request, for the asynchronous work it starts. */
 export declare function withRequest<T>(request: RequestContext, fn: () => T): T;

package/dist/index.d.ts

@@ -17,9 +17,10 @@ export { Consumer, type ConsumerClass } from "./consumer.ts";
 export { TimedAction, type TimedActionClass } from "./timedAction.ts";
 export { AgentEffects, type AgentEffect } from "./effects/agent.ts";
 export { Agent, type AgentClass } from "./agent.ts";
+export { AutonomousAgent, AutonomousAgentCalls, TaskCalls, Tasks, accepted, rejected, taskAcceptance, taskRule, taskType, type Accepted, type AgentState, type Attachment, type AutonomousAgentClass, type AutonomousSettings, type Notification, type Rejected, type TaskAcceptance, type TaskRule, type TaskSnapshot, type TaskType, } from "./autonomous.ts";
 export { Endpoint, type EndpointClass } from "./endpoint.ts";
-export { Acl, HttpProblem, get, post, put, patch, del, sse, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
-export { type CommandContext, type RequestContext, type Principal, Query, Headers } from "./context.ts";
+export { Acl, Callers, type CallerMatcher, type CallersAcl, HttpProblem, get, post, put, patch, del, sse, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
+export { type CommandContext, type RequestContext, type Principal, type Caller, Query, Headers } from "./context.ts";
 export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, type TimerTarget, type ComponentRef } from "./client.ts";
 export { Ankka, ServiceBuilder, Registry, RegistrationError, type ServiceOptions, type RegisteredComponent, type RegisteredEndpoint, type Source, type RegisteredEventSourced, type RegisteredKeyValue, type RegisteredWorkflow, type RegisteredView, type RegisteredConsumer, type RegisteredTimedAction, type RegisteredAgent, } from "./service.ts";
 export { Server, type ServerOptions } from "./server/server.ts";

package/dist/index.js

@@ -28,8 +28,9 @@ export { Consumer } from "./consumer.js";
 export { TimedAction } from "./timedAction.js";
 export { AgentEffects } from "./effects/agent.js";
 export { Agent } from "./agent.js";
+export { AutonomousAgent, AutonomousAgentCalls, TaskCalls, Tasks, accepted, rejected, taskAcceptance, taskRule, taskType, } from "./autonomous.js";
 export { Endpoint } from "./endpoint.js";
-export { Acl, HttpProblem, get, post, put, patch, del, sse } from "./routes.js";
+export { Acl, Callers, HttpProblem, get, post, put, patch, del, sse } from "./routes.js";
 export { Query, Headers } from "./context.js";
 export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers } from "./client.js";
 export { Ankka, ServiceBuilder, Registry, RegistrationError, } from "./service.js";

package/dist/kinds.d.ts

@@ -1,7 +1,7 @@
 import { Kind as ProtoKind } from "./_proto/ankka/protocol/v1/discovery_pb.ts";
 import { ErrorCode as ProtoErrorCode } from "./_proto/ankka/protocol/v1/payload_pb.ts";
 import { ErrorCode } from "./effects/common.ts";
-export type ComponentKind = "event-sourced" | "key-value" | "workflow" | "view" | "consumer" | "timed-action" | "agent";
+export type ComponentKind = "event-sourced" | "key-value" | "workflow" | "view" | "consumer" | "timed-action" | "agent" | "autonomous-agent";
 export declare function kindToProto(kind: ComponentKind): ProtoKind;
 export declare function kindFromProto(kind: ProtoKind): ComponentKind;
 export declare function errorCodeToProto(code: ErrorCode): ProtoErrorCode;

package/dist/kinds.js

@@ -10,6 +10,7 @@ const KIND_TO_PROTO = Object.freeze({
     consumer: ProtoKind.CONSUMER,
     "timed-action": ProtoKind.TIMED_ACTION,
     agent: ProtoKind.AGENT,
+    "autonomous-agent": ProtoKind.AUTONOMOUS_AGENT,
 });
 export function kindToProto(kind) {
     return KIND_TO_PROTO[kind];

package/dist/routes.d.ts

@@ -1,13 +1,49 @@
 import type { Shape } from "./codec.ts";
 import type { RequestContext } from "./context.ts";
 import type { Infer, Schema } from "./schema.ts";
-/** Who may call: everyone, no one, or authenticated callers only. There is no default. */
+/** One kind of caller an `Acl.allowCallers` admits; build one through `Callers`. */
+export type CallerMatcher = {
+    readonly kind: "internet";
+} | {
+    readonly kind: "service";
+    readonly name: string;
+    readonly project?: string;
+} | {
+    readonly kind: "anyInProject";
+} | {
+    readonly kind: "self";
+};
+/**
+ * The callers an endpoint can name: `Acl.allowCallers(Callers.internet, Callers.service("orders"))`. A named
+ * service is in this service's own project unless `project` names another.
+ */
+export declare const Callers: Readonly<{
+    internet: CallerMatcher;
+    anyInProject: CallerMatcher;
+    self: CallerMatcher;
+    service(name: string, options?: {
+        readonly project?: string;
+    }): CallerMatcher;
+}>;
+/** Only the callers named. In a cluster the caller is read from the certificate the platform issued. */
+export interface CallersAcl {
+    readonly kind: "callers";
+    readonly callers: readonly CallerMatcher[];
+}
+/**
+ * Who may call: everyone, no one, authenticated callers only, or only the callers named. There is no default.
+ *
+ * Outside a cluster every caller is `{ kind: "local" }`, and `allowCallers` admits it.
+ */
+export type Acl = "allow-all" | "deny-all" | "authenticated" | CallersAcl;
 export declare const Acl: Readonly<{
-    readonly allowAll: "allow-all";
-    readonly denyAll: "deny-all";
-    readonly authenticated: "authenticated";
+    allowAll: Acl;
+    denyAll: Acl;
+    authenticated: Acl;
+    allowCallers(first: CallerMatcher, ...rest: CallerMatcher[]): Acl;
 }>;
-export type Acl = (typeof Acl)[keyof typeof Acl];
+/** Whether `x` is an access rule: one of the three words, or a non-empty callers rule. */
+export declare function isAcl(x: unknown): x is Acl;
 /** Thrown from a route handler to answer a status other than 200 with a plain-text message. */
 export declare class HttpProblem extends Error {
     readonly status: number;

package/dist/routes.js

@@ -9,12 +9,35 @@
 //
 // `req.params` is typed from the template: "/{cartId}/items" gives { cartId: string }.
 import { isCodec } from "./codec.js";
-/** Who may call: everyone, no one, or authenticated callers only. There is no default. */
+/**
+ * The callers an endpoint can name: `Acl.allowCallers(Callers.internet, Callers.service("orders"))`. A named
+ * service is in this service's own project unless `project` names another.
+ */
+export const Callers = Object.freeze({
+    internet: Object.freeze({ kind: "internet" }),
+    anyInProject: Object.freeze({ kind: "anyInProject" }),
+    self: Object.freeze({ kind: "self" }),
+    service(name, options) {
+        return Object.freeze(options?.project !== undefined ? { kind: "service", name, project: options.project } : { kind: "service", name });
+    },
+});
 export const Acl = Object.freeze({
     allowAll: "allow-all",
     denyAll: "deny-all",
     authenticated: "authenticated",
+    allowCallers(first, ...rest) {
+        return Object.freeze({ kind: "callers", callers: Object.freeze([first, ...rest]) });
+    },
 });
+/** Whether `x` is an access rule: one of the three words, or a non-empty callers rule. */
+export function isAcl(x) {
+    if (x === "allow-all" || x === "deny-all" || x === "authenticated")
+        return true;
+    if (typeof x !== "object" || x === null)
+        return false;
+    const rule = x;
+    return rule.kind === "callers" && Array.isArray(rule.callers) && rule.callers.length > 0;
+}
 /** Thrown from a route handler to answer a status other than 200 with a plain-text message. */
 export class HttpProblem extends Error {
     status;

package/dist/server/agent.d.ts

@@ -1,5 +1,5 @@
-import type { ConnectRouter } from "@connectrpc/connect";
-import { type GuardrailRequest, type GuardrailResult, type PlanReply, type PlanRequest, type ToolRequest, type ToolResult } from "../_proto/ankka/protocol/v1/agent_pb.ts";
+import { type ConnectRouter } from "@connectrpc/connect";
+import { type GuardrailRequest, type GuardrailResult, type PlanReply, type PlanRequest, type TaskResultRequest, type TaskResultVerdict, type ToolRequest, type ToolResult } from "../_proto/ankka/protocol/v1/agent_pb.ts";
 import type { AgentEffect } from "../effects/agent.ts";
 import type { Agent } from "../agent.ts";
 import type { RegisteredAgent } from "../service.ts";
@@ -11,4 +11,10 @@ export declare function handlePlan(req: PlanRequest, ctx: ServerContext): Promis
 export declare function runTool(registered: RegisteredAgent, agent: Agent, name: string, argumentsJson: string): Promise<string>;
 export declare function handleTool(req: ToolRequest, ctx: ServerContext): Promise<ToolResult>;
 export declare function handleGuardrail(req: GuardrailRequest, ctx: ServerContext): Promise<GuardrailResult>;
+/**
+ * An autonomous agent's result: decoded as its task type's, then put through its rules in order. A
+ * rule that throws is answered as an error, which the sidecar takes as a failed iteration and tries
+ * again — never as a verdict, since nothing was decided.
+ */
+export declare function handleTaskResult(req: TaskResultRequest, ctx: ServerContext): Promise<TaskResultVerdict>;
 export declare function agentRoutes(router: ConnectRouter, ctx: ServerContext): void;

package/dist/server/agent.js

@@ -1,13 +1,15 @@
 // The agent conversation: the sidecar asks this process to plan (an AgentEffect as data), to run a tool
 // with the model's arguments, and to check a guardrail. The loop, the memory and the model's key are
 // the sidecar's.
+import { Code, ConnectError } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
-import { Agent as AgentService, AgentPlan_Memory, GuardrailRequest_Stage, GuardrailResultSchema, PlanReplySchema, ToolResultSchema, } from "../_proto/ankka/protocol/v1/agent_pb.js";
+import { Agent as AgentService, AgentPlan_Memory, GuardrailRequest_Stage, GuardrailResultSchema, PlanReplySchema, TaskResultVerdictSchema, ToolResultSchema, } from "../_proto/ankka/protocol/v1/agent_pb.js";
 import { codecFor, isCodec } from "../codec.js";
 import { metadataFromProto } from "../context.js";
 import { ErrorCode } from "../effects/common.js";
 import { decodeJsonValue, reviver } from "../json.js";
 import { errorCodeToProto } from "../kinds.js";
+import { decodeResult } from "../autonomous.js";
 import { decodePayload } from "./payloads.js";
 function messageOf(e) {
     return e instanceof Error ? e.message : String(e);
@@ -75,6 +77,9 @@ export async function runTool(registered, agent, name, argumentsJson) {
     return typeof result === "string" ? result : JSON.stringify(result, (_k, v) => (typeof v === "bigint" ? v.toString() : v));
 }
 export async function handleTool(req, ctx) {
+    const autonomous = ctx.registry.of("autonomous-agent", req.componentId);
+    if (autonomous)
+        return handleAutonomousTool(autonomous, req, ctx);
     const registered = ctx.registry.of("agent", req.componentId);
     if (!registered)
         return create(ToolResultSchema, { result: { case: "error", value: `no agent ${JSON.stringify(req.componentId)} is registered` } });
@@ -89,7 +94,7 @@ export async function handleTool(req, ctx) {
     }
 }
 export async function handleGuardrail(req, ctx) {
-    const registered = ctx.registry.of("agent", req.componentId);
+    const registered = ctx.registry.of("agent", req.componentId) ?? ctx.registry.of("autonomous-agent", req.componentId);
     const guardrail = registered?.guardrails.get(req.guardrail);
     if (!registered || !guardrail)
         return create(GuardrailResultSchema, { result: { case: "block", value: `no guardrail ${JSON.stringify(req.guardrail)} on ${req.componentId}` } });
@@ -104,10 +109,62 @@ export async function handleGuardrail(req, ctx) {
         return create(GuardrailResultSchema, { result: { case: "block", value: `guardrail ${req.guardrail} failed: ${messageOf(e)}` } });
     }
 }
+async function handleAutonomousTool(registered, req, ctx) {
+    const tool = registered.tools.get(req.tool);
+    if (!tool)
+        return create(ToolResultSchema, { result: { case: "error", value: `no tool ${JSON.stringify(req.tool)} on ${registered.id}` } });
+    const agent = new registered.cls();
+    agent._bind(req.sessionId, ctx.client);
+    try {
+        let input;
+        if (isCodec(tool.input))
+            input = tool.input.decode(new TextEncoder().encode(req.argumentsJson));
+        else
+            input = decodeJsonValue(tool.input, JSON.parse(req.argumentsJson || "{}", reviver));
+        const result = await tool.run(agent, input);
+        const text = typeof result === "string" ? result : JSON.stringify(result, (_k, v) => (typeof v === "bigint" ? v.toString() : v));
+        return create(ToolResultSchema, { result: { case: "ok", value: text } });
+    }
+    catch (e) {
+        return create(ToolResultSchema, { result: { case: "error", value: messageOf(e) } });
+    }
+}
+/**
+ * An autonomous agent's result: decoded as its task type's, then put through its rules in order. A
+ * rule that throws is answered as an error, which the sidecar takes as a failed iteration and tries
+ * again — never as a verdict, since nothing was decided.
+ */
+export async function handleTaskResult(req, ctx) {
+    const registered = ctx.registry.of("autonomous-agent", req.componentId);
+    const type = registered?.taskTypes.get(req.taskType);
+    if (!registered || !type)
+        throw new ConnectError(`no task type ${JSON.stringify(req.taskType)} on ${req.componentId}`, Code.NotFound);
+    let result;
+    try {
+        result = decodeResult(type, req.resultJson);
+    }
+    catch (e) {
+        return create(TaskResultVerdictSchema, { verdict: { case: "malformed", value: messageOf(e) } });
+    }
+    for (const rule of type.rules) {
+        let verdict;
+        try {
+            verdict = await rule.check(result);
+        }
+        catch (e) {
+            ctx.log(`ankka: rule ${registered.id}/${req.taskType}/${rule.name} threw: ${messageOf(e)}`);
+            throw new ConnectError(`rule ${rule.name} threw: ${messageOf(e)}`, Code.Internal);
+        }
+        if (verdict.verdict === "rejected")
+            return create(TaskResultVerdictSchema, { verdict: { case: "reject", value: { rule: rule.name, reason: verdict.reason } } });
+    }
+    return create(TaskResultVerdictSchema, { verdict: { case: "accept", value: {} } });
+}
 export function agentRoutes(router, ctx) {
     router.service(AgentService, {
         plan: (req) => handlePlan(req, ctx),
         invokeTool: (req) => handleTool(req, ctx),
         checkGuardrail: (req) => handleGuardrail(req, ctx),
+        checkTaskResult: (req) => handleTaskResult(req, ctx),
     });
 }

package/dist/server/http.js

@@ -30,6 +30,18 @@ function principalOf(req) {
         return null;
     return Object.freeze({ subject: p.subject, name: p.name ?? null, email: p.email ?? null, emailVerified: p.emailVerified, roles: Object.freeze([...p.roles]) });
 }
+/** The caller the sidecar established; a sidecar that predates protocol 1.1 sends none, which reads as local. */
+function callerOf(req) {
+    const kind = req.caller?.kind;
+    switch (kind?.case) {
+        case "gateway":
+            return Object.freeze({ kind: "gateway" });
+        case "service":
+            return Object.freeze({ kind: "service", project: kind.value.project, name: kind.value.name });
+        default:
+            return Object.freeze({ kind: "local" });
+    }
+}
 /** A path parameter as its declared schema: strings as they are, scalars through their text codec. */
 function parseParam(name, text, shape) {
     if (!shape)
@@ -82,6 +94,7 @@ export function createHttpDispatcher(ctx) {
                 headers: new Headers(req.headers.map((p) => [p.name, p.value])),
                 principal: principalOf(req),
                 metadata: metadataFromProto(req.metadata),
+                caller: callerOf(req),
             });
             const body = route.body ? codecFor(route.body).decode(req.body) : undefined;
             return { ok: true, prepared: { endpoint, route, instance, request, body } };

package/dist/service.d.ts

@@ -6,6 +6,7 @@ import { View, type ViewClass } from "./view.ts";
 import { Consumer, type ConsumerClass } from "./consumer.ts";
 import { TimedAction, type TimedActionClass } from "./timedAction.ts";
 import { Agent, type AgentClass } from "./agent.ts";
+import { AutonomousAgent, type AutonomousAgentClass, type TaskType } from "./autonomous.ts";
 import { Endpoint, type EndpointClass } from "./endpoint.ts";
 import type { GuardrailRef, HandlerRef, ToolRef } from "./handlers.ts";
 import type { RouteRef, Acl } from "./routes.ts";
@@ -82,7 +83,15 @@ export interface RegisteredAgent {
     readonly role: string;
     readonly maxToolCallSteps: number;
 }
-export type RegisteredComponent = RegisteredEventSourced | RegisteredKeyValue | RegisteredWorkflow | RegisteredView | RegisteredConsumer | RegisteredTimedAction | RegisteredAgent;
+export interface RegisteredAutonomousAgent {
+    readonly kind: "autonomous-agent";
+    readonly id: string;
+    readonly cls: AutonomousAgentClass<any>;
+    readonly tools: ReadonlyMap<string, ToolRef<any, any>>;
+    readonly guardrails: ReadonlyMap<string, GuardrailRef>;
+    readonly taskTypes: ReadonlyMap<string, TaskType<any>>;
+}
+export type RegisteredComponent = RegisteredEventSourced | RegisteredKeyValue | RegisteredWorkflow | RegisteredView | RegisteredConsumer | RegisteredTimedAction | RegisteredAgent | RegisteredAutonomousAgent;
 export interface RegisteredEndpoint {
     readonly id: string;
     readonly cls: EndpointClass<any>;
@@ -127,6 +136,7 @@ export declare class ServiceBuilder {
     register<M, Out, C extends Consumer<M, Out>>(cls: ConsumerClass<M, Out, C>): this;
     register<C extends TimedAction>(cls: TimedActionClass<C>): this;
     register<C extends Agent>(cls: AgentClass<C>): this;
+    register<C extends AutonomousAgent>(cls: AutonomousAgentClass<C>): this;
     register<C extends Endpoint>(cls: EndpointClass<C>): this;
     /** Validates every registration and returns the registry, or throws a `RegistrationError` naming every problem. */
     validate(): Registry;