ankka 0.6.0

package/README.md

@@ -0,0 +1,30 @@
+# ankka for TypeScript
+
+The ankka SDK for services written in TypeScript on Node.js. A service is a process that the ankka
+runtime hosts as a sidecar: the sidecar owns everything durable and distributed, and the process owns
+the decisions. This package speaks the sidecar protocol so your code never does.
+
+Documentation: <https://docs.ankka.cloud/> — start with *Your first service in TypeScript* and the
+*TypeScript SDK* reference.
+
+```bash
+npm install ankka                  # the SDK
+npm install -D testcontainers @testcontainers/postgresql   # only if you use the integration testkit
+```
+
+Node 22.22 or later. A service runs from source: `node main.ts`.
+
+## Developing the SDK
+
+```bash
+npm ci
+npm run proto                      # copy protocol/ in, generate src/_proto, write src/version.ts
+npm run typecheck                  # tsc --noEmit over src, test, examples
+npm test                           # the fast tests, no Docker
+npm run test:slow                  # the Docker-backed tests (needs the ankka-sidecar image)
+npm run conformance                # the platform's conformance suite against this SDK's reference service
+npm run build                      # emit dist/, what the package ships
+```
+
+`proto/` is a verbatim copy of the repository's `protocol/`; CI fails when the two differ, so a
+protocol change reaches this SDK deliberately by running `npm run proto`.

package/dist/_proto/ankka/protocol/v1/agent_pb.d.ts

