@opengeni/runtime 2.5.2 → 2.5.3-canary.1

package/src/mcp-operation-dispatch.ts

@@ -0,0 +1,144 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { AttemptToolResult } from "@opengeni/contracts";
+
+export type RecoverableMcpOperation = {
+  operationId: string;
+  sourceCallId?: string;
+  serverId: string;
+  originalTool: string;
+  observerTool: string;
+  destinationDigest: string;
+  argumentDigest: string;
+};
+
+export type CapturedMcpOperation = RecoverableMcpOperation & { authorityDigest: string };
+
+/** Worker-owned persistence. Its implementation must enforce canonical live
+ * attempt identity and store no arguments, URLs, headers, or credentials. */
+export type McpOperationPersistence = {
+  capture: (operation: CapturedMcpOperation) => Promise<"created" | "existing">;
+  settleOriginal: (
+    input:
+      | { operationId: string; outcome: "completed"; result: AttemptToolResult }
+      | { operationId: string; outcome: "outcome_unknown" },
+  ) => Promise<void>;
+};
+
+type DispatchContext = {
+  operation: RecoverableMcpOperation;
+  persistence: McpOperationPersistence;
+  captureStarted: boolean;
+  captured: boolean;
+  closed: boolean;
+};
+
+const dispatchContext = new AsyncLocalStorage<DispatchContext>();
+
+/** Presence is an execution-routing fact, not authorization. A closed context
+ * remains visible to late callbacks so they still hit the dispatch fence. */
+export function hasActiveRecoverableMcpOperation(): boolean {
+  return dispatchContext.getStore() !== undefined;
+}
+
+export class McpOperationOutcomeUnknownError extends Error {
+  readonly code = "mcp_operation_outcome_unknown";
+  constructor(
+    readonly operationId: string,
+    cause: unknown,
+  ) {
+    super(
+      `MCP operation ${operationId} has an unknown outcome. Read the existing operation result; do not repeat the mutation.`,
+      { cause },
+    );
+    this.name = "McpOperationOutcomeUnknownError";
+  }
+}
+
+/** Establish trusted in-process correlation around one gateway execution. */
+export async function runRecoverableMcpOperation(
+  operation: RecoverableMcpOperation,
+  persistence: McpOperationPersistence,
+  execute: () => Promise<AttemptToolResult>,
+): Promise<AttemptToolResult> {
+  const context: DispatchContext = {
+    operation: { ...operation },
+    persistence,
+    captureStarted: false,
+    captured: false,
+    closed: false,
+  };
+  return await dispatchContext.run(context, async () => {
+    let result: AttemptToolResult;
+    try {
+      try {
+        result = await execute();
+      } catch (error) {
+        if (!context.captured) throw error;
+        // An uncertain settlement acknowledgment cannot authorize replay or
+        // replace the original recovery handle with a database-only error.
+        try {
+          await persistence.settleOriginal({
+            operationId: operation.operationId,
+            outcome: "outcome_unknown",
+          });
+        } catch {
+          /* The pre-dispatch record remains the recovery authority. */
+        }
+        throw new McpOperationOutcomeUnknownError(operation.operationId, error);
+      }
+      if (!context.captured) {
+        throw new Error("Recoverable MCP execution did not cross its durable capture boundary");
+      }
+      try {
+        await persistence.settleOriginal({
+          operationId: operation.operationId,
+          outcome: "completed",
+          result,
+        });
+      } catch (error) {
+        // Never submit a second, contradictory settlement after an ambiguous
+        // acknowledgment of the successful one.
+        throw new McpOperationOutcomeUnknownError(operation.operationId, error);
+      }
+      return result;
+    } finally {
+      context.closed = true;
+    }
+  });
+}
+
+/** Called by the authorized broker immediately before the physical request.
+ * A second dispatch with the same identity is never an observation. */
+export async function captureMcpOperationDispatch(input: {
+  operationId: string;
+  serverId: string;
+  toolName: string;
+  destinationDigest: string;
+  authorityDigest: string;
+}): Promise<void> {
+  const context = dispatchContext.getStore();
+  if (!context) return;
+  const operation = context.operation;
+  if (
+    input.operationId !== operation.operationId ||
+    input.serverId !== operation.serverId ||
+    input.toolName !== operation.originalTool ||
+    input.destinationDigest !== operation.destinationDigest ||
+    !/^[a-f0-9]{64}$/u.test(input.authorityDigest)
+  )
+    throw new Error("Recoverable MCP dispatch identity does not match its trusted binding");
+  if (context.closed || context.captureStarted) {
+    throw new Error("MCP operation dispatch is already claimed or closed");
+  }
+  context.captureStarted = true;
+  const result = await context.persistence.capture({
+    ...operation,
+    authorityDigest: input.authorityDigest,
+  });
+  if (result !== "created")
+    throw new Error("MCP operation was already dispatched; read its existing result");
+  // The SDK may have timed out while capture was committing. Do not start a
+  // mutation after its enclosing execution has already returned.
+  if (context.closed) throw new Error("MCP operation dispatch closed during capture");
+  context.captured = true;
+}

