ankka 0.8.0 → 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/index.d.ts

@@ -17,6 +17,7 @@ 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, 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";

package/dist/index.js

@@ -28,6 +28,7 @@ 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, Callers, HttpProblem, get, post, put, patch, del, sse } from "./routes.js";
 export { Query, Headers } from "./context.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/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/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;

package/dist/service.js

@@ -11,6 +11,7 @@ import { View } from "./view.js";
 import { Consumer } from "./consumer.js";
 import { TimedAction } from "./timedAction.js";
 import { Agent } from "./agent.js";
+import { AutonomousAgent, COMPLETE_TASK, FAIL_TASK } from "./autonomous.js";
 import { Endpoint } from "./endpoint.js";
 import { isAcl } from "./routes.js";
 import { ComponentClient } from "./client.js";
@@ -100,6 +101,8 @@ export class ServiceBuilder {
                 add(registerTimedAction(cls, problems), cls);
             else if (extendsBase(cls, Agent))
                 add(registerAgent(cls, problems), cls);
+            else if (extendsBase(cls, AutonomousAgent))
+                add(registerAutonomousAgent(cls, problems), cls);
             else if (extendsBase(cls, Endpoint)) {
                 const ep = cls;
                 if (typeof ep.prefix === "string") {
@@ -117,7 +120,7 @@ export class ServiceBuilder {
                 }
             }
             else {
-                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, Consumer, TimedAction, Agent or Endpoint`);
+                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, Consumer, TimedAction, Agent, AutonomousAgent or Endpoint`);
             }
         }
         if (problems.length > 0)
@@ -314,6 +317,44 @@ function registerAgent(cls, problems) {
         return undefined;
     return Object.freeze({ kind: "agent", id: cls.componentId, cls, handlers, tools, guardrails, role: cls.role ?? "", maxToolCallSteps });
 }