@@ -0,0 +1,350 @@
+import type { GenEnum, GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
+import type { Empty, Error, Failure, Metadata, Payload } from "./payload_pb.ts";
+import type { Message, UnknownEnum } from "@bufbuild/protobuf";
+/**
+ * Describes the file ankka/protocol/v1/agent.proto.
+ */
+export declare const file_ankka_protocol_v1_agent: GenFile;
+/**
+ * @generated from message ankka.protocol.v1.PlanRequest
+ */
+export type PlanRequest = Message<"ankka.protocol.v1.PlanRequest"> & {
+    /**
+     * @generated from field: string component_id = 1;
+     */
+    componentId: string;
+    /**
+     * @generated from field: string session_id = 2;
+     */
+    sessionId: string;
+    /**
+     * @generated from field: string name = 3;
+     */
+    name: string;
+    /**
+     * @generated from field: ankka.protocol.v1.Payload payload = 4;
+     */
+    payload?: Payload | undefined;
+    /**
+     * @generated from field: ankka.protocol.v1.Metadata metadata = 5;
+     */
+    metadata?: Metadata | undefined;
+};
+/**
+ * Describes the message ankka.protocol.v1.PlanRequest.
+ * Use `create(PlanRequestSchema)` to create a new message.
+ */
+export declare const PlanRequestSchema: GenMessage<PlanRequest>;
+/**
+ * @generated from message ankka.protocol.v1.PlanReply
+ */
+export type PlanReply = Message<"ankka.protocol.v1.PlanReply"> & {
+    /**
+     * @generated from oneof ankka.protocol.v1.PlanReply.message
+     */
+    message: {
+        /**
+         * @generated from field: ankka.protocol.v1.AgentPlan plan = 1;
+         */
+        value: AgentPlan;
+        case: "plan";
+    } | {
+        /**
+         * @generated from field: ankka.protocol.v1.Failure failure = 2;
+         */
+        value: Failure;
+        case: "failure";
+    } | {
+        case: undefined;
+        value?: undefined;
+    };
+};
+/**
+ * Describes the message ankka.protocol.v1.PlanReply.
+ * Use `create(PlanReplySchema)` to create a new message.
+ */
+export declare const PlanReplySchema: GenMessage<PlanReply>;
+/**
+ * AgentEffect, as data
+ *
+ * @generated from message ankka.protocol.v1.AgentPlan
+ */
+export type AgentPlan = Message<"ankka.protocol.v1.AgentPlan"> & {
+    /**
+     * a name in the sidecar's configuration
+     *
+     * @generated from field: optional string model = 1;
+     */
+    model?: string | undefined;
+    /**
+     * @generated from field: optional string system = 2;
+     */
+    system?: string | undefined;
+    /**
+     * @generated from field: optional string user = 3;
+     */
+    user?: string | undefined;
+    /**
+     * @generated from field: repeated string context = 4;
+     */
+    context: string[];
+    /**
+     * @generated from field: ankka.protocol.v1.AgentPlan.Memory memory = 5;
+     */
+    memory: AgentPlan_Memory;
+    /**
+     * names declared in discovery
+     *
+     * @generated from field: repeated string tools = 6;
+     */
+    tools: string[];
+    /**
+     * @generated from field: ankka.protocol.v1.AgentPlan.ResponseShape response_shape = 7;
+     */
+    responseShape?: AgentPlan_ResponseShape | undefined;
+    /**
+     * names declared in discovery
+     *
+     * @generated from field: repeated string guardrails = 8;
+     */
+    guardrails: string[];
+    /**
+     * effects.error(...): a refusal before any model call
+     *
+     * @generated from field: optional ankka.protocol.v1.Error failure = 9;
+     */
+    failure?: Error | undefined;
+};
+/**
+ * Describes the message ankka.protocol.v1.AgentPlan.
+ * Use `create(AgentPlanSchema)` to create a new message.
+ */
+export declare const AgentPlanSchema: GenMessage<AgentPlan>;
+/**
+ * @generated from message ankka.protocol.v1.AgentPlan.ResponseShape
+ */
+export type AgentPlan_ResponseShape = Message<"ankka.protocol.v1.AgentPlan.ResponseShape"> & {
+    /**
+     * @generated from oneof ankka.protocol.v1.AgentPlan.ResponseShape.shape
+     */
+    shape: {
+        /**
+         * @generated from field: ankka.protocol.v1.Empty text = 1;
+         */
+        value: Empty;
+        case: "text";
+    } | {
+        /**
+         * @generated from field: ankka.protocol.v1.AgentPlan.ResponseShape.Json json = 2;
+         */
+        value: AgentPlan_ResponseShape_Json;
+        case: "json";
+    } | {
+        case: undefined;
+        value?: undefined;
+    };
+};
+/**
+ * Describes the message ankka.protocol.v1.AgentPlan.ResponseShape.
+ * Use `create(AgentPlan_ResponseShapeSchema)` to create a new message.
+ */
+export declare const AgentPlan_ResponseShapeSchema: GenMessage<AgentPlan_ResponseShape>;
+/**
+ * @generated from message ankka.protocol.v1.AgentPlan.ResponseShape.Json
+ */
+export type AgentPlan_ResponseShape_Json = Message<"ankka.protocol.v1.AgentPlan.ResponseShape.Json"> & {
+    /**
+     * @generated from field: string schema_hint = 1;
+     */
+    schemaHint: string;
+};
+/**
+ * Describes the message ankka.protocol.v1.AgentPlan.ResponseShape.Json.
+ * Use `create(AgentPlan_ResponseShape_JsonSchema)` to create a new message.
+ */
+export declare const AgentPlan_ResponseShape_JsonSchema: GenMessage<AgentPlan_ResponseShape_Json>;
+/**
+ * @generated from enum ankka.protocol.v1.AgentPlan.Memory
+ */
+export declare const AgentPlan_Memory: {
+    /**
+     * @generated from enum value: SESSION = 0;
+     */
+    readonly SESSION: 0;
+    /**
+     * @generated from enum value: NONE = 1;
+     */
+    readonly NONE: 1;
+};
+/**
+ * @generated from enum ankka.protocol.v1.AgentPlan.Memory
+ */
+export type AgentPlan_Memory = (typeof AgentPlan_Memory)[keyof typeof AgentPlan_Memory] | UnknownEnum;
+/**
+ * Describes the enum ankka.protocol.v1.AgentPlan.Memory.
+ */
+export declare const AgentPlan_MemorySchema: GenEnum<AgentPlan_Memory>;
+/**
+ * @generated from message ankka.protocol.v1.ToolRequest
+ */
+export type ToolRequest = Message<"ankka.protocol.v1.ToolRequest"> & {
+    /**
+     * @generated from field: string component_id = 1;
+     */
+    componentId: string;
+    /**
+     * @generated from field: string session_id = 2;
+     */
+    sessionId: string;
+    /**
+     * @generated from field: string tool = 3;
+     */
+    tool: string;
+    /**
+     * @generated from field: string arguments_json = 4;
+     */
+    argumentsJson: string;
+};
+/**
+ * Describes the message ankka.protocol.v1.ToolRequest.
+ * Use `create(ToolRequestSchema)` to create a new message.
+ */
+export declare const ToolRequestSchema: GenMessage<ToolRequest>;
+/**
+ * @generated from message ankka.protocol.v1.ToolResult
+ */
+export type ToolResult = Message<"ankka.protocol.v1.ToolResult"> & {
+    /**
+     * @generated from oneof ankka.protocol.v1.ToolResult.result
+     */
+    result: {
+        /**
+         * @generated from field: string ok = 1;
+         */
+        value: string;
+        case: "ok";
+    } | {
+        /**
+         * @generated from field: string error = 2;
+         */
+        value: string;
+        case: "error";
+    } | {
+        case: undefined;
+        value?: undefined;
+    };
+};
+/**
+ * Describes the message ankka.protocol.v1.ToolResult.
+ * Use `create(ToolResultSchema)` to create a new message.
+ */
+export declare const ToolResultSchema: GenMessage<ToolResult>;
+/**
+ * @generated from message ankka.protocol.v1.GuardrailRequest
+ */
+export type GuardrailRequest = Message<"ankka.protocol.v1.GuardrailRequest"> & {
+    /**
+     * @generated from field: string component_id = 1;
+     */
+    componentId: string;
+    /**
+     * @generated from field: string session_id = 2;
+     */
+    sessionId: string;
+    /**
+     * @generated from field: string guardrail = 3;
+     */
+    guardrail: string;
+    /**
+     * @generated from field: ankka.protocol.v1.GuardrailRequest.Stage stage = 4;
+     */
+    stage: GuardrailRequest_Stage;
+    /**
+     * @generated from field: string text = 5;
+     */
+    text: string;
+};
+/**
+ * Describes the message ankka.protocol.v1.GuardrailRequest.
+ * Use `create(GuardrailRequestSchema)` to create a new message.
+ */
+export declare const GuardrailRequestSchema: GenMessage<GuardrailRequest>;
+/**
+ * @generated from enum ankka.protocol.v1.GuardrailRequest.Stage
+ */
+export declare const GuardrailRequest_Stage: {
+    /**
+     * @generated from enum value: INPUT = 0;
+     */
+    readonly INPUT: 0;
+    /**
+     * @generated from enum value: OUTPUT = 1;
+     */
+    readonly OUTPUT: 1;
+};
+/**
+ * @generated from enum ankka.protocol.v1.GuardrailRequest.Stage
+ */
+export type GuardrailRequest_Stage = (typeof GuardrailRequest_Stage)[keyof typeof GuardrailRequest_Stage] | UnknownEnum;
+/**
+ * Describes the enum ankka.protocol.v1.GuardrailRequest.Stage.
+ */
+export declare const GuardrailRequest_StageSchema: GenEnum<GuardrailRequest_Stage>;
+/**
+ * @generated from message ankka.protocol.v1.GuardrailResult
+ */
+export type GuardrailResult = Message<"ankka.protocol.v1.GuardrailResult"> & {
+    /**
+     * @generated from oneof ankka.protocol.v1.GuardrailResult.result
+     */
+    result: {
+        /**
+         * @generated from field: ankka.protocol.v1.Empty pass = 1;
+         */
+        value: Empty;
+        case: "pass";
+    } | {
+        /**
+         * @generated from field: string block = 2;
+         */
+        value: string;
+        case: "block";
+    } | {
+        case: undefined;
+        value?: undefined;
+    };
+};
+/**
+ * Describes the message ankka.protocol.v1.GuardrailResult.
+ * Use `create(GuardrailResultSchema)` to create a new message.
+ */
+export declare const GuardrailResultSchema: GenMessage<GuardrailResult>;
+/**
+ * @generated from service ankka.protocol.v1.Agent
+ */
+export declare const Agent: GenService<{
+    /**
+     * @generated from rpc ankka.protocol.v1.Agent.Plan
+     */
+    plan: {
+        methodKind: "unary";
+        input: typeof PlanRequestSchema;
+        output: typeof PlanReplySchema;
+    };
+    /**
+     * @generated from rpc ankka.protocol.v1.Agent.InvokeTool
+     */
+    invokeTool: {
+        methodKind: "unary";
+        input: typeof ToolRequestSchema;
+        output: typeof ToolResultSchema;
+    };
+    /**
+     * @generated from rpc ankka.protocol.v1.Agent.CheckGuardrail
+     */
+    checkGuardrail: {
+        methodKind: "unary";
+        input: typeof GuardrailRequestSchema;
+        output: typeof GuardrailResultSchema;
+    };
+}>;

package/dist/_proto/ankka/protocol/v1/agent_pb.js

@@ -0,0 +1,90 @@
+// Agents: the process plans (an AgentEffect as data) and runs tools; the sidecar runs the loop.
+import { enumDesc, fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv2";
+import { file_ankka_protocol_v1_payload } from "./payload_pb.js";
+/**
+ * Describes the file ankka/protocol/v1/agent.proto.
+ */
+export const file_ankka_protocol_v1_agent = /*@__PURE__*/ fileDesc("Ch1hbmtrYS9wcm90b2NvbC92MS9hZ2VudC5wcm90bxIRYW5ra2EucHJvdG9jb2wudjEioQEKC1BsYW5SZXF1ZXN0EhQKDGNvbXBvbmVudF9pZBgBIAEoCRISCgpzZXNzaW9uX2lkGAIgASgJEgwKBG5hbWUYAyABKAkSKwoHcGF5bG9hZBgEIAEoCzIaLmFua2thLnByb3RvY29sLnYxLlBheWxvYWQSLQoIbWV0YWRhdGEYBSABKAsyGy5hbmtrYS5wcm90b2NvbC52MS5NZXRhZGF0YSJzCglQbGFuUmVwbHkSLAoEcGxhbhgBIAEoCzIcLmFua2thLnByb3RvY29sLnYxLkFnZW50UGxhbkgAEi0KB2ZhaWx1cmUYAiABKAsyGi5hbmtrYS5wcm90b2NvbC52MS5GYWlsdXJlSABCCQoHbWVzc2FnZSKSBAoJQWdlbnRQbGFuEhIKBW1vZGVsGAEgASgJSACIAQESEwoGc3lzdGVtGAIgASgJSAGIAQESEQoEdXNlchgDIAEoCUgCiAEBEg8KB2NvbnRleHQYBCADKAkSMwoGbWVtb3J5GAUgASgOMiMuYW5ra2EucHJvdG9jb2wudjEuQWdlbnRQbGFuLk1lbW9yeRINCgV0b29scxgGIAMoCRJCCg5yZXNwb25zZV9zaGFwZRgHIAEoCzIqLmFua2thLnByb3RvY29sLnYxLkFnZW50UGxhbi5SZXNwb25zZVNoYXBlEhIKCmd1YXJkcmFpbHMYCCADKAkSLgoHZmFpbHVyZRgJIAEoCzIYLmFua2thLnByb3RvY29sLnYxLkVycm9ySAOIAQEaoAEKDVJlc3BvbnNlU2hhcGUSKAoEdGV4dBgBIAEoCzIYLmFua2thLnByb3RvY29sLnYxLkVtcHR5SAASPwoEanNvbhgCIAEoCzIvLmFua2thLnByb3RvY29sLnYxLkFnZW50UGxhbi5SZXNwb25zZVNoYXBlLkpzb25IABobCgRKc29uEhMKC3NjaGVtYV9oaW50GAEgASgJQgcKBXNoYXBlIh8KBk1lbW9yeRILCgdTRVNTSU9OEAASCAoETk9ORRABQggKBl9tb2RlbEIJCgdfc3lzdGVtQgcKBV91c2VyQgoKCF9mYWlsdXJlIl0KC1Rvb2xSZXF1ZXN0EhQKDGNvbXBvbmVudF9pZBgBIAEoCRISCgpzZXNzaW9uX2lkGAIgASgJEgwKBHRvb2wYAyABKAkSFgoOYXJndW1lbnRzX2pzb24YBCABKAkiNQoKVG9vbFJlc3VsdBIMCgJvaxgBIAEoCUgAEg8KBWVycm9yGAIgASgJSABCCAoGcmVzdWx0IrcBChBHdWFyZHJhaWxSZXF1ZXN0EhQKDGNvbXBvbmVudF9pZBgBIAEoCRISCgpzZXNzaW9uX2lkGAIgASgJEhEKCWd1YXJkcmFpbBgDIAEoCRI4CgVzdGFnZRgEIAEoDjIpLmFua2thLnByb3RvY29sLnYxLkd1YXJkcmFpbFJlcXVlc3QuU3RhZ2USDAoEdGV4dBgFIAEoCSIeCgVTdGFnZRIJCgVJTlBVVBAAEgoKBk9VVFBVVBABIlYKD0d1YXJkcmFpbFJlc3VsdBIoCgRwYXNzGAEgASgLMhguYW5ra2EucHJvdG9jb2wudjEuRW1wdHlIABIPCgVibG9jaxgCIAEoCUgAQggKBnJlc3VsdDL1AQoFQWdlbnQSRAoEUGxhbhIeLmFua2thLnByb3RvY29sLnYxLlBsYW5SZXF1ZXN0GhwuYW5ra2EucHJvdG9jb2wudjEuUGxhblJlcGx5EksKCkludm9rZVRvb2wSHi5hbmtrYS5wcm90b2NvbC52MS5Ub29sUmVxdWVzdBodLmFua2thLnByb3RvY29sLnYxLlRvb2xSZXN1bHQSWQoOQ2hlY2tHdWFyZHJhaWwSIy5hbmtrYS5wcm90b2NvbC52MS5HdWFyZHJhaWxSZXF1ZXN0GiIuYW5ra2EucHJvdG9jb2wudjEuR3VhcmRyYWlsUmVzdWx0YgZwcm90bzM", [file_ankka_protocol_v1_payload]);
+/**
+ * Describes the message ankka.protocol.v1.PlanRequest.
+ * Use `create(PlanRequestSchema)` to create a new message.
+ */
+export const PlanRequestSchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_agent, 0);
+/**
+ * Describes the message ankka.protocol.v1.PlanReply.
+ * Use `create(PlanReplySchema)` to create a new message.
+ */
+export const PlanReplySchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_agent, 1);
+/**
+ * Describes the message ankka.protocol.v1.AgentPlan.
+ * Use `create(AgentPlanSchema)` to create a new message.
+ */
+export const AgentPlanSchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_agent, 2);
+/**
+ * Describes the message ankka.protocol.v1.AgentPlan.ResponseShape.
+ * Use `create(AgentPlan_ResponseShapeSchema)` to create a new message.
+ */
+export const AgentPlan_ResponseShapeSchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_agent, 2, 0);
+/**
+ * Describes the message ankka.protocol.v1.AgentPlan.ResponseShape.Json.
+ * Use `create(AgentPlan_ResponseShape_JsonSchema)` to create a new message.
+ */
+export const AgentPlan_ResponseShape_JsonSchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_agent, 2, 0, 0);
+/**
+ * @generated from enum ankka.protocol.v1.AgentPlan.Memory
+ */
+export const AgentPlan_Memory = {
+    /**
+     * @generated from enum value: SESSION = 0;
+     */
+    SESSION: 0,
+    /**
+     * @generated from enum value: NONE = 1;
+     */
+    NONE: 1,
+};
+/**
+ * Describes the enum ankka.protocol.v1.AgentPlan.Memory.
+ */
+export const AgentPlan_MemorySchema = /*@__PURE__*/ enumDesc(file_ankka_protocol_v1_agent, 2, 0);
+/**
+ * Describes the message ankka.protocol.v1.ToolRequest.
+ * Use `create(ToolRequestSchema)` to create a new message.
+ */
+export const ToolRequestSchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_agent, 3);
+/**
+ * Describes the message ankka.protocol.v1.ToolResult.
+ * Use `create(ToolResultSchema)` to create a new message.
+ */
+export const ToolResultSchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_agent, 4);
+/**
+ * Describes the message ankka.protocol.v1.GuardrailRequest.
+ * Use `create(GuardrailRequestSchema)` to create a new message.
+ */
+export const GuardrailRequestSchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_agent, 5);
+/**
+ * @generated from enum ankka.protocol.v1.GuardrailRequest.Stage
+ */
+export const GuardrailRequest_Stage = {
+    /**
+     * @generated from enum value: INPUT = 0;
+     */
+    INPUT: 0,
+    /**
+     * @generated from enum value: OUTPUT = 1;
+     */
+    OUTPUT: 1,
+};
+/**
+ * Describes the enum ankka.protocol.v1.GuardrailRequest.Stage.
+ */
+export const GuardrailRequest_StageSchema = /*@__PURE__*/ enumDesc(file_ankka_protocol_v1_agent, 5, 0);
+/**
+ * Describes the message ankka.protocol.v1.GuardrailResult.
+ * Use `create(GuardrailResultSchema)` to create a new message.
+ */
+export const GuardrailResultSchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_agent, 6);
+/**
+ * @generated from service ankka.protocol.v1.Agent
+ */
+export const Agent = /*@__PURE__*/ serviceDesc(file_ankka_protocol_v1_agent, 0);