@jsm-mit/agent-platform-canister-package 0.0.1

package/README.md

@@ -0,0 +1,133 @@
+# Agent Platform Canister Package
+
+A TypeScript library for interacting with the `agent-platform-canister` canister
+on the Internet Computer — agent configs (base fields + freeform custom JSON)
+and batched chat history for the agent platform. The wrapper is the only
+sanctioned way to talk to the canister: it hides `HttpAgent`/`idlFactory`
+wiring, unwraps the canister's `Framework.Result<T>` into "resolves with `T`
+or throws a known `Error`", and converts candid `opt`/`variant`/`Principal`
+shapes into idiomatic TypeScript.
+
+Part of `workspace-agent-platform`; the canister itself lives in the sibling
+`../agent-platform-canister`. Concept/architecture design lives in
+`~/workspace-jsm-company/jsm-ideas/agent-platform/`.
+
+## Installation
+
+```bash
+npm install @jsm-mit/agent-platform-canister-package
+```
+
+## Usage
+
+### Initialization
+
+```typescript
+import {
+    AgentConfigsActor,
+    ChatHistoryActor,
+    AdminActor,
+} from "@jsm-mit/agent-platform-canister-package";
+
+const canisterId = "your-canister-id";
+const agentConfigsActor = new AgentConfigsActor(canisterId, identity); // identity optional
+const chatHistoryActor = new ChatHistoryActor(canisterId, identity);
+const adminActor = new AdminActor(canisterId, identity);
+```
+
+### Permissions model
+
+Everything is admin-gated. A fresh canister has no admins — the first caller
+of `adminActor.registerAsAdminAsyncUnsafe()` claims the role (e.g.
+agents-village's own service identity); further admins via
+`addAdminAsyncUnsafe`.
+
+### Agent configs
+
+```typescript
+const config = await agentConfigsActor.upsertAgentConfigAsyncUnsafe({
+    id: "kasia",
+    name: "Kasia",
+    persona: "Jesteś Kasią, sprzedawczynią mebli...",
+    disclosesAsAi: false,
+    // tools defaults to [] when omitted (a tool-less agent); customConfigJson too is
+    // an optional escape hatch, JSON-encoded.
+    tools: [
+        { tool: "check_availability", paramsJson: '{"serviceId":"sultana"}' },
+    ],
+});
+// Same call again with the same id updates in place — createdAt is preserved.
+
+const fetched = await agentConfigsActor.getAgentConfigAsyncUnsafe("kasia");
+const all = await agentConfigsActor.listAgentConfigsAsyncUnsafe(500);
+await agentConfigsActor.deleteAgentConfigAsyncUnsafe("kasia");
+```
+
+### Chat history — batched, mixed conversations/agents per call
+
+A single flush from agents-village can mix entries from many conversations
+and agents — that's the whole point of flushing a buffer as one call rather
+than one call per message (AGENT-PLATFORM decision 2026-08-18). Any entry
+naming an unknown `agentId` refuses the _whole_ batch.
+
+```typescript
+await chatHistoryActor.appendMessageBatchAsyncUnsafe([
+    {
+        conversationId: "conv-1",
+        agentId: "kasia",
+        message: { role: "user", content: "hi", timestamp: 0n },
+    },
+    {
+        conversationId: "conv-2",
+        agentId: "lilly",
+        message: { role: "user", content: "hey", timestamp: 0n },
+    },
+]);
+
+const history = await chatHistoryActor.getConversationHistoryAsyncUnsafe(
+    "conv-1",
+    100,
+);
+```
+
+## Error model
+
+Every `...AsyncUnsafe` method throws one of exactly three errors — switch on
+`error.message`, details are always on `error.cause`:
+
+- `CanisterError` — the canister returned a business `#err`;
+  `cause = { errorKey, errorMessage, logs }` (e.g. `errorKey: "NotAuthorized"`,
+  `"NotFound"`, `"InvalidData"`).
+- `CriticalCanisterError` — transport failure or a canister trap;
+  `cause = { logs, rawError }`.
+- `CallRefusedAtInspectionStage` — the canister's `inspect` gate refused the
+  call before execution (oversized payload or anonymous caller).
+
+## API
+
+- `AgentConfigsActor` — `upsertAgentConfigAsyncUnsafe`, `getAgentConfigAsyncUnsafe`,
+  `listAgentConfigsAsyncUnsafe`, `deleteAgentConfigAsyncUnsafe`.
+- `ChatHistoryActor` — `appendMessageBatchAsyncUnsafe`, `getConversationHistoryAsyncUnsafe`.
+- `AdminActor` — admin allowlist and diagnostics: `registerAsAdminAsyncUnsafe`,
+  `addAdminAsyncUnsafe`, `removeAdminAsyncUnsafe`, `getAdminsAsyncUnsafe`,
+  `setLoggingEnabledAsyncUnsafe`, `whoAmIAsyncUnsafe`, `getLogsAsyncUnsafe`,
+  `clearLogsAsyncUnsafe`.
+- Configs/messages are returned as `AgentConfigView`/`ChatMessageView` (opts
+  flattened to optionals, the message role variant as a
+  `"user" | "assistant" | "tool"` string union); raw candid types remain
+  available from `.` and `./declarations/*` exports.
+
+## Development
+
+See `CLAUDE.md` for the canister-change workflow (declarations sync, wrapper
+updates) and the integration-test policy (`npm run test-suite` runs against a
+real mainnet test canister — human-run only).
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5+
+
+## License
+
+ISC

package/declarations/agent-platform-canister/agent-platform-canister.did

@@ -0,0 +1,120 @@
+type UpsertAgentConfigArgs = 
+ record {
+   customConfigJson: opt text;
+   disclosesAsAi: bool;
+   id: AgentId;
+   name: text;
+   persona: text;
+   tools: vec ToolBinding;
+ };
+type ToolBinding = 
+ record {
+   paramsJson: text;
+   tool: text;
+ };
+type Result_6 = 
+ variant {
+   err: Error;
+   ok;
+ };
+type Result_5 = 
+ variant {
+   err: Error;
+   ok: vec principal;
+ };
+type Result_4 = 
+ variant {
+   err: Error;
+   ok: vec ChatMessage;
+ };
+type Result_3 = 
+ variant {
+   err: Error;
+   ok: vec AgentConfig;
+ };
+type Result_2 = 
+ variant {
+   err: Error;
+   ok: principal;
+ };
+type Result_1 = 
+ variant {
+   err: Error;
+   ok: bool;
+ };
+type Result = 
+ variant {
+   err: Error;
+   ok: AgentConfig;
+ };
+type MessageBatchEntry = 
+ record {
+   agentId: AgentId;
+   conversationId: ConversationId;
+   message: ChatMessage;
+ };
+type GetConversationHistoryArgs = 
+ record {
+   conversationId: ConversationId;
+   limit: nat;
+ };
+type ErrorDetails = 
+ variant {
+   AlreadyExists;
+   InterCanisterConnectionError;
+   InvalidData: text;
+   NotAuthorized: text;
+   NotFound;
+   RemoteCanisterError: text;
+   ReturnsNull;
+ };
+type Error = 
+ record {
+   details: ErrorDetails;
+   logsJson: text;
+ };
+type ConversationId = text;
+type ChatMessageRole = 
+ variant {
+   assistant;
+   tool;
+   user;
+ };
+type ChatMessage = 
+ record {
+   content: text;
+   role: ChatMessageRole;
+   timestamp: int;
+   toolCallId: opt text;
+   toolName: opt text;
+ };
+type AppendMessageBatchArgs = record {entries: vec MessageBatchEntry;};
+type AgentId = text;
+type AgentConfig = 
+ record {
+   createdAt: int;
+   customConfigJson: opt text;
+   disclosesAsAi: bool;
+   id: AgentId;
+   name: text;
+   persona: text;
+   tools: vec ToolBinding;
+   updatedAt: int;
+ };
+service : {
+  addAdmin: ("principal": principal) -> (Result_1);
+  appendMessageBatch: (args: AppendMessageBatchArgs) -> (Result_6);
+  clearLogs: () -> ();
+  deleteAgentConfig: (id: AgentId) -> (Result_6);
+  getAdmins: () -> (Result_5) query;
+  getAgentConfig: (id: AgentId) -> (Result) query;
+  getConversationHistory: (args: GetConversationHistoryArgs) ->
+   (Result_4) query;
+  getLogs: () -> (text) query;
+  listAgentConfigs: (limit: nat) -> (Result_3) query;
+  registerAsAdmin: () -> (Result_2);
+  removeAdmin: ("principal": principal) -> (Result_1);
+  setLoggingEnabled: (enabled: bool) -> (Result_1);
+  upsertAgentConfig: (args: UpsertAgentConfigArgs) -> (Result);
+  whoAmI: () -> (principal) query;
+}

package/declarations/agent-platform-canister/agent-platform-canister.did.d.ts

@@ -0,0 +1,86 @@
+import type { Principal } from "@icp-sdk/core/principal";
+import type { ActorMethod } from "@icp-sdk/core/agent";
+import type { IDL } from "@icp-sdk/core/candid";
+
+export interface AgentConfig {
+    id: AgentId;
+    tools: Array<ToolBinding>;
+    name: string;
+    createdAt: bigint;
+    updatedAt: bigint;
+    persona: string;
+    disclosesAsAi: boolean;
+    customConfigJson: [] | [string];
+}
+export type AgentId = string;
+export interface AppendMessageBatchArgs {
+    entries: Array<MessageBatchEntry>;
+}
+export interface ChatMessage {
+    content: string;
+    role: ChatMessageRole;
+    timestamp: bigint;
+    toolName: [] | [string];
+    toolCallId: [] | [string];
+}
+export type ChatMessageRole =
+    { tool: null } | { user: null } | { assistant: null };
+export type ConversationId = string;
+export interface Error {
+    details: ErrorDetails;
+    logsJson: string;
+}
+export type ErrorDetails =
+    | { InterCanisterConnectionError: null }
+    | { RemoteCanisterError: string }
+    | { NotFound: null }
+    | { NotAuthorized: string }
+    | { InvalidData: string }
+    | { AlreadyExists: null }
+    | { ReturnsNull: null };
+export interface GetConversationHistoryArgs {
+    limit: bigint;
+    conversationId: ConversationId;
+}
+export interface MessageBatchEntry {
+    agentId: AgentId;
+    conversationId: ConversationId;
+    message: ChatMessage;
+}
+export type Result = { ok: AgentConfig } | { err: Error };
+export type Result_1 = { ok: boolean } | { err: Error };
+export type Result_2 = { ok: Principal } | { err: Error };
+export type Result_3 = { ok: Array<AgentConfig> } | { err: Error };
+export type Result_4 = { ok: Array<ChatMessage> } | { err: Error };
+export type Result_5 = { ok: Array<Principal> } | { err: Error };
+export type Result_6 = { ok: null } | { err: Error };
+export interface ToolBinding {
+    paramsJson: string;
+    tool: string;
+}
+export interface UpsertAgentConfigArgs {
+    id: AgentId;
+    tools: Array<ToolBinding>;
+    name: string;
+    persona: string;
+    disclosesAsAi: boolean;
+    customConfigJson: [] | [string];
+}
+export interface _SERVICE {
+    addAdmin: ActorMethod<[Principal], Result_1>;
+    appendMessageBatch: ActorMethod<[AppendMessageBatchArgs], Result_6>;
+    clearLogs: ActorMethod<[], undefined>;
+    deleteAgentConfig: ActorMethod<[AgentId], Result_6>;
+    getAdmins: ActorMethod<[], Result_5>;
+    getAgentConfig: ActorMethod<[AgentId], Result>;
+    getConversationHistory: ActorMethod<[GetConversationHistoryArgs], Result_4>;
+    getLogs: ActorMethod<[], string>;
+    listAgentConfigs: ActorMethod<[bigint], Result_3>;
+    registerAsAdmin: ActorMethod<[], Result_2>;
+    removeAdmin: ActorMethod<[Principal], Result_1>;
+    setLoggingEnabled: ActorMethod<[boolean], Result_1>;
+    upsertAgentConfig: ActorMethod<[UpsertAgentConfigArgs], Result>;
+    whoAmI: ActorMethod<[], Principal>;
+}
+export declare const idlFactory: IDL.InterfaceFactory;
+export declare const init: (args: { IDL: typeof IDL }) => IDL.Type[];

package/declarations/agent-platform-canister/agent-platform-canister.did.js

@@ -0,0 +1,93 @@
+export const idlFactory = ({ IDL }) => {
+    const ErrorDetails = IDL.Variant({
+        InterCanisterConnectionError: IDL.Null,
+        RemoteCanisterError: IDL.Text,
+        NotFound: IDL.Null,
+        NotAuthorized: IDL.Text,
+        InvalidData: IDL.Text,
+        AlreadyExists: IDL.Null,
+        ReturnsNull: IDL.Null,
+    });
+    const Error = IDL.Record({ details: ErrorDetails, logsJson: IDL.Text });
+    const Result_1 = IDL.Variant({ ok: IDL.Bool, err: Error });
+    const AgentId = IDL.Text;
+    const ConversationId = IDL.Text;
+    const ChatMessageRole = IDL.Variant({
+        tool: IDL.Null,
+        user: IDL.Null,
+        assistant: IDL.Null,
+    });
+    const ChatMessage = IDL.Record({
+        content: IDL.Text,
+        role: ChatMessageRole,
+        timestamp: IDL.Int,
+        toolName: IDL.Opt(IDL.Text),
+        toolCallId: IDL.Opt(IDL.Text),
+    });
+    const MessageBatchEntry = IDL.Record({
+        agentId: AgentId,
+        conversationId: ConversationId,
+        message: ChatMessage,
+    });
+    const AppendMessageBatchArgs = IDL.Record({
+        entries: IDL.Vec(MessageBatchEntry),
+    });
+    const Result_6 = IDL.Variant({ ok: IDL.Null, err: Error });
+    const Result_5 = IDL.Variant({
+        ok: IDL.Vec(IDL.Principal),
+        err: Error,
+    });
+    const ToolBinding = IDL.Record({
+        paramsJson: IDL.Text,
+        tool: IDL.Text,
+    });
+    const AgentConfig = IDL.Record({
+        id: AgentId,
+        tools: IDL.Vec(ToolBinding),
+        name: IDL.Text,
+        createdAt: IDL.Int,
+        updatedAt: IDL.Int,
+        persona: IDL.Text,
+        disclosesAsAi: IDL.Bool,
+        customConfigJson: IDL.Opt(IDL.Text),
+    });
+    const Result = IDL.Variant({ ok: AgentConfig, err: Error });
+    const GetConversationHistoryArgs = IDL.Record({
+        limit: IDL.Nat,
+        conversationId: ConversationId,
+    });
+    const Result_4 = IDL.Variant({ ok: IDL.Vec(ChatMessage), err: Error });
+    const Result_3 = IDL.Variant({ ok: IDL.Vec(AgentConfig), err: Error });
+    const Result_2 = IDL.Variant({ ok: IDL.Principal, err: Error });
+    const UpsertAgentConfigArgs = IDL.Record({
+        id: AgentId,
+        tools: IDL.Vec(ToolBinding),
+        name: IDL.Text,
+        persona: IDL.Text,
+        disclosesAsAi: IDL.Bool,
+        customConfigJson: IDL.Opt(IDL.Text),
+    });
+    return IDL.Service({
+        addAdmin: IDL.Func([IDL.Principal], [Result_1], []),
+        appendMessageBatch: IDL.Func([AppendMessageBatchArgs], [Result_6], []),
+        clearLogs: IDL.Func([], [], []),
+        deleteAgentConfig: IDL.Func([AgentId], [Result_6], []),
+        getAdmins: IDL.Func([], [Result_5], ["query"]),
+        getAgentConfig: IDL.Func([AgentId], [Result], ["query"]),
+        getConversationHistory: IDL.Func(
+            [GetConversationHistoryArgs],
+            [Result_4],
+            ["query"],
+        ),
+        getLogs: IDL.Func([], [IDL.Text], ["query"]),
+        listAgentConfigs: IDL.Func([IDL.Nat], [Result_3], ["query"]),
+        registerAsAdmin: IDL.Func([], [Result_2], []),
+        removeAdmin: IDL.Func([IDL.Principal], [Result_1], []),
+        setLoggingEnabled: IDL.Func([IDL.Bool], [Result_1], []),
+        upsertAgentConfig: IDL.Func([UpsertAgentConfigArgs], [Result], []),
+        whoAmI: IDL.Func([], [IDL.Principal], ["query"]),
+    });
+};
+export const init = ({ IDL }) => {
+    return [];
+};

package/dist/actor-base.d.ts

@@ -0,0 +1,48 @@
+import { type ActorSubclass, HttpAgent, type Identity } from "@icp-sdk/core/agent";
+import type { _SERVICE, Error as ErrorFromCanister } from "../declarations/agent-platform-canister/agent-platform-canister.did.js";
+export interface LogEntry {
+    id: number;
+    message: string;
+}
+/**
+ * Base class for every per-domain actor wrapper (AgentConfigsActor,
+ * ChatHistoryActor, AdminActor). Builds the HttpAgent + raw candid actor and
+ * owns the single choke point that turns the canister's Framework.Result<T>
+ * into idiomatic TS:
+ * - `{ok: T}` resolves with `T` directly.
+ * - `{err: ...}` is thrown as `Error("CanisterError", { cause: {errorKey, errorMessage, logs} })`.
+ * - An `inspect()`-stage rejection is thrown as `Error("CallRefusedAtInspectionStage")`.
+ * - Any other transport failure is thrown as `Error("CriticalCanisterError")`.
+ */
+export declare class ActorBase {
+    protected canisterId: string;
+    protected identity?: Identity | undefined;
+    protected actor: ActorSubclass<_SERVICE>;
+    protected agent: HttpAgent;
+    constructor(canisterId: string, identity?: Identity | undefined);
+    private initAgentAndActor;
+    /**
+     * Rebuilds the HttpAgent and the actor from scratch. Useful for a long-lived
+     * consumer after a prolonged streak of failed calls, where a stale
+     * agent/connection is the usual suspect. Safe to call at any time.
+     */
+    reinitializeAgent(): void;
+    protected executeFunctionAsyncUnsafe<T>(fnAsync: () => Promise<{
+        ok: T;
+    } | {
+        err: ErrorFromCanister;
+    }>): Promise<T>;
+    /**
+     * For the few diagnostic methods that do NOT return a Framework.Result (whoAmI,
+     * getLogs, clearLogs) — only the transport-level error translation applies.
+     */
+    protected executeRawAsyncUnsafe<T>(fnAsync: () => Promise<T>): Promise<T>;
+    protected handleResultErrors(errorFromCanister: ErrorFromCanister): {
+        errorKey: string;
+        errorMessage: any;
+        logs: LogEntry[];
+    };
+    protected isInspectionRejection(error: any): boolean;
+    protected extractLogsFromError(error: any): LogEntry[] | null;
+}
+//# sourceMappingURL=actor-base.d.ts.map

package/dist/actor-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-base.d.ts","sourceRoot":"","sources":["../src/actor-base.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,aAAa,EAClB,SAAS,EACT,KAAK,QAAQ,EAEhB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACR,QAAQ,EACR,KAAK,IAAI,iBAAiB,EAC7B,MAAM,wEAAwE,CAAC;AAGhF,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,qBAAa,SAAS;IAKd,SAAS,CAAC,UAAU,EAAE,MAAM;IAC5B,SAAS,CAAC,QAAQ,CAAC,EAAE,QAAQ;IALjC,SAAS,CAAC,KAAK,EAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC1C,SAAS,CAAC,KAAK,EAAG,SAAS,CAAC;gBAGd,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,QAAQ,YAAA;IAKjC,OAAO,CAAC,iBAAiB;IAWzB;;;;OAIG;IACI,iBAAiB,IAAI,IAAI;cAIhB,0BAA0B,CAAC,CAAC,EACxC,OAAO,EAAE,MAAM,OAAO,CAAC;QAAE,EAAE,EAAE,CAAC,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,iBAAiB,CAAA;KAAE,CAAC,GAC/D,OAAO,CAAC,CAAC,CAAC;IAuCb;;;OAGG;cACa,qBAAqB,CAAC,CAAC,EACnC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC;IAab,SAAS,CAAC,kBAAkB,CAAC,iBAAiB,EAAE,iBAAiB;;;;;IAqBjE,SAAS,CAAC,qBAAqB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;IAWpD,SAAS,CAAC,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,QAAQ,EAAE,GAAG,IAAI;CAyBhE"}

package/dist/actor-base.js

@@ -0,0 +1,133 @@
+import { HttpAgent, Actor, } from "@icp-sdk/core/agent";
+import { idlFactory } from "../declarations/agent-platform-canister/agent-platform-canister.did.js";
+import { BetterJSON } from "@jsm-mit/utils-package";
+/**
+ * Base class for every per-domain actor wrapper (AgentConfigsActor,
+ * ChatHistoryActor, AdminActor). Builds the HttpAgent + raw candid actor and
+ * owns the single choke point that turns the canister's Framework.Result<T>
+ * into idiomatic TS:
+ * - `{ok: T}` resolves with `T` directly.
+ * - `{err: ...}` is thrown as `Error("CanisterError", { cause: {errorKey, errorMessage, logs} })`.
+ * - An `inspect()`-stage rejection is thrown as `Error("CallRefusedAtInspectionStage")`.
+ * - Any other transport failure is thrown as `Error("CriticalCanisterError")`.
+ */
+export class ActorBase {
+    canisterId;
+    identity;
+    actor;
+    agent;
+    constructor(canisterId, identity) {
+        this.canisterId = canisterId;
+        this.identity = identity;
+        this.initAgentAndActor();
+    }
+    initAgentAndActor() {
+        this.agent = HttpAgent.createSync({
+            host: "https://icp0.io",
+            identity: this.identity,
+        });
+        this.actor = Actor.createActor(idlFactory, {
+            agent: this.agent,
+            canisterId: this.canisterId,
+        });
+    }
+    /**
+     * Rebuilds the HttpAgent and the actor from scratch. Useful for a long-lived
+     * consumer after a prolonged streak of failed calls, where a stale
+     * agent/connection is the usual suspect. Safe to call at any time.
+     */
+    reinitializeAgent() {
+        this.initAgentAndActor();
+    }
+    async executeFunctionAsyncUnsafe(fnAsync) {
+        let errorObj = {};
+        try {
+            const result = await fnAsync();
+            if ("ok" in result) {
+                return result.ok;
+            }
+            errorObj = this.handleResultErrors(result.err);
+        }
+        catch (err) {
+            // The canister's `system func inspect` rejected the call before it was ever
+            // decoded or executed (oversized payload or anonymous caller). This is a
+            // transport-level IC reject, not a decoded Framework.Result — there's never any
+            // Framework log to extract, and it's not a real "canister unreachable/crashed"
+            // scenario either, so it gets its own distinct error.
+            if (this.isInspectionRejection(err)) {
+                throw new Error("CallRefusedAtInspectionStage", { cause: err });
+            }
+            // No console output here — whatever was extractable is passed forward on `cause`
+            // instead, so callers can inspect it themselves rather than it only ever being
+            // printed and lost.
+            const logs = this.extractLogsFromError(err);
+            throw new Error("CriticalCanisterError", {
+                cause: { logs, rawError: err },
+            });
+        }
+        if (errorObj) {
+            throw new Error("CanisterError", { cause: errorObj });
+        }
+        else {
+            throw new Error("UnreachableCodeError", {
+                cause: "Reached a code path that should be unreachable after error handling. Location Id: APCPA",
+            });
+        }
+    }
+    /**
+     * For the few diagnostic methods that do NOT return a Framework.Result (whoAmI,
+     * getLogs, clearLogs) — only the transport-level error translation applies.
+     */
+    async executeRawAsyncUnsafe(fnAsync) {
+        try {
+            return await fnAsync();
+        }
+        catch (err) {
+            if (this.isInspectionRejection(err)) {
+                throw new Error("CallRefusedAtInspectionStage", { cause: err });
+            }
+            throw new Error("CriticalCanisterError", {
+                cause: { logs: null, rawError: err },
+            });
+        }
+    }
+    handleResultErrors(errorFromCanister) {
+        const logs = BetterJSON.parse(errorFromCanister.logsJson, false);
+        const error = errorFromCanister.details;
+        const errorKey = Object.keys(error)[0];
+        const errorMessage = error[errorKey];
+        return {
+            errorKey: errorKey.toString(),
+            errorMessage,
+            logs,
+        };
+    }
+    // True if `error` is an IC transport-level reject caused by `system func inspect`
+    // returning false (`canister_inspect_message explicitly refused message`, IC0503).
+    // This text is a fixed IC/Motoko runtime message — it does not vary by which inspect
+    // check failed.
+    isInspectionRejection(error) {
+        const rejectText = error?.cause?.code?.rejectMessage || error?.message || "";
+        return rejectText.includes("canister_inspect_message explicitly refused message");
+    }
+    // On a trap, Logs.interrupt appends the request's log trail as a JSON array to the
+    // reject message — best-effort recovery of that array from the raw reject text.
+    extractLogsFromError(error) {
+        try {
+            const rejectMessage = error?.cause?.code?.rejectMessage || error?.message || "";
+            if (!rejectMessage)
+                return null;
+            const jsonStartIdx = rejectMessage.indexOf("[{");
+            const jsonEndIdx = rejectMessage.lastIndexOf("}]");
+            if (jsonStartIdx === -1 || jsonEndIdx === -1) {
+                return null;
+            }
+            const rawJson = rejectMessage.substring(jsonStartIdx, jsonEndIdx + 2);
+            const logs = JSON.parse(rawJson);
+            return logs;
+        }
+        catch (e) {
+            return null;
+        }
+    }
+}

package/dist/actors/admin-actor.d.ts

@@ -0,0 +1,75 @@
+import { type Identity } from "@icp-sdk/core/agent";
+import { ActorBase, type LogEntry } from "../actor-base.js";
+/** 1:1 wrapper for the canister's AdminController plus the diagnostic endpoints
+ * (whoAmI, getLogs, clearLogs). */
+export declare class AdminActor extends ActorBase {
+    constructor(canisterId: string, identity?: Identity);
+    /**
+     * The principal the canister sees for this wrapper's identity — diagnostic endpoint,
+     * open to any caller.
+     * @returns The caller principal as text.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution (anonymous caller).
+     */
+    whoAmIAsyncUnsafe(): Promise<string>;
+    /**
+     * Leftover log entries on the canister (logs are cleared per request by the canister's
+     * ok/err helpers, so this only ever shows remnants of calls that bypassed them) —
+     * diagnostic endpoint, open to any caller.
+     * @returns The parsed log entries.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution (anonymous caller).
+     */
+    getLogsAsyncUnsafe(): Promise<LogEntry[]>;
+    /**
+     * Clears the canister's leftover log buffer — diagnostic endpoint, open to any caller.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution (anonymous caller).
+     */
+    clearLogsAsyncUnsafe(): Promise<void>;
+    /**
+     * Adds a principal to the admin allowlist. Admin only.
+     * @param principalText - The principal (text form) to whitelist.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, errorKey `AlreadyExists`, anonymous principal). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    addAdminAsyncUnsafe(principalText: string): Promise<boolean>;
+    /**
+     * Removes a principal from the admin allowlist. Admin only; removing the last admin is
+     * refused.
+     * @param principalText - The principal (text form) to remove.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, errorKey `NotFound`, last admin). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    removeAdminAsyncUnsafe(principalText: string): Promise<boolean>;
+    /**
+     * The current admin allowlist. Admin only.
+     * @returns Principals in text form.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    getAdminsAsyncUnsafe(): Promise<string[]>;
+    /**
+     * Bootstrap: succeeds only while the canister has NO admin at all — the first caller
+     * claims the admin role. Once any admin exists this always refuses; further admins
+     * are added via addAdminAsyncUnsafe.
+     * @returns The registered admin principal (the caller) as text.
+     * @throws Error with message `CanisterError` when the canister returns a business error (errorKey `NotAuthorized` once an admin is already registered). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution (anonymous caller).
+     */
+    registerAsAdminAsyncUnsafe(): Promise<string>;
+    /**
+     * Toggles the canister's request logging (kill switch for production). Admin only.
+     * @param enabled - The new logging state.
+     * @returns The committed state.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    setLoggingEnabledAsyncUnsafe(enabled: boolean): Promise<boolean>;
+}
+//# sourceMappingURL=admin-actor.d.ts.map

package/dist/actors/admin-actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-actor.d.ts","sourceRoot":"","sources":["../../src/actors/admin-actor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5D;mCACmC;AACnC,qBAAa,UAAW,SAAQ,SAAS;gBACzB,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ;IAInD;;;;;;OAMG;IACU,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAOjD;;;;;;;OAOG;IACU,kBAAkB,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAOtD;;;;OAIG;IACU,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlD;;;;;;OAMG;IACU,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMzE;;;;;;;OAOG;IACU,sBAAsB,CAC/B,aAAa,EAAE,MAAM,GACtB,OAAO,CAAC,OAAO,CAAC;IAMnB;;;;;;OAMG;IACU,oBAAoB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAOtD;;;;;;;;OAQG;IACU,0BAA0B,IAAI,OAAO,CAAC,MAAM,CAAC;IAO1D;;;;;;;OAOG;IACU,4BAA4B,CACrC,OAAO,EAAE,OAAO,GACjB,OAAO,CAAC,OAAO,CAAC;CAKtB"}

package/dist/actors/admin-actor.js

@@ -0,0 +1,98 @@
+import {} from "@icp-sdk/core/agent";
+import { Principal } from "@icp-sdk/core/principal";
+import { BetterJSON } from "@jsm-mit/utils-package";
+import { ActorBase } from "../actor-base.js";
+/** 1:1 wrapper for the canister's AdminController plus the diagnostic endpoints
+ * (whoAmI, getLogs, clearLogs). */
+export class AdminActor extends ActorBase {
+    constructor(canisterId, identity) {
+        super(canisterId, identity);
+    }
+    /**
+     * The principal the canister sees for this wrapper's identity — diagnostic endpoint,
+     * open to any caller.
+     * @returns The caller principal as text.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution (anonymous caller).
+     */
+    async whoAmIAsyncUnsafe() {
+        const principal = await this.executeRawAsyncUnsafe(() => this.actor.whoAmI());
+        return principal.toText();
+    }
+    /**
+     * Leftover log entries on the canister (logs are cleared per request by the canister's
+     * ok/err helpers, so this only ever shows remnants of calls that bypassed them) —
+     * diagnostic endpoint, open to any caller.
+     * @returns The parsed log entries.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution (anonymous caller).
+     */
+    async getLogsAsyncUnsafe() {
+        const logsJson = await this.executeRawAsyncUnsafe(() => this.actor.getLogs());
+        return BetterJSON.parse(logsJson, false) ?? [];
+    }
+    /**
+     * Clears the canister's leftover log buffer — diagnostic endpoint, open to any caller.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution (anonymous caller).
+     */
+    async clearLogsAsyncUnsafe() {
+        await this.executeRawAsyncUnsafe(() => this.actor.clearLogs());
+    }
+    /**
+     * Adds a principal to the admin allowlist. Admin only.
+     * @param principalText - The principal (text form) to whitelist.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, errorKey `AlreadyExists`, anonymous principal). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async addAdminAsyncUnsafe(principalText) {
+        return this.executeFunctionAsyncUnsafe(() => this.actor.addAdmin(Principal.fromText(principalText)));
+    }
+    /**
+     * Removes a principal from the admin allowlist. Admin only; removing the last admin is
+     * refused.
+     * @param principalText - The principal (text form) to remove.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, errorKey `NotFound`, last admin). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async removeAdminAsyncUnsafe(principalText) {
+        return this.executeFunctionAsyncUnsafe(() => this.actor.removeAdmin(Principal.fromText(principalText)));
+    }
+    /**
+     * The current admin allowlist. Admin only.
+     * @returns Principals in text form.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async getAdminsAsyncUnsafe() {
+        const principals = await this.executeFunctionAsyncUnsafe(() => this.actor.getAdmins());
+        return principals.map((p) => p.toText());
+    }
+    /**
+     * Bootstrap: succeeds only while the canister has NO admin at all — the first caller
+     * claims the admin role. Once any admin exists this always refuses; further admins
+     * are added via addAdminAsyncUnsafe.
+     * @returns The registered admin principal (the caller) as text.
+     * @throws Error with message `CanisterError` when the canister returns a business error (errorKey `NotAuthorized` once an admin is already registered). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution (anonymous caller).
+     */
+    async registerAsAdminAsyncUnsafe() {
+        const principal = await this.executeFunctionAsyncUnsafe(() => this.actor.registerAsAdmin());
+        return principal.toText();
+    }
+    /**
+     * Toggles the canister's request logging (kill switch for production). Admin only.
+     * @param enabled - The new logging state.
+     * @returns The committed state.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async setLoggingEnabledAsyncUnsafe(enabled) {
+        return this.executeFunctionAsyncUnsafe(() => this.actor.setLoggingEnabled(enabled));
+    }
+}

package/dist/actors/agent-configs-actor.d.ts

@@ -0,0 +1,44 @@
+import { type Identity } from "@icp-sdk/core/agent";
+import { ActorBase } from "../actor-base.js";
+import type { AgentConfigView, UpsertAgentConfigInput } from "../interfaces.js";
+/** 1:1 wrapper for the canister's AgentConfigsController. */
+export declare class AgentConfigsActor extends ActorBase {
+    constructor(canisterId: string, identity?: Identity);
+    /**
+     * Creates the config on first write, otherwise updates it in place —
+     * `createdAt` is preserved across an update. Admin only.
+     * @param input - The full desired config; `id` decides create-vs-update. `tools`
+     * defaults to [] (a tool-less agent) when omitted.
+     * @returns The stored config as it now stands.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, or `InvalidData` — a bounded field was too long/too many entries). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    upsertAgentConfigAsyncUnsafe(input: UpsertAgentConfigInput): Promise<AgentConfigView>;
+    /**
+     * Fetches one agent's config. Admin only.
+     * @param id - The agent id.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, errorKey `NotFound`). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    getAgentConfigAsyncUnsafe(id: string): Promise<AgentConfigView>;
+    /**
+     * Lists agent configs, most-recently-created last. Admin only.
+     * @param limit - Bounded server-side to `ChatHistoryController`/`AgentConfigsController`'s
+     * `MAX_LIST_LIMIT` (500) regardless of what's passed.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    listAgentConfigsAsyncUnsafe(limit: number): Promise<AgentConfigView[]>;
+    /**
+     * Deletes an agent's config. Admin only.
+     * @param id - The agent id.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, errorKey `NotFound`). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    deleteAgentConfigAsyncUnsafe(id: string): Promise<void>;
+}
+//# sourceMappingURL=agent-configs-actor.d.ts.map

package/dist/actors/agent-configs-actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-configs-actor.d.ts","sourceRoot":"","sources":["../../src/actors/agent-configs-actor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAGhF,6DAA6D;AAC7D,qBAAa,iBAAkB,SAAQ,SAAS;gBAChC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ;IAInD;;;;;;;;;OASG;IACU,4BAA4B,CACrC,KAAK,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC;IAc3B;;;;;;OAMG;IACU,yBAAyB,CAClC,EAAE,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,CAAC;IAO3B;;;;;;;OAOG;IACU,2BAA2B,CACpC,KAAK,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,EAAE,CAAC;IAO7B;;;;;;OAMG;IACU,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAKvE"}

package/dist/actors/agent-configs-actor.js

@@ -0,0 +1,63 @@
+import {} from "@icp-sdk/core/agent";
+import { ActorBase } from "../actor-base.js";
+import { mapAgentConfigView, toOpt } from "../mappers.js";
+/** 1:1 wrapper for the canister's AgentConfigsController. */
+export class AgentConfigsActor extends ActorBase {
+    constructor(canisterId, identity) {
+        super(canisterId, identity);
+    }
+    /**
+     * Creates the config on first write, otherwise updates it in place —
+     * `createdAt` is preserved across an update. Admin only.
+     * @param input - The full desired config; `id` decides create-vs-update. `tools`
+     * defaults to [] (a tool-less agent) when omitted.
+     * @returns The stored config as it now stands.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, or `InvalidData` — a bounded field was too long/too many entries). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async upsertAgentConfigAsyncUnsafe(input) {
+        const config = await this.executeFunctionAsyncUnsafe(() => this.actor.upsertAgentConfig({
+            id: input.id,
+            name: input.name,
+            persona: input.persona,
+            disclosesAsAi: input.disclosesAsAi,
+            tools: input.tools ?? [],
+            customConfigJson: toOpt(input.customConfigJson),
+        }));
+        return mapAgentConfigView(config);
+    }
+    /**
+     * Fetches one agent's config. Admin only.
+     * @param id - The agent id.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, errorKey `NotFound`). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async getAgentConfigAsyncUnsafe(id) {
+        const config = await this.executeFunctionAsyncUnsafe(() => this.actor.getAgentConfig(id));
+        return mapAgentConfigView(config);
+    }
+    /**
+     * Lists agent configs, most-recently-created last. Admin only.
+     * @param limit - Bounded server-side to `ChatHistoryController`/`AgentConfigsController`'s
+     * `MAX_LIST_LIMIT` (500) regardless of what's passed.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async listAgentConfigsAsyncUnsafe(limit) {
+        const configs = await this.executeFunctionAsyncUnsafe(() => this.actor.listAgentConfigs(BigInt(limit)));
+        return configs.map(mapAgentConfigView);
+    }
+    /**
+     * Deletes an agent's config. Admin only.
+     * @param id - The agent id.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, errorKey `NotFound`). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async deleteAgentConfigAsyncUnsafe(id) {
+        await this.executeFunctionAsyncUnsafe(() => this.actor.deleteAgentConfig(id));
+    }
+}

package/dist/actors/chat-history-actor.d.ts

@@ -0,0 +1,30 @@
+import { type Identity } from "@icp-sdk/core/agent";
+import { ActorBase } from "../actor-base.js";
+import type { ChatMessageView, MessageBatchEntryInput } from "../interfaces.js";
+/** 1:1 wrapper for the canister's ChatHistoryController. */
+export declare class ChatHistoryActor extends ActorBase {
+    constructor(canisterId: string, identity?: Identity);
+    /**
+     * Appends a batch of message entries — a single call can mix entries from many
+     * conversations and agents (that's the point of flushing a buffer as one call,
+     * see AGENT-PLATFORM decision 2026-08-18). Admin only; any entry naming an unknown
+     * `agentId` refuses the *whole* batch, not just that entry.
+     * @param entries - Each entry pairs a message with which conversation/agent it belongs to.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, errorKey `NotFound` for an unknown agentId, or `InvalidData` — batch/content too large). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    appendMessageBatchAsyncUnsafe(entries: MessageBatchEntryInput[]): Promise<void>;
+    /**
+     * Fetches the most recent `limit` messages of one conversation, oldest first — a
+     * query tool for admin/debugging, not the hot path (the live conversation state
+     * lives in agents-village's own memory). Admin only.
+     * @param conversationId - Which conversation to read.
+     * @param limit - Bounded server-side to `ChatHistoryController.MAX_HISTORY_QUERY_LIMIT` (500).
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    getConversationHistoryAsyncUnsafe(conversationId: string, limit: number): Promise<ChatMessageView[]>;
+}
+//# sourceMappingURL=chat-history-actor.d.ts.map

package/dist/actors/chat-history-actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-history-actor.d.ts","sourceRoot":"","sources":["../../src/actors/chat-history-actor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAOhF,4DAA4D;AAC5D,qBAAa,gBAAiB,SAAQ,SAAS;gBAC/B,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ;IAInD;;;;;;;;;OASG;IACU,6BAA6B,CACtC,OAAO,EAAE,sBAAsB,EAAE,GAClC,OAAO,CAAC,IAAI,CAAC;IAkBhB;;;;;;;;;OASG;IACU,iCAAiC,CAC1C,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,EAAE,CAAC;CAShC"}

package/dist/actors/chat-history-actor.js

@@ -0,0 +1,51 @@
+import {} from "@icp-sdk/core/agent";
+import { ActorBase } from "../actor-base.js";
+import { mapChatMessageView, toChatMessageRoleVariant, toOpt, } from "../mappers.js";
+/** 1:1 wrapper for the canister's ChatHistoryController. */
+export class ChatHistoryActor extends ActorBase {
+    constructor(canisterId, identity) {
+        super(canisterId, identity);
+    }
+    /**
+     * Appends a batch of message entries — a single call can mix entries from many
+     * conversations and agents (that's the point of flushing a buffer as one call,
+     * see AGENT-PLATFORM decision 2026-08-18). Admin only; any entry naming an unknown
+     * `agentId` refuses the *whole* batch, not just that entry.
+     * @param entries - Each entry pairs a message with which conversation/agent it belongs to.
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized, errorKey `NotFound` for an unknown agentId, or `InvalidData` — batch/content too large). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async appendMessageBatchAsyncUnsafe(entries) {
+        await this.executeFunctionAsyncUnsafe(() => this.actor.appendMessageBatch({
+            entries: entries.map((entry) => ({
+                conversationId: entry.conversationId,
+                agentId: entry.agentId,
+                message: {
+                    role: toChatMessageRoleVariant(entry.message.role),
+                    content: entry.message.content,
+                    toolCallId: toOpt(entry.message.toolCallId),
+                    toolName: toOpt(entry.message.toolName),
+                    timestamp: entry.message.timestamp,
+                },
+            })),
+        }));
+    }
+    /**
+     * Fetches the most recent `limit` messages of one conversation, oldest first — a
+     * query tool for admin/debugging, not the hot path (the live conversation state
+     * lives in agents-village's own memory). Admin only.
+     * @param conversationId - Which conversation to read.
+     * @param limit - Bounded server-side to `ChatHistoryController.MAX_HISTORY_QUERY_LIMIT` (500).
+     * @throws Error with message `CanisterError` when the canister returns a business error (not authorized). Examine "cause" for {errorKey, errorMessage, logs}.
+     * @throws Error with message `CriticalCanisterError` when there is no communication with the canister or the canister code traps during execution.
+     * @throws Error with message `CallRefusedAtInspectionStage` when the canister's `inspect` rejects the call before execution.
+     */
+    async getConversationHistoryAsyncUnsafe(conversationId, limit) {
+        const messages = await this.executeFunctionAsyncUnsafe(() => this.actor.getConversationHistory({
+            conversationId,
+            limit: BigInt(limit),
+        }));
+        return messages.map(mapChatMessageView);
+    }
+}

package/dist/globals.d.ts

@@ -0,0 +1,2 @@
+export declare const componentName = "agent-platform-canister-package";
+//# sourceMappingURL=globals.d.ts.map

package/dist/globals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../src/globals.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,oCAAoC,CAAC"}

package/dist/globals.js

@@ -0,0 +1 @@
+export const componentName = "agent-platform-canister-package";

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { ActorBase, type LogEntry } from "./actor-base.js";
+export { AdminActor } from "./actors/admin-actor.js";
+export { AgentConfigsActor } from "./actors/agent-configs-actor.js";
+export { ChatHistoryActor } from "./actors/chat-history-actor.js";
+export type { ChatMessageRoleView, ChatMessageView, MessageBatchEntryInput, AgentConfigView, UpsertAgentConfigInput, } from "./interfaces.js";
+export { mapChatMessageRoleView, mapChatMessageView, mapAgentConfigView, } from "./mappers.js";
+export type { ToolBinding, Error as CanisterErrorShape, ErrorDetails, } from "../declarations/agent-platform-canister/agent-platform-canister.did.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,YAAY,EACR,mBAAmB,EACnB,eAAe,EACf,sBAAsB,EACtB,eAAe,EACf,sBAAsB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACH,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,GACrB,MAAM,cAAc,CAAC;AACtB,YAAY,EACR,WAAW,EACX,KAAK,IAAI,kBAAkB,EAC3B,YAAY,GACf,MAAM,wEAAwE,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { ActorBase } from "./actor-base.js";
+export { AdminActor } from "./actors/admin-actor.js";
+export { AgentConfigsActor } from "./actors/agent-configs-actor.js";
+export { ChatHistoryActor } from "./actors/chat-history-actor.js";
+export { mapChatMessageRoleView, mapChatMessageView, mapAgentConfigView, } from "./mappers.js";

package/dist/interfaces.d.ts

@@ -0,0 +1,58 @@
+export type ChatMessageRoleView = "user" | "assistant" | "tool";
+/** Candid `ChatMessage` with the role variant as a string union and opts flattened —
+ * matches chat-agent-package's own ChatMessage shape so history round-trips without
+ * further translation on the consumer side. */
+export interface ChatMessageView {
+    role: ChatMessageRoleView;
+    content: string;
+    toolCallId?: string;
+    toolName?: string;
+    /** Nanoseconds since epoch */
+    timestamp: bigint;
+}
+/** Input for ChatHistoryActor.appendMessageBatchAsyncUnsafe — role as a plain string,
+ * opts as plain optionals; the wrapper does the variant/opt shaping. */
+export interface MessageBatchEntryInput {
+    conversationId: string;
+    agentId: string;
+    message: {
+        role: ChatMessageRoleView;
+        content: string;
+        toolCallId?: string;
+        toolName?: string;
+        timestamp: bigint;
+    };
+}
+/** Candid `AgentConfig` with the opt flattened. */
+export interface AgentConfigView {
+    id: string;
+    name: string;
+    persona: string;
+    disclosesAsAi: boolean;
+    tools: {
+        tool: string;
+        paramsJson: string;
+    }[];
+    customConfigJson?: string;
+    /** Nanoseconds since epoch */
+    createdAt: bigint;
+    /** Nanoseconds since epoch */
+    updatedAt: bigint;
+}
+/** Input for AgentConfigsActor.upsertAgentConfigAsyncUnsafe — customConfigJson as a
+ * plain optional (candid `opt` shaping done by the wrapper); tools is optional here
+ * even though the canister's own UpsertAgentConfigArgs requires it — the wrapper
+ * defaults a missing tools to [] for a tool-less agent, so callers don't have to
+ * spell out `tools: []` every time. */
+export interface UpsertAgentConfigInput {
+    id: string;
+    name: string;
+    persona: string;
+    disclosesAsAi: boolean;
+    tools?: {
+        tool: string;
+        paramsJson: string;
+    }[];
+    customConfigJson?: string;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAEhE;;+CAE+C;AAC/C,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;wEACwE;AACxE,MAAM,WAAW,sBAAsB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE;QACL,IAAI,EAAE,mBAAmB,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAC;CACL;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;uCAIuC;AACvC,MAAM,WAAW,sBAAsB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B"}

package/dist/interfaces.js

@@ -0,0 +1,4 @@
+// Friendlier view types for the minority of candid shapes that don't map cleanly 1:1
+// (opt-heavy records, no-payload variants). Everything else is re-exported raw from the
+// declarations in index.ts.
+export {};

package/dist/mappers.d.ts

@@ -0,0 +1,9 @@
+import type { AgentConfig, ChatMessage, ChatMessageRole } from "../declarations/agent-platform-canister/agent-platform-canister.did.js";
+import type { ChatMessageRoleView, ChatMessageView, AgentConfigView } from "./interfaces.js";
+declare function toOpt<T>(value: T | undefined): [] | [T];
+export declare function mapChatMessageRoleView(role: ChatMessageRole): ChatMessageRoleView;
+export declare function toChatMessageRoleVariant(role: ChatMessageRoleView): ChatMessageRole;
+export declare function mapChatMessageView(message: ChatMessage): ChatMessageView;
+export declare function mapAgentConfigView(config: AgentConfig): AgentConfigView;
+export { toOpt };
+//# sourceMappingURL=mappers.d.ts.map

package/dist/mappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mappers.d.ts","sourceRoot":"","sources":["../src/mappers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,WAAW,EACX,WAAW,EACX,eAAe,EAClB,MAAM,wEAAwE,CAAC;AAChF,OAAO,KAAK,EACR,mBAAmB,EACnB,eAAe,EACf,eAAe,EAClB,MAAM,iBAAiB,CAAC;AAMzB,iBAAS,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAEhD;AAED,wBAAgB,sBAAsB,CAClC,IAAI,EAAE,eAAe,GACtB,mBAAmB,CAErB;AAED,wBAAgB,wBAAwB,CACpC,IAAI,EAAE,mBAAmB,GAC1B,eAAe,CAEjB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,eAAe,CAQxE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAWvE;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/dist/mappers.js

@@ -0,0 +1,34 @@
+function fromOpt(opt) {
+    return opt[0];
+}
+function toOpt(value) {
+    return value === undefined ? [] : [value];
+}
+export function mapChatMessageRoleView(role) {
+    return Object.keys(role)[0];
+}
+export function toChatMessageRoleVariant(role) {
+    return { [role]: null };
+}
+export function mapChatMessageView(message) {
+    return {
+        role: mapChatMessageRoleView(message.role),
+        content: message.content,
+        toolCallId: fromOpt(message.toolCallId),
+        toolName: fromOpt(message.toolName),
+        timestamp: message.timestamp,
+    };
+}
+export function mapAgentConfigView(config) {
+    return {
+        id: config.id,
+        name: config.name,
+        persona: config.persona,
+        disclosesAsAi: config.disclosesAsAi,
+        tools: config.tools,
+        customConfigJson: fromOpt(config.customConfigJson),
+        createdAt: config.createdAt,
+        updatedAt: config.updatedAt,
+    };
+}
+export { toOpt };

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@jsm-mit/agent-platform-canister-package",
+    "version": "0.0.1",
+    "description": "Wrapper TypeScript package for the agent-platform-canister canister.",
+    "license": "ISC",
+    "author": "",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./declarations/*": "./declarations/*"
+    },
+    "files": [
+        "dist/",
+        "declarations/"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "clean": "rm -rf dist",
+        "prepare": "npm run build",
+        "publish-public": "npm run build && npm login && npm publish --access public",
+        "typecheck": "tsc --noEmit -p tsconfig.tests.json",
+        "sync-declarations": "bash scripts/sync-declarations.sh",
+        "test-suite": "bash scripts/run-tests.sh tests/test-suite.ts",
+        "sandbox": "npx tsx sandbox/main.ts",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "guard:clean": "test -z \"$(git status --porcelain)\" || { echo '✖ Git working tree is not clean — commit your changes before publishing (published code must be a known commit).'; exit 1; }",
+        "prepublishOnly": "npm run guard:clean"
+    },
+    "dependencies": {
+        "@jsm-mit/utils-package": "^0.5.0"
+    },
+    "peerDependencies": {
+        "@icp-sdk/core": "^6.0.0"
+    },
+    "devDependencies": {
+        "@jsm-mit/cli-game-helpers": "^0.1.0",
+        "@types/node": "^22.0.0",
+        "dotenv": "^16.4.0",
+        "prettier": "^3.3.0",
+        "tsx": "^4.19.0",
+        "typescript": "^5.6.0",
+        "@icp-sdk/core": "^6.1.0"
+    }
+}