@tangle-network/agent-app 0.49.9 → 0.49.11

package/dist/hosted-agent/engine.d.ts

@@ -0,0 +1,159 @@
+import type { BackendConfig, CreateSessionOptions } from '@tangle-network/sandbox';
+import type { ConversationTurnOptions, ConversationTurnResult, PromptInputPart } from '@tangle-network/sandbox/core';
+/**
+ * The one turn engine for a hosted agent, whatever hosts it. This kit's
+ * `createHostedAgent` runs on it with a key-value store, and Agent Builder
+ * runs on it with its D1 enrollments, per-user keys, spaces and product
+ * ingest. A host supplies those as ports; the engine owns the order of the
+ * steps and what each outcome and failure means.
+ *
+ * One call is one non-blocking pass for one message:
+ *
+ *   validate -> admit once -> the person's box -> authorize -> session -> drive -> classify
+ *
+ * Every step is idempotent by the turn id: the sandbox's admission receipt
+ * settles a repeated drive on the same turn, so a host may repeat a pass for
+ * the same message any number of times and the agent runs it once.
+ */
+export type TurnRefusal = 'not_enrolled' | 'execution_not_ready' | 'refused' | 'unavailable';
+export type TurnReply = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    reason: TurnRefusal;
+    detail?: string;
+};
+export type TurnStep = 'ensure' | 'drive' | 'turn';
+/**
+ * Where an unfinished turn stands. `code` is the same on every repeat of the
+ * same cause, so a host can tell a stuck turn from a slow one. A transient
+ * cause (a lost response, a timeout, a busy platform, a box still starting)
+ * is expected to clear by itself; any other repeats until it is fixed.
+ */
+export interface PendingDetail {
+    step: TurnStep;
+    code: string;
+    transient: boolean;
+}
+/** `cause` is what a port or the Sandbox threw, when a throw left the turn pending. */
+export type TurnOutcome = TurnReply | {
+    ok: 'pending';
+    detail: PendingDetail;
+    cause?: unknown;
+};
+export declare const MAX_MESSAGE_CHARS = 8000;
+/** Identical non-transient failures in a row after which a host fails a turn. */
+export declare const MAX_REPEATED_FAILURES = 3;
+/** Refusal detail when the host's `authorize` check fails. */
+export declare const AUTHORITY_ENDED = "authority_ended";
+/** The part of a Sandbox box one turn uses. `SandboxInstance` satisfies it. */
+export interface TurnBox {
+    readonly id: string;
+    driveConversationTurn(message: string | PromptInputPart[], options: ConversationTurnOptions): Promise<ConversationTurnResult>;
+    session(id: string): {
+        status(): Promise<unknown>;
+    };
+    createSession(options: CreateSessionOptions): Promise<unknown>;
+}
+/** A port throws this to report a turn that is not ready yet, such as a box still starting. */
+export declare class TurnPending extends Error {
+    readonly code: string;
+    readonly transient: boolean;
+    constructor(code: string, transient: boolean);
+}
+/** A thrown value as a stable code plus a secret-free message for a log line. */
+export interface TurnFailure {
+    name: string;
+    code: string;
+    status?: number;
+    reason?: string;
+    message: string;
+}
+/** What a pass reports while it runs. Every hook is optional; none changes the outcome. */
+export interface TurnObserver {
+    /** Time one step of this pass took, whether it returned or threw. */
+    span?(step: 'ensure' | 'session' | 'drive', ms: number): void;
+    /** The session the turn runs in, as the runtime reports it, or the backend it was created with. */
+    session?(info: {
+        harness?: string;
+        model?: string;
+        created: boolean;
+    }): void;
+    /**
+     * Read a session this pass created once more, so `session` reports the
+     * harness and model the runtime chose for it. It costs one request, so a
+     * host asks for it only when it shows them (an owner's debug line, say).
+     */
+    readCreatedSession?: boolean;
+    /** Each drive result and the time it arrived. */
+    drive?(result: ConversationTurnResult, at: number): void;
+    /** A failure that left the turn pending or refused. */
+    failure?(step: TurnStep, failure: TurnFailure, boxId?: string): void | Promise<void>;
+}
+/** Storage and policy a host supplies for one message. */
+export interface HostedTurnPorts<Box extends TurnBox = TurnBox> {
+    /**
+     * Admit this turn once, before any compute. Return null to run it, or the
+     * refusal. A turn admitted by an earlier pass must return null again, so a
+     * retry never consumes allowance twice.
+     */
+    admit(): Promise<Extract<TurnReply, {
+        ok: false;
+    }> | null>;
+    /** The person's running box: created, resumed or replaced as needed. Throw to report why not. */
+    box(): Promise<Box>;
+    /** The host's own authority (a phone link, say), read after the box is ready and right before the drive. */
+    authorize?(): Promise<boolean>;
+    /** The session this turn runs in. A session binds its backend when created, so a new persona needs a new id. */
+    sessionId: string;
+    /** The backend a missing session is created with. Without it the runtime answers as its generic assistant. */
+    backend(): Promise<BackendConfig>;
+    /** The message as the agent receives it: text, or text and images. */
+    prompt(box: Box): Promise<string | PromptInputPart[]>;
+    /** Runs once the turn has a non-empty answer, before the pass returns it. */
+    answered?(answer: string, box: Box): Promise<void>;
+    /** Map a thrown value to an outcome. Undefined leaves it to the engine's own classification. */
+    classify?(error: unknown, step: 'ensure' | 'drive'): TurnOutcome | undefined;
+    observe?: TurnObserver;
+}
+export interface HostedTurnOptions {
+    /** The run's wall-clock cap; the Sandbox cancels a turn that exceeds it. */
+    wallCapMs: number;
+    /** How long one drive request may wait on a running turn. Default 8 s. */
+    timeoutMs?: number;
+    /** False only reads a turn admitted earlier; it never admits or starts one. */
+    allowDispatch?: boolean;
+    /** Keep driving a running turn until this time, instead of returning pending after one drive. */
+    until?: number;
+    /** Wait between drives while `until` allows. Default 2 s. */
+    pollMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** The code omits the message, which can carry ids or times that differ on every repeat of one cause. */
+export declare function describeFailure(error: unknown): TurnFailure;
+export declare function isTransientFailure(failure: Pick<TurnFailure, 'name' | 'status' | 'reason'>): boolean;
+/** One non-blocking pass for one message. Safe to repeat with the same turn id. */
+export declare function runHostedTurn<Box extends TurnBox>(turn: {
+    turnId: string;
+    text: string;
+}, ports: HostedTurnPorts<Box>, options: HostedTurnOptions): Promise<TurnOutcome>;
+/**
+ * Repeat passes until the turn settles, for a caller that holds a connection
+ * open (a voice question, say). A turn the runtime never finishes must not
+ * hold the caller forever, so `deadline` bounds the wait; `signal` stops the
+ * wait only, and the admitted turn keeps running.
+ */
+export declare function settleHostedTurn(pass: () => Promise<TurnOutcome>, options: {
+    deadline: number;
+    pollMs?: number;
+    signal?: AbortSignal;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}): Promise<TurnReply>;
+/**
+ * A space member who may chat only: no shell and no file writes in the shared
+ * box. The profile's other settings are kept.
+ */
+export declare function chatOnlyBackend(backend: BackendConfig): BackendConfig;

package/dist/hosted-agent/index.d.ts

@@ -1,5 +1,6 @@
 import { type HubProviderEvent } from '@tangle-network/hub-sdk';
 import type { AgentProfile } from '@tangle-network/sandbox';
+export * from './engine';
 /**
  * A hosted agent: a person texts or calls a line, and the agent answers from
  * that person's own isolated sandbox. The developer's Tangle API key pays for

package/dist/hosted-agent/index.js

@@ -2,6 +2,169 @@
 import { authenticateHubEventRequest, HubClient } from "@tangle-network/hub-sdk";
 import { buildMessagingReply, normalizeConversationEvent } from "@tangle-network/agent-integrations/conversation-events";
 import { Sandbox, SandboxError } from "@tangle-network/sandbox/core";
+
+// src/hosted-agent/engine.ts
+var MAX_MESSAGE_CHARS = 8e3;
+var MAX_REPEATED_FAILURES = 3;
+var AUTHORITY_ENDED = "authority_ended";
+var TurnPending = class extends Error {
+  constructor(code, transient) {
+    super(code);
+    this.code = code;
+    this.transient = transient;
+    this.name = "TurnPending";
+  }
+  code;
+  transient;
+};
+function sessionInfo(session) {
+  const s = typeof session === "object" && session !== null ? session : {};
+  const effective = s.effectiveBackend?.model;
+  const model = typeof effective === "string" && effective ? effective : typeof s.model === "string" && s.model ? s.model : void 0;
+  return { ...typeof s.backend === "string" && s.backend ? { harness: s.backend } : {}, ...model ? { model } : {} };
+}
+var refusal = (reason, detail) => ({ ok: false, reason, ...detail ? { detail } : {} });
+var RUNNING = /* @__PURE__ */ new Set(["running", "awaiting_input", "not_admitted"]);
+var TRANSIENT_ERRORS = /* @__PURE__ */ new Set(["NetworkError", "TimeoutError", "QuotaError", "AbortError", "EdgeNotReadyError"]);
+var TRANSIENT_503 = /* @__PURE__ */ new Set(["MODEL_CREDENTIAL_SUPERSEDED", "HUB_CREDENTIAL_REFRESH_UNAVAILABLE"]);
+function describeFailure(error) {
+  const e = typeof error === "object" && error !== null ? error : {};
+  const name = typeof e.name === "string" ? e.name : typeof error;
+  const status = typeof e.status === "number" ? e.status : void 0;
+  const own = typeof e.code === "string" ? e.code : typeof e.reason === "string" ? e.reason : void 0;
+  const code = [name, own, status].filter((part) => part !== void 0).join(":").replace(/[^\w.:-]/g, "_").slice(0, 100);
+  const message = String(typeof e.message === "string" ? e.message : error).replace(/sk-tan-[\w-]+|eyJ[\w-]+\.[\w-]+\.[\w-]*|Bearer\s+\S+/g, "<redacted>").slice(0, 400);
+  return { name, code, ...status !== void 0 ? { status } : {}, ...own !== void 0 ? { reason: own } : {}, message };
+}
+function isTransientFailure(failure) {
+  return TRANSIENT_ERRORS.has(failure.name) || [408, 429, 502, 504].includes(failure.status ?? 0) || failure.status === 503 && (failure.reason === void 0 || TRANSIENT_503.has(failure.reason));
+}
+var budgetExhausted = (error) => error instanceof Error && error.name === "KeyBudgetExhaustedError";
+async function runHostedTurn(turn, ports, options) {
+  const now = options.now ?? Date.now;
+  const sleep2 = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const observe = ports.observe ?? {};
+  const allowDispatch = options.allowDispatch !== false;
+  const text = turn.text.trim();
+  if (!text || text.length > MAX_MESSAGE_CHARS || !turn.turnId || turn.turnId.length > 200) return refusal("refused", "invalid_message");
+  const refused = await ports.admit();
+  if (refused) return refused;
+  const timed = async (step, fn) => {
+    const start = now();
+    try {
+      return await fn();
+    } finally {
+      observe.span?.(step, now() - start);
+    }
+  };
+  const failed = async (step, error, boxId) => {
+    const failure = describeFailure(error);
+    await observe.failure?.(step, failure, boxId);
+    const classified = ports.classify?.(error, step);
+    if (classified) return classified;
+    if (error instanceof TurnPending) return { ok: "pending", detail: { step, code: error.code, transient: error.transient } };
+    if (budgetExhausted(error)) return refusal("refused", "budget_exhausted");
+    return { ok: "pending", detail: { step, code: failure.code, transient: isTransientFailure(failure) }, cause: error };
+  };
+  let box;
+  try {
+    box = await timed("ensure", () => ports.box());
+  } catch (error) {
+    return failed("ensure", error);
+  }
+  if (ports.authorize && !await ports.authorize()) return refusal("refused", AUTHORITY_ENDED);
+  let result;
+  try {
+    const prompt = await ports.prompt(box);
+    const sessionId = ports.sessionId;
+    if (allowDispatch) await timed("session", async () => {
+      const session = await box.session(sessionId).status();
+      if (session) {
+        observe.session?.({ created: false, ...sessionInfo(session) });
+        return;
+      }
+      const backend = await ports.backend();
+      await box.createSession({ sessionId, retention: "workspace", backend });
+      const created = observe.session && observe.readCreatedSession ? sessionInfo(await box.session(sessionId).status()) : {};
+      observe.session?.({ created: true, ...backend.type ? { harness: backend.type } : {}, ...created });
+    });
+    for (; ; ) {
+      result = await timed("drive", () => box.driveConversationTurn(prompt, {
+        sessionId,
+        turnId: turn.turnId,
+        wallCapMs: options.wallCapMs,
+        timeoutMs: options.timeoutMs ?? 8e3,
+        allowDispatch
+      }));
+      observe.drive?.(result, now());
+      const pollMs = options.pollMs ?? 2e3;
+      if (!RUNNING.has(result.state) || options.until === void 0 || now() + pollMs > options.until) break;
+      await sleep2(pollMs);
+    }
+  } catch (error) {
+    return failed("drive", error, box.id);
+  }
+  switch (result.state) {
+    case "completed": {
+      const answer = result.text.trim();
+      if (!answer) {
+        await observe.failure?.("turn", describeFailure(new Error("The turn completed with no reply text")), box.id);
+        return refusal("unavailable", "empty_reply");
+      }
+      await ports.answered?.(answer, box);
+      return { ok: true, text: answer };
+    }
+    case "failed":
+      await observe.failure?.("turn", describeFailure(Object.assign(new Error(result.error), { name: "TurnFailed" })), box.id);
+      return refusal("unavailable", "agent_failed");
+    // Interaction and plan approval are not exposed over messaging. The wall
+    // cap cancels a turn that waits on one, which frees the session.
+    // Sandbox 0.45 reported approval and question outcomes as `failed`.
+    case "awaiting_plan_decision":
+    case "blocked_on_approval":
+    case "awaiting_question":
+    case "awaiting_interaction":
+      return refusal("refused", "needs_decision");
+    case "running":
+    case "awaiting_input":
+    case "not_admitted":
+      return { ok: "pending", detail: { step: "turn", code: result.state, transient: true } };
+  }
+}
+async function settleHostedTurn(pass, options) {
+  const now = options.now ?? Date.now;
+  const sleep2 = options.sleep ?? ((ms, signal) => new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    }, { once: true });
+  }));
+  let last = "", repeats = 0;
+  for (; ; ) {
+    if (options.signal?.aborted || now() > options.deadline) return refusal("unavailable", "pending");
+    const outcome = await pass();
+    if (outcome.ok !== "pending") return outcome;
+    repeats = outcome.detail.code === last ? repeats + 1 : 1;
+    last = outcome.detail.code;
+    if (!outcome.detail.transient && repeats >= MAX_REPEATED_FAILURES) return refusal("unavailable", `${outcome.detail.step}:${last}`);
+    try {
+      await sleep2(options.pollMs ?? 1500, options.signal);
+    } catch {
+      return refusal("unavailable", "pending");
+    }
+  }
+}
+function chatOnlyBackend(backend) {
+  const profile = backend.profile ?? {};
+  return { ...backend, profile: {
+    ...profile,
+    tools: { ...profile.tools, bash: false, edit: false, write: false },
+    permissions: { ...profile.permissions, bash: "deny", edit: "deny" }
+  } };
+}
+
+// src/hosted-agent/index.ts
 var DEFAULT_BOX_POLICY = {
   cpuCores: 1,
   memoryMB: 2048,
@@ -187,54 +350,77 @@ function createHostedAgent(config) {
     if (!text || text.length > 8e3 || !/^[\w-]{1,120}$/.test(message.turnId)) return { state: "declined" };
     const user = (await sha256(message.userId)).slice(0, 32);
     const admittedKey = `turn:${user}:${message.turnId}`;
-    if (!await store.get(admittedKey)) {
-      const decision = await admit(message, user);
-      if (decision === "ignore") return { state: "declined" };
-      if (decision !== "answer") return { state: "declined", reply: decision.reply };
-      await store.put(admittedKey, "1", { expirationTtl: TWO_DAYS });
-    }
-    const trace = options.trace, traceKey = `trace:${user}:${message.turnId}`;
-    const box = await ensureBox(user, options.deadline, trace);
-    if (trace) {
-      const first = await store.get(traceKey);
-      if (first) trace.box = first;
-      else if (trace.box) await store.put(traceKey, trace.box, { expirationTtl: TWO_DAYS });
-    }
-    if (!box) return { state: "pending" };
     const sessionId = `hosted-${user}-${await profileTag}`;
-    const session = await box.session(sessionId).status();
-    if (!session) await box.createSession({ sessionId, retention: "workspace", backend });
-    if (trace) {
-      trace.harness = session?.backend ?? config.harness;
-      trace.model = session?.model;
-    }
-    const asked = message.channel === "voice" ? `[Phone call. Answer in one to three short spoken sentences.]
+    const trace = options.trace, traceKey = `trace:${user}:${message.turnId}`;
+    const conversationKey = `convo:${user}`;
+    let declined;
+    let conversation, at = "";
+    const outcome = await runHostedTurn({ turnId: message.turnId, text }, {
+      async admit() {
+        if (await store.get(admittedKey)) return null;
+        const decision = await admit(message, user);
+        if (decision === "answer") {
+          await store.put(admittedKey, "1", { expirationTtl: TWO_DAYS });
+          return null;
+        }
+        declined = decision === "ignore" ? { state: "declined" } : { state: "declined", reply: decision.reply };
+        return { ok: false, reason: "refused", detail: "declined" };
+      },
+      async box() {
+        const box = await ensureBox(user, options.deadline, trace);
+        if (trace) {
+          const first = await store.get(traceKey);
+          if (first) trace.box = first;
+          else if (trace.box) await store.put(traceKey, trace.box, { expirationTtl: TWO_DAYS });
+        }
+        if (!box) throw new TurnPending("box_starting", true);
+        return box;
+      },
+      sessionId,
+      backend: async () => backend,
+      async prompt(box) {
+        const asked = message.channel === "voice" ? `[Phone call. Answer in one to three short spoken sentences.]
 ${text}` : text;
-    const conversationKey = `convo:${user}`, at = `${box.id}/${sessionId}`;
-    const stored = await store.get(conversationKey);
-    const conversation = stored ? JSON.parse(stored) : { at, turns: [] };
-    const carried = conversation.at === at ? "" : conversation.turns.map(([, them, you]) => `Them: ${them}
+        at = `${box.id}/${sessionId}`;
+        const stored = await store.get(conversationKey);
+        conversation = stored ? JSON.parse(stored) : { at, turns: [] };
+        const carried = conversation.at === at ? "" : conversation.turns.map(([, them, you]) => `Them: ${them}
 You: ${you}`).join("\n");
-    const prompt = carried ? `${CARRY_HEAD}
+        return carried ? `${CARRY_HEAD}
 ${carried}
 ${CARRY_NOW}
 ${asked}` : asked;
-    for (; ; ) {
-      const result = await box.driveConversationTurn(prompt, { sessionId, turnId: message.turnId, wallCapMs, timeoutMs: 8e3 });
-      if (result.state === "completed") {
-        const answer = result.text.trim();
-        if (!answer) throw new HostedAgentError("empty_reply", "The turn completed with no reply text.");
-        if (trace) noteResult(trace, result.result, result.usage);
-        const turns = conversation.turns.filter(([id]) => id !== message.turnId);
+      },
+      async answered(answer) {
+        const turns = (conversation?.turns ?? []).filter(([id]) => id !== message.turnId);
         turns.push([message.turnId, message.channel === "voice" ? `(on a call) ${text}` : text, answer]);
         while (turns.length > 1 && JSON.stringify(turns).length > CARRY_CHARS) turns.shift();
         await store.put(conversationKey, JSON.stringify({ at, turns }));
-        return { state: "answered", text: answer };
+      },
+      classify: (error) => error instanceof HostedAgentError ? { ok: false, reason: "unavailable", detail: error.code } : void 0,
+      observe: {
+        readCreatedSession: Boolean(trace),
+        session(info) {
+          if (!trace) return;
+          trace.harness = info.harness ?? config.harness;
+          trace.model = info.model;
+        },
+        drive(result) {
+          if (trace && result.state === "completed") noteResult(trace, result.result, result.usage);
+        },
+        failure(step, failure) {
+          console.error(`[hosted-agent] turn=${message.turnId} step=${step} code=${failure.code} message=${JSON.stringify(failure.message)}`);
+        }
       }
-      if (result.state === "failed") throw new HostedAgentError("turn_failed", result.error);
-      if (Date.now() + 2e3 > options.deadline) return { state: "pending" };
-      await sleep(2e3);
+    }, { wallCapMs, timeoutMs: 8e3, until: options.deadline });
+    if (declined) return declined;
+    if (outcome.ok === true) return { state: "answered", text: outcome.text };
+    if (outcome.ok === "pending") {
+      if (outcome.cause !== void 0) throw outcome.cause;
+      return { state: "pending" };
     }
+    const code = outcome.detail ?? outcome.reason;
+    throw new HostedAgentError(code === "agent_failed" ? "turn_failed" : code, `The turn ended without an answer (${code}).`);
   }
   return {
     ask,
@@ -359,14 +545,23 @@ ${debugFooter(config.profile.name ?? "agent", turnId, trace, totalMs)}`;
   };
 }
 export {
+  AUTHORITY_ENDED,
   CONVERSATION_TOOLS_OFF,
   DEFAULT_BOX_POLICY,
   DEFAULT_HOSTED_MODEL,
   HostedAgentError,
+  MAX_MESSAGE_CHARS,
+  MAX_REPEATED_FAILURES,
   NOTICE,
+  TurnPending,
+  chatOnlyBackend,
   createHostedAgent,
   debugCommand,
   debugFooter,
-  normalizeAddress
+  describeFailure,
+  isTransientFailure,
+  normalizeAddress,
+  runHostedTurn,
+  settleHostedTurn
 };
 //# sourceMappingURL=index.js.map