@tangle-network/agent-app 0.43.42 → 0.43.44

package/dist/chat-routes/index.d.ts

@@ -1,9 +1,9 @@
-import { C as ChatTurnRequestPayload, a as ChatTurnPartInput, b as ChatTurnFilePartInput } from '../file-index-Bw_IQE_G.js';
-export { c as ChatTurnInputError, d as ChatTurnTextPartInput, e as CreateSandboxFileIndexRouteOptions, F as FileIndexAuthorization, f as FileIndexCache, g as FileIndexReadyResponse, h as FileIndexResponse, i as FileIndexWarmingResponse, j as FileMention, k as FileMentionsToPartsOptions, I as INLINE_PARTS_MAX_BYTES, S as SandboxFileTreeSource, l as SandboxTreeFile, m as SandboxTreeResult, n as assertPromptPartsWithinCap, o as buildMentionPromptBlock, p as chatTurnRequestInit, q as createSandboxFileIndexRoute, r as fileMentionsToParts, s as mediaTypeForMentionPath, t as parseChatTurnParts, u as promptPartsByteSize } from '../file-index-Bw_IQE_G.js';
+import { A as ChatTurnRequestPayload, B as ChatTurnPartInput, e as ChatMessagePart, D as ChatTurnFilePartInput } from '../parts-1_3y2JmR.js';
+export { c as ChatMentionKind, E as ChatTurnInputError, G as ChatTurnTextPartInput, F as FileMention, H as FileMentionsToPartsOptions, I as INLINE_PARTS_MAX_BYTES, M as MENTION_MAX_COUNT, J as SandboxMentionPathCheck, K as assertPromptPartsWithinCap, L as buildMentionPromptBlock, N as chatTurnRequestInit, O as fileMentionsToParts, P as mediaTypeForMentionPath, Q as mentionKindForPath, R as parseChatTurnParts, T as parseFileMentions, U as promptPartsByteSize, V as validateSandboxMentionPath } from '../parts-1_3y2JmR.js';
 import { ChatTurnIdentity, ChatTurnProducer } from '@tangle-network/agent-runtime';
-import { c as ChatMessagePart } from '../parts-DjX0RRTS.js';
 import { InteractionAnswerRoute, InteractionAnswerRouteOptions } from '../interactions/index.js';
 import { PersistedChatMessageForTurn, TurnEventStore } from '../stream/index.js';
+export { C as CreateSandboxFileIndexRouteOptions, F as FileIndexAuthorization, a as FileIndexCache, b as FileIndexReadyResponse, c as FileIndexResponse, d as FileIndexWarmingResponse, S as SandboxFileTreeSource, e as SandboxTreeFile, f as SandboxTreeResult, g as createSandboxFileIndexRoute } from '../file-index-Bn6sitKb.js';
 import '@tangle-network/agent-interface';
 import '../contract-KfqJh_au.js';
 import '../plans/index.js';
@@ -318,6 +318,154 @@ interface ChatTurnRoutes {
 }
 declare function createChatTurnRoutes<TContext = void>(options: CreateChatTurnRoutesOptions<TContext>): ChatTurnRoutes;
 