+function registerAutonomousAgent(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    if (typeof cls.description !== "string" || cls.description.trim() === "")
+        fail("a description is required");
+    const tools = new Map();
+    for (const [property, t] of Object.entries(cls.tools ?? {})) {
+        if (typeof t !== "object" || t === null || typeof t.name !== "string" || typeof t.run !== "function") {
+            fail(`tools.${property} is not a tool: declare it with tool(name, description, input, run)`);
+            continue;
+        }
+        if (t.name === COMPLETE_TASK || t.name === FAIL_TASK)
+            fail(`tool name ${JSON.stringify(t.name)} is reserved`);
+        if (tools.has(t.name))
+            fail(`two tools declare the name ${JSON.stringify(t.name)}`);
+        tools.set(t.name, t);
+    }
+    const guardrails = new Map();
+    for (const g of Object.values(cls.guardrails ?? {})) {
+        if (guardrails.has(g.name))
+            fail(`two guardrails declare the name ${JSON.stringify(g.name)}`);
+        guardrails.set(g.name, g);
+    }
+    const taskTypes = new Map();
+    const accepts = cls.accepts ?? [];
+    if (accepts.length === 0)
+        fail("it accepts no task type: declare accepts = [taskAcceptance(...)]");
+    for (const a of accepts) {
+        if (taskTypes.has(a.taskType.name))
+            fail(`task type ${JSON.stringify(a.taskType.name)} is accepted twice`);
+        if (!Number.isInteger(a.maxIterations) || a.maxIterations < 1)
+            fail(`task type ${JSON.stringify(a.taskType.name)} needs a budget of at least one iteration`);
+        taskTypes.set(a.taskType.name, a.taskType);
+    }
+    if (!ok())
+        return undefined;
+    return Object.freeze({ kind: "autonomous-agent", id: cls.componentId, cls, tools, guardrails, taskTypes });
+}
 /** Collects a handler table by wire name, reporting a duplicate wire name or a kind the component cannot host. */
 export function collectHandlers(table, what, allowed, fail) {
     const out = new Map();

package/dist/spec.d.ts

@@ -2,7 +2,7 @@ import { type MessageInitShape } from "@bufbuild/protobuf";
 import { Endpoint_Acl, type CallerMatcherSchema, type Spec } from "./_proto/ankka/protocol/v1/discovery_pb.ts";
 import type { Registry } from "./service.ts";
 import type { Acl } from "./routes.ts";
-export declare const PROTOCOL_VERSION = "1.1";
+export declare const PROTOCOL_VERSION = "1.2";
 export declare const SDK_NAME = "ankka-typescript";
 export declare function aclToProto(acl: Acl): Endpoint_Acl;
 /** The callers a CALLERS acl names, as discovery carries them; empty for every other rule. */

package/dist/spec.js

@@ -1,11 +1,12 @@
 // Renders the discovery Spec from the registry: what the sidecar hosts is exactly what is registered.
 import { create } from "@bufbuild/protobuf";
 import { Endpoint_Acl, SpecSchema } from "./_proto/ankka/protocol/v1/discovery_pb.js";
+import { resultSchemaJson } from "./autonomous.js";
 import { kindToProto } from "./kinds.js";
 import { toJsonSchema } from "./schema.js";
 import { isCodec } from "./codec.js";
 import { VERSION } from "./version.js";
-export const PROTOCOL_VERSION = "1.1";
+export const PROTOCOL_VERSION = "1.2";
 export const SDK_NAME = "ankka-typescript";
 export function aclToProto(acl) {
     if (typeof acl === "object")
@@ -66,6 +67,8 @@ function settingsInit(s) {
 function componentInit(c) {
     const base = { kind: kindToProto(c.kind), id: c.id };
     switch (c.kind) {
+        case "autonomous-agent":
+            return autonomousInit(c);
         case "event-sourced":
             return { ...base, handlers: handlerInits(c.handlers), detail: { case: "eventSourced", value: { snapshotEvery: c.snapshotEvery } } };
         case "key-value":
@@ -100,6 +103,40 @@ function componentInit(c) {
             };
     }
 }
+function settingsOf(s) {
+    return {
+        ...(s.approachingBudgetAt !== undefined ? { approachingBudgetAt: s.approachingBudgetAt } : {}),
+        ...(s.repeatedFailureAt !== undefined ? { repeatedFailureAt: s.repeatedFailureAt } : {}),
+        ...(s.maxConsecutiveFailures !== undefined ? { maxConsecutiveFailures: s.maxConsecutiveFailures } : {}),
+        ...(s.dependencyStuckAfterMillis !== undefined ? { dependencyStuckAfterMillis: BigInt(s.dependencyStuckAfterMillis) } : {}),
+    };
+}
+function autonomousInit(c) {
+    const cls = c.cls;
+    return {
+        kind: kindToProto(c.kind),
+        id: c.id,
+        handlers: [],
+        detail: {
+            case: "autonomousAgent",
+            value: {
+                description: cls.description,
+                ...(cls.instructions !== undefined ? { instructions: cls.instructions } : {}),
+                ...(cls.model !== undefined ? { model: cls.model } : {}),
+                tools: [...c.tools.values()]
+                    .sort((a, b) => a.name.localeCompare(b.name))
+                    .map((t) => ({ name: t.name, description: t.description, inputSchemaJson: JSON.stringify(isCodec(t.input) ? { type: "object" } : toJsonSchema(t.input)) })),
+                guardrails: [...c.guardrails.keys()].sort(),
+                taskTypes: [...c.taskTypes.values()].map((t) => {
+                    const schema = resultSchemaJson(t);
+                    return { name: t.name, description: t.description, rules: t.rules.map((r) => r.name), ...(schema !== undefined ? { resultSchemaJson: schema } : {}) };
+                }),
+                accepts: cls.accepts.map((a) => ({ taskType: a.taskType.name, maxIterations: a.maxIterations })),
+                ...(cls.settings ? { settings: settingsOf(cls.settings) } : {}),
+            },
+        },
+    };
+}
 export function renderSpec(registry) {
     const components = [...registry.components.values()].sort((a, b) => a.id.localeCompare(b.id)).map(componentInit);
     const endpoints = [...registry.endpoints.values()].map((e) => ({

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.8.0";
+export declare const VERSION = "0.9.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Written by scripts/proto.ts from package.json; do not edit. 0.0.0 in the tree, the tag's version in a release.
-export const VERSION = "0.8.0";
+export const VERSION = "0.9.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ankka",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Build services on ankka in TypeScript: entities, views, workflows, agents and endpoints hosted by the ankka sidecar.",
   "license": "Apache-2.0",
   "type": "module",