package/src/mcp-operation-observation.ts

@@ -0,0 +1,148 @@
+import { AttemptToolResult } from "@opengeni/contracts";
+import { z } from "zod";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export type McpOperationObservationAuthority = {
+  serverId: string;
+  observerTool: string;
+  destinationDigest: string;
+  authorityDigest: string;
+};
+const observationAuthority = new AsyncLocalStorage<{
+  binding: McpOperationObservationAuthority;
+  closed: boolean;
+}>();
+
+/** Pin the actual broker request, not merely the earlier credential lookup. */
+export async function runMcpOperationObservationWithAuthority<T>(
+  binding: McpOperationObservationAuthority,
+  execute: () => Promise<T>,
+): Promise<T> {
+  const scope = { binding: { ...binding }, closed: false };
+  return await observationAuthority.run(scope, async () => {
+    try {
+      return await execute();
+    } finally {
+      scope.closed = true;
+    }
+  });
+}
+
+/** The caller is the credential broker, after live authorization and before
+ * physical tools/call dispatch. Unrelated ordinary calls remain unchanged. */
+export function assertMcpOperationObservationAuthority(actual: {
+  serverId: string;
+  toolName?: string;
+  destinationDigest: string;
+  authorityDigest?: string;
+}): void {
+  const scope = observationAuthority.getStore();
+  if (!scope) return;
+  const expected = scope.binding;
+  if (
+    scope.closed ||
+    actual.serverId !== expected.serverId ||
+    actual.toolName !== expected.observerTool ||
+    actual.destinationDigest !== expected.destinationDigest ||
+    actual.authorityDigest !== expected.authorityDigest
+  ) {
+    throw new Error("MCP operation observation authority changed before provider use");
+  }
+}
+
+const fingerprint = z
+  .object({
+    version: z.literal(1),
+    algorithm: z.literal("sha256"),
+    value: z.string().regex(/^[a-f0-9]{64}$/u),
+  })
+  .strict();
+
+const identity = {
+  version: z.literal(1),
+  operationRef: z.string().uuid(),
+  fingerprint,
+};
+
+const receiptSchema = z.discriminatedUnion("status", [
+  z.object({ ...identity, status: z.literal("unknown") }).strict(),
+  z
+    .object({
+      ...identity,
+      status: z.literal("pending"),
+      evidenceRevision: z.string().min(1),
+    })
+    .strict(),
+  z
+    .object({
+      ...identity,
+      status: z.literal("completed"),
+      receiptRevision: z
+        .string()
+        .min(1)
+        .refine((value) => Buffer.byteLength(value, "utf8") <= 1024, {
+          message: "MCP receipt revision must fit the ledger's 1024-byte identity field",
+        }),
+      result: AttemptToolResult,
+    })
+    .strict(),
+  z.object({ ...identity, status: z.literal("conflict") }).strict(),
+]);
+
+const bindingSchema = z
+  .object({
+    operationId: z.string().uuid(),
+    serverId: z.string().min(1),
+    originalTool: z.string().min(1),
+    observerTool: z.string().min(1),
+    argumentDigest: fingerprint.shape.value,
+  })
+  .strict()
+  .refine((value) => value.originalTool !== value.observerTool, {
+    message: "The observer must not be the original mutation tool",
+  });
+
+export type McpObservationBinding = z.infer<typeof bindingSchema>;
+export type McpObservationReceipt = z.infer<typeof receiptSchema>;
+
+/**
+ * One observation, never a mutation retry. This helper is deliberately not an
+ * authority resolver or a scheduler: its caller must load an immutable trusted
+ * binding and bind callObserver to that exact authorized provider destination.
+ * Tool annotations and model-supplied arguments cannot establish that trust.
+ *
+ * Durable settlement must additionally recheck authority under its own locks.
+ * A successful return alone is not a durable delivery or commit receipt.
+ */
+export async function observeMcpOperation(input: {
+  binding: McpObservationBinding;
+  authorize: (phase: "before_request" | "before_delivery") => Promise<boolean>;
+  callObserver: (tool: string, args: Record<string, unknown>) => Promise<unknown>;
+}): Promise<McpObservationReceipt> {
+  // Parse into a fresh object before callbacks can mutate the caller's input.
+  const binding = bindingSchema.parse(input.binding);
+  if (!(await input.authorize("before_request"))) {
+    throw new Error("MCP operation observation is not authorized");
+  }
+  const response = await input.callObserver(binding.observerTool, {
+    version: 1,
+    operationRef: binding.operationId,
+    originalTool: binding.originalTool,
+    fingerprint: { version: 1, algorithm: "sha256", value: binding.argumentDigest },
+  });
+  if (!(await input.authorize("before_delivery"))) {
+    throw new Error("MCP operation observation is not authorized for delivery");
+  }
+  const envelope = AttemptToolResult.parse(response);
+  if (envelope.isError) {
+    throw new Error("MCP operation observer returned an error, not a receipt");
+  }
+  const receipt = receiptSchema.parse(envelope.structuredContent);
+  if (
+    receipt.operationRef !== binding.operationId ||
+    receipt.fingerprint.value !== binding.argumentDigest
+  ) {
+    throw new Error("MCP operation observation receipt identity does not match");
+  }
+  return receipt;
+}