+/**
+ * Recovery policy for a `ChatTurnLock` whose holder died.
+ *
+ * `createChatTurnRoutes` takes the lock as a seam (`acquire`/`release`) and a
+ * lock is a single-flight guard: while it is held, a second turn on the same
+ * scope is refused. Products give it a TTL measured in tens of minutes, so a
+ * turn that dies without releasing wedges chat for that whole window. Every
+ * app on the seam inherits that wedge, which is why the way OUT of it is
+ * policy this package owns rather than something each app rediscovers.
+ *
+ * The policy takes PROBES, not clients: it imports no sandbox SDK, opens no
+ * connection, and knows nothing about how a product finds its box or talks to
+ * a sidecar. That is what makes the rules testable and what keeps the concrete
+ * probes — which box key, which session id, which sidecar endpoint — in the
+ * product.
+ *
+ * The rules, in precedence order:
+ *
+ * 1. The session probe answered and the execution is TERMINAL ⇒ release, once
+ *    the lock is past a short grace period. The authority on "is this turn
+ *    still running" is whatever is actually running it; a terminal verdict is
+ *    proof the lock outlived its turn — but only if the verdict is about THIS
+ *    turn, which is what the grace buys (see
+ *    {@link DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS}).
+ * 2. The session probe answered and the execution is LIVE ⇒ hold, always.
+ *    Nothing below may override this. The lock is doing exactly its job.
+ * 3. The probes could not reach that authority at all — the sandbox could not
+ *    be listed, is gone, is not running, or its session probe failed ⇒ fall
+ *    back on the physical argument: an execution runs INSIDE the box, so a box
+ *    that is not there is running nothing, and the lock is releasable. Without
+ *    this fallback the recovery would depend on the very subsystem whose
+ *    failure produced the stale lock.
+ *
+ * Rule 3 is gated on a grace period because it is an inference, not an
+ * observation — see {@link DEFAULT_STALE_TURN_LOCK_GRACE_MS}.
+ */
+/** Where the box is, as far as the caller can see. `state` on `not-running`
+ *  is the platform's own status string, carried through for the log. */
+type StaleTurnLockSandboxProbeResult = {
+    status: 'running';
+} | {
+    status: 'absent';
+} | {
+    status: 'not-running';
+    state?: string;
+};
+/** What the thing running the turn says about it. `terminal: false` means an
+ *  execution is LIVE — the strongest signal in the policy. `diagnostics` rides
+ *  through to the result and the logs unread. */
+type StaleTurnLockSessionProbeResult = {
+    reachable: true;
+    terminal: boolean;
+    diagnostics?: Record<string, unknown>;
+} | {
+    reachable: false;
+    reason?: string;
+};
+/**
+ * Minimum age a lock must reach before the "sandbox unreachable ⇒ nothing can
+ * be running" fallback may force-release it.
+ *
+ * The lock is acquired BEFORE the box is ensured, so during a cold workspace's
+ * first turn there is a real window in which the lock is held and no box exists
+ * yet — indistinguishable, from a peek, from a box that vanished. The grace
+ * period has to outlast that window (create + bootstrap + whatever the product
+ * hydrates) or a concurrent request steals the lock from a turn that is merely
+ * still provisioning. Five minutes clears observed cold starts with room to
+ * spare while cutting the worst case from a TTL-length wedge down to five
+ * minutes. Raising it makes recovery slower; lowering it risks stealing a lock
+ * mid-provision.
+ */
+declare const DEFAULT_STALE_TURN_LOCK_GRACE_MS: number;
+/**
+ * Minimum age a lock must reach before a TERMINAL session verdict may release
+ * it.
+ *
+ * The session probe is keyed on the THREAD, not on the execution the lock
+ * holds: a sidecar that has nothing running reports `terminal` with
+ * `activeExecutionId: null`, so there is no id to match the lock against. The
+ * lock, meanwhile, is acquired BEFORE the box is ensured and before the
+ * execution registers with the sidecar. Between those two moments a second
+ * request that reconciles the lock asks the sidecar about a turn it has not
+ * heard of yet and gets back the PREVIOUS turn's terminal state — proof about
+ * the wrong execution. Releasing on that verdict hands the second request a
+ * lock the first one is still using, which is two concurrent turns on a scope
+ * whose single-flight guard just voted for itself.
+ *
+ * One minute covers the acquire → box-ensure → sidecar-registration window on
+ * a warm box (the cold-box case is Rule 3's, and has its own, much longer
+ * grace). Deliberately NOT
+ * {@link DEFAULT_STALE_TURN_LOCK_GRACE_MS}: this branch has a positive
+ * observation behind it, so it should recover fast, and stretching it to five
+ * minutes would leave a genuinely dead turn wedged for the whole window that
+ * the session probe exists to shortcut. Raising it delays recovery from a
+ * crashed turn; lowering it narrows the registration window it protects.
+ */
+declare const DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS: number;
+interface ReconcileStaleTurnLockOptions {
+    /** When the held lock was acquired (epoch ms). The grace period is measured
+     *  from here, so it must be the LOCK's start, not the turn's. */
+    lockStartedAt: number;
+    /** Is the box there and running? Never provisions — a peek, not an ensure.
+     *  A throw is treated as unreachable, same as `absent`. */
+    probeSandbox(): Promise<StaleTurnLockSandboxProbeResult>;
+    /** Ask the running box whether the execution is still live. Only called when
+     *  `probeSandbox` reported `running`. A throw is treated as unreachable. */
+    probeSession(): Promise<StaleTurnLockSessionProbeResult>;
+    /** Release the lock, fenced by the instant the releasing evidence was
+     *  observed. `fence.observedAt` is snapshotted BEFORE the probe that
+     *  justified the release, so a store that can compare it against the held
+     *  lock's start refuses to delete a SUCCESSOR lock acquired while the probe
+     *  was in flight. A store that cannot make that comparison may ignore the
+     *  fence, but must not substitute its own `Date.now()` — that timestamp is
+     *  by construction newer than any successor and makes the check vacuous.
+     *
+     *  Returns whether the release actually landed — `false` when the lock was
+     *  already gone (someone else got there first), which is reported, never
+     *  treated as a release. */
+    release(fence: {
+        observedAt: number;
+    }): boolean | Promise<boolean>;
+    /** Override {@link DEFAULT_STALE_TURN_LOCK_GRACE_MS} (Rule 3's fallback). */
+    graceMs?: number;
+    /** Override {@link DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS} (Rule 1's release). */
+    terminalGraceMs?: number;
+    /** Identity fields merged into every log line (workspace, thread, execution
+     *  id — whatever makes the entry findable in the product's logs). */
+    context?: Record<string, unknown>;
+    /** Defaults to `console.warn`. Both the withheld and the force-released
+     *  branches log; a force-release is never silent. */
+    log?(message: string, meta: Record<string, unknown>): void;
+    /** Injectable clock, for tests. */
+    now?(): number;
+}
+interface ReconcileStaleTurnLockResult {
+    released: boolean;
+    /** Why the policy decided what it did — the probe's own diagnostics on the
+     *  reachable path, the unreachable reason and lock age on the fallback. */
+    diagnostics: Record<string, unknown>;
+}
+/**
+ * Decide whether a held lock is stale and, if so, release it.
+ *
+ * Never provisions and never mutates anything but the lock: a reconciliation
+ * attempt on a cold workspace leaves it cold.
+ */
+declare function reconcileStaleTurnLock(options: ReconcileStaleTurnLockOptions): Promise<ReconcileStaleTurnLockResult>;
+
 /**
  * Sandbox lane: bridge a raw sandbox event stream (`streamSandboxPrompt`) into
  * the `ChatTurnProducer` shape agent-runtime's `handleChatTurn` consumes AND
@@ -440,4 +588,4 @@ declare function sanitizeUploadFilename(name: string): string;
 declare function bytesToBase64(bytes: Uint8Array): string;
 declare function createUploadRoute(options: CreateUploadRouteOptions): (request: Request) => Promise<Response>;
 
-export { type ChatRouteDurableProjection, type ChatRouteDurableProjectionLogger, type ChatTurnAuthorization, type ChatTurnAuthorizeArgs, ChatTurnFilePartInput, type ChatTurnGateResult, type ChatTurnHeartbeat, type ChatTurnInputPatch, type ChatTurnLifecycle, type ChatTurnLifecycleComplete, type ChatTurnLifecycleError, type ChatTurnLifecycleStart, type ChatTurnLock, type ChatTurnLockResult, type ChatTurnMessageStore, ChatTurnPartInput, type ChatTurnProduceArgs, ChatTurnRequestPayload, type ChatTurnRouteProducer, type ChatTurnRoutes, type ChatTurnUsage, type CreateChatTurnRoutesOptions, type CreateUploadRouteOptions, type SandboxChatProducerOptions, type SandboxUploadSink, UPLOAD_INLINE_MAX_BYTES, UPLOAD_MAX_FILE_BYTES, type UploadAuthorization, type UploadedChatFile, bytesToBase64, createChatTurnRoutes, createSandboxChatProducer, createUploadRoute, sanitizeUploadFilename, withDurableChatProjection };
+export { type ChatRouteDurableProjection, type ChatRouteDurableProjectionLogger, type ChatTurnAuthorization, type ChatTurnAuthorizeArgs, ChatTurnFilePartInput, type ChatTurnGateResult, type ChatTurnHeartbeat, type ChatTurnInputPatch, type ChatTurnLifecycle, type ChatTurnLifecycleComplete, type ChatTurnLifecycleError, type ChatTurnLifecycleStart, type ChatTurnLock, type ChatTurnLockResult, type ChatTurnMessageStore, ChatTurnPartInput, type ChatTurnProduceArgs, ChatTurnRequestPayload, type ChatTurnRouteProducer, type ChatTurnRoutes, type ChatTurnUsage, type CreateChatTurnRoutesOptions, type CreateUploadRouteOptions, DEFAULT_STALE_TURN_LOCK_GRACE_MS, DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS, type ReconcileStaleTurnLockOptions, type ReconcileStaleTurnLockResult, type SandboxChatProducerOptions, type SandboxUploadSink, type StaleTurnLockSandboxProbeResult, type StaleTurnLockSessionProbeResult, UPLOAD_INLINE_MAX_BYTES, UPLOAD_MAX_FILE_BYTES, type UploadAuthorization, type UploadedChatFile, bytesToBase64, createChatTurnRoutes, createSandboxChatProducer, createUploadRoute, reconcileStaleTurnLock, sanitizeUploadFilename, withDurableChatProjection };

package/dist/chat-routes/index.js

@@ -1,15 +1,6 @@
 import {
-  ChatTurnInputError,
-  INLINE_PARTS_MAX_BYTES,
-  assertPromptPartsWithinCap,
-  buildMentionPromptBlock,
-  chatTurnRequestInit,
-  createSandboxFileIndexRoute,
-  fileMentionsToParts,
-  mediaTypeForMentionPath,
-  parseChatTurnParts,
-  promptPartsByteSize
-} from "../chunk-2EO7CPL3.js";
+  createSandboxFileIndexRoute
+} from "../chunk-LCNY3DCM.js";
 import {
   asRecord,
   asString,
@@ -31,8 +22,22 @@ import {
   parseJsonObjectBody
 } from "../chunk-HFC4BTWJ.js";
 import {
-  toChatMessageParts
-} from "../chunk-I2ATYB7R.js";
+  ChatTurnInputError,
+  INLINE_PARTS_MAX_BYTES,
+  MENTION_MAX_COUNT,
+  assertPromptPartsWithinCap,
+  buildMentionPromptBlock,
+  chatTurnRequestInit,
+  fileMentionsToParts,
+  mediaTypeForMentionPath,
+  mentionInputToPart,
+  mentionKindForPath,
+  parseChatTurnParts,
+  parseFileMentions,
+  promptPartsByteSize,
+  toChatMessageParts,
+  validateSandboxMentionPath
+} from "../chunk-6E2XJSCT.js";
 import {
   cancelStatusFor,
   interactionPartKey,
@@ -64,8 +69,9 @@ function validateTurnBody(body, maxInlinePartBytes) {
   if (typeof rawContent !== "string") throw new ChatTurnInputError("content must be a string");
   const content = rawContent.trim();
   const fileParts = parseChatTurnParts(body.parts);
-  if (!content && fileParts.length === 0) {
-    throw new ChatTurnInputError("Missing content (send text, parts, or both)");
+  const mentions = parseFileMentions(body.mentions);
+  if (!content && fileParts.length === 0 && mentions.length === 0) {
+    throw new ChatTurnInputError("Missing content (send text, parts, mentions, or any combination)");
   }
   assertPromptPartsWithinCap(fileParts, maxInlinePartBytes);
   let turnId;
@@ -75,14 +81,22 @@ function validateTurnBody(body, maxInlinePartBytes) {
     throw new ChatTurnInputError(err instanceof Error ? err.message : "Invalid turnId");
   }
   return {
-    payload: { ...body, threadId, content },
+    // The VALIDATED, deduped mention list replaces the raw one on the payload,
+    // so every downstream seam (`authorize`, `contextGate`, `beforeTurn`,
+    // `produce`) reads checked paths and never the request's own.
+    payload: { ...body, threadId, content, mentions },
     content,
     fileParts,
+    mentions,
     turnId
   };
 }
-function userPartsWithFiles(userParts, fileParts) {
-  return toChatMessageParts([...userParts, ...fileParts.map((part) => ({ ...part }))]);
+function userPartsWithFiles(userParts, fileParts, mentions) {
+  return toChatMessageParts([
+    ...userParts,
+    ...fileParts.map((part) => ({ ...part })),
+    ...mentions.map((mention) => ({ ...mentionInputToPart(mention) }))
+  ]);
 }
 async function* tapRawEvents(source, onRawEvent, log) {
   for await (const event of source) {
@@ -139,7 +153,7 @@ function createChatTurnRoutes(options) {
       if (err instanceof ChatTurnInputError) return errorResponse(err);
       throw err;
     }
-    const { payload, content, fileParts, turnId } = parsed;
+    const { payload, content, fileParts, mentions, turnId } = parsed;
     const auth = await options.authorize({ request, intent: "turn", body: payload });
     if (!auth.ok) return auth.response;
     const { tenantId, userId, context } = auth;
@@ -241,7 +255,7 @@ function createChatTurnRoutes(options) {
           threadId: payload.threadId,
           role: "user",
           content,
-          parts: userPartsWithFiles(chatTurn.userParts, fileParts)
+          parts: userPartsWithFiles(chatTurn.userParts, fileParts, mentions)
         });
       }
       if (options.contextGate) {
@@ -485,6 +499,99 @@ function concatStreams(streams) {
   });
 }
 
+// src/chat-routes/stale-turn-lock.ts
+var DEFAULT_STALE_TURN_LOCK_GRACE_MS = 5 * 60 * 1e3;
+var DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS = 60 * 1e3;
+function messageOf(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function reconcileStaleTurnLock(options) {
+  let sandbox;
+  try {
+    sandbox = await options.probeSandbox();
+  } catch (err) {
+    return forceReleaseUnreachable(options, {
+      unreachableReason: "SANDBOX_PROBE_FAILED",
+      unreachableDetail: messageOf(err)
+    });
+  }
+  if (sandbox.status !== "running") {
+    return forceReleaseUnreachable(options, {
+      unreachableReason: sandbox.status === "absent" ? "SANDBOX_ABSENT" : "SANDBOX_NOT_RUNNING",
+      ...sandbox.status === "not-running" && sandbox.state !== void 0 ? { sandboxState: sandbox.state } : {}
+    });
+  }
+  const observedAt = (options.now ?? Date.now)();
+  let session;
+  try {
+    session = await options.probeSession();
+  } catch (err) {
+    return forceReleaseUnreachable(options, {
+      unreachableReason: "SESSION_PROBE_FAILED",
+      unreachableDetail: messageOf(err)
+    });
+  }
+  if (!session.reachable) {
+    return forceReleaseUnreachable(options, {
+      unreachableReason: "SESSION_UNREACHABLE",
+      ...session.reason !== void 0 ? { sessionProbeError: session.reason } : {}
+    });
+  }
+  const diagnostics = {
+    sandboxReachable: true,
+    sessionTerminal: session.terminal,
+    ...session.diagnostics ?? {}
+  };
+  if (!session.terminal) return { released: false, diagnostics };
+  const terminalGraceMs = options.terminalGraceMs ?? DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS;
+  const lockAgeMs = observedAt - options.lockStartedAt;
+  if (lockAgeMs < terminalGraceMs) {
+    const log = options.log ?? ((message, meta) => console.warn(message, meta));
+    const withheld = {
+      ...diagnostics,
+      lockAgeMs,
+      terminalReleaseGraceMs: terminalGraceMs,
+      terminalReleaseWithheld: "LOCK_WITHIN_TERMINAL_GRACE_PERIOD"
+    };
+    log("[chat-routes] stale turn lock held: terminal verdict but lock is younger than the registration window", {
+      ...options.context ?? {},
+      ...withheld
+    });
+    return { released: false, diagnostics: withheld };
+  }
+  const released = await options.release({ observedAt });
+  return {
+    released,
+    diagnostics: { ...diagnostics, lockAgeMs, terminalReleaseGraceMs: terminalGraceMs, released, observedAt }
+  };
+}
+async function forceReleaseUnreachable(options, reason) {
+  const log = options.log ?? ((message, meta) => console.warn(message, meta));
+  const graceMs = options.graceMs ?? DEFAULT_STALE_TURN_LOCK_GRACE_MS;
+  const at = (options.now ?? Date.now)();
+  const lockAgeMs = at - options.lockStartedAt;
+  const diagnostics = {
+    ...reason,
+    sandboxReachable: false,
+    lockAgeMs,
+    forceReleaseGraceMs: graceMs
+  };
+  if (lockAgeMs < graceMs) {
+    log("[chat-routes] stale turn lock held: sandbox unreachable but lock is inside the grace period", {
+      ...options.context ?? {},
+      ...diagnostics
+    });
+    return { released: false, diagnostics: { ...diagnostics, forceReleaseWithheld: "LOCK_WITHIN_GRACE_PERIOD" } };
+  }
+  const released = await options.release({ observedAt: at });
+  log("[chat-routes] force-released stale turn lock: sandbox unreachable, no turn can be executing", {
+    ...options.context ?? {},
+    ...diagnostics,
+    released
+  });
+  return { released, diagnostics: { ...diagnostics, forceReleased: released } };
+}
+
 // src/chat-routes/sandbox-producer.ts
 function textDelta(tracker, key, part, rawDelta) {
   const explicit = typeof rawDelta === "string" ? rawDelta : void 0;
@@ -828,7 +935,10 @@ function createUploadRoute(options) {
 }
 export {
   ChatTurnInputError,
+  DEFAULT_STALE_TURN_LOCK_GRACE_MS,
+  DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS,
   INLINE_PARTS_MAX_BYTES,
+  MENTION_MAX_COUNT,
   UPLOAD_INLINE_MAX_BYTES,
   UPLOAD_MAX_FILE_BYTES,
   assertPromptPartsWithinCap,
@@ -841,9 +951,13 @@ export {
   createUploadRoute,
   fileMentionsToParts,
   mediaTypeForMentionPath,
+  mentionKindForPath,
   parseChatTurnParts,
+  parseFileMentions,
   promptPartsByteSize,
+  reconcileStaleTurnLock,
   sanitizeUploadFilename,
+  validateSandboxMentionPath,
   withDurableChatProjection
 };
 //# sourceMappingURL=index.js.map