package/src/operational-instructions.ts

@@ -159,7 +159,7 @@ Skills are reusable instructions supplied dynamically for the current session. W
 
 Use \`session_events\` for conversation history: its default returns user and completed assistant messages, not execution noise. Cursors only paginate. Request \`results\` for final outcomes, \`tools\` for tool receipts, or \`debug\` for explicit diagnostics; request large tool bodies only when needed. Use the returned continuation cursor rather than rereading whole pages. Audit reads do not acknowledge command completion.
 
-For a yielded command, use \`command_read\` to read available output and status, or \`command_wait\` to wait briefly using the same command interface. Keep the command ID and output cursor. A terminal read suppresses any still-pending completion notification; a running read does not. Earlier tool results and delivered messages never change. Use \`command_input\` only to send input where supported, not to poll output. An unsupported input capability does not imply output is unavailable. Give foreground commands a realistic requested wait; an internal polling slice is not a reason to return a background handle.
+For a yielded command, use \`command_read\` to read available output and status, or \`command_wait\` to wait briefly using the same command interface. Keep the command ID and output cursor. A terminal read suppresses any still-pending completion notification; a running read does not. Earlier tool results and delivered messages never change. Use \`command_input\` only to send input where supported, not to poll output. An unsupported input capability does not imply output is unavailable. Give foreground commands a realistic requested wait; default to 10 seconds (yield_time_ms: 10000). An internal polling slice is not a reason to return a background handle.
 
 If the user asks to create, inspect, continue, pause, resume, steer, rename, or otherwise manage a session, use the corresponding session tool. Pause affects the selected workstream and its descendants: pausing an ancestor also stops you, so you cannot then Resume yourself. Coordinate disjoint edits through messages instead of ancestor Pause.
 

package/src/runtime-skills.ts

@@ -128,7 +128,7 @@ const emptyNativeToolSkillSet: NativeToolSkillSet = Object.freeze({
 export function loadNativeToolSkillArtifacts(
   nativeTools: NativeToolSkillSet & Readonly<{ projects?: boolean }>,
 ): readonly RuntimeSkillArtifact[] {
-  const directories: string[] = [];
+  const directories: string[] = ["bundled_default_skills"];
   if (nativeTools.projects) directories.push("bundled_project_skills");
   if (nativeTools.editableArtifacts) directories.push("bundled_artifact_skills");
   if (nativeTools.sites) directories.push("bundled_site_skills");
@@ -384,7 +384,12 @@ function nativeToolSkillSources(nativeTools: NativeToolSkillSet): Array<{
   names: string[];
   reason: string;
 }> {
-  const sources: Array<{ names: string[]; reason: string }> = [];
+  const sources: Array<{ names: string[]; reason: string }> = [
+    {
+      names: skillDirNames(packagedSkillDirectory("bundled_default_skills")),
+      reason: "included by default",
+    },
+  ];
   if (nativeTools.editableArtifacts) {
     sources.push({
       names: skillDirNames(packagedSkillDirectory("bundled_artifact_skills")),

package/src/sandbox/archive-spool.ts

@@ -0,0 +1,16 @@
+import type { TarWorkspaceArchiveDescriptor } from "@opengeni/contracts";
+
+/** Process-owned, reopenable archive bytes. Never persisted as a local path. */
+export type WorkspaceArchiveSpool = {
+  path: string;
+  byteSize: number;
+  sha256: string;
+  open: () => AsyncIterable<Uint8Array>;
+  dispose: () => Promise<void>;
+};
+
+export type VerifiedHostWorkspaceArchive = {
+  kind: "host_spool";
+  spool: WorkspaceArchiveSpool;
+  descriptor: TarWorkspaceArchiveDescriptor;
+};