@hachej/boring-agent 0.1.79 → 0.1.80

package/dist/{chunk-RFHSFIHF.js → chunk-URRIDA6O.js}

@@ -1,13 +1,18 @@
 import {
   AgentDefinitionValidationError,
+  AgentDeploymentValidationError,
+  OpaqueRefSchema,
+  Sha256DigestSchema,
   createAgentAssetDigest,
   createAgentDefinitionDigest,
+  createAgentDeploymentDigest,
   validateAgentDefinition,
+  validateAgentDeployment,
   validateTool
-} from "./chunk-Q42DWR3T.js";
+} from "./chunk-CUF7ELFO.js";
 import {
   createAgentRuntimeBridge
-} from "./chunk-LCEBDU6G.js";
+} from "./chunk-BNZIE26N.js";
 import {
   sessionStreamPath
 } from "./chunk-WSQ5QNIY.js";
@@ -22,7 +27,7 @@ import {
   StopReceiptSchema,
   extractToolUiMetadata,
   sanitizeToolUiMetadata2 as sanitizeToolUiMetadata
-} from "./chunk-P23XFC4W.js";
+} from "./chunk-UJQXCOHR.js";
 import {
   createLogger,
   createPiCodingAgentHarness,
@@ -33,14 +38,15 @@ import {
   registerConfiguredModelProviders,
   setEnvDefault,
   withPiHarnessDefaults
-} from "./chunk-X4WT3TPU.js";
+} from "./chunk-N4ES6PVX.js";
 import {
   safeCapture
 } from "./chunk-AQBXNPMD.js";
 import {
   AgentDefinitionErrorCode,
+  AgentDeploymentErrorCode,
   ErrorCode
-} from "./chunk-YVON2BHN.js";
+} from "./chunk-CCNXYCD5.js";
 
 // src/server/sandbox/direct/createDirectSandbox.ts
 import { spawn } from "child_process";
@@ -8446,11 +8452,12 @@ function createAgentRuntimeBridge2(config, options = {}) {
   }
   return createAgentRuntimeBridge({
     runtimeFactory: () => createRuntime(config, options),
+    readiness: config.readiness,
     readinessRequirements: config.readinessRequirements
   });
 }
 async function createRuntime(config, options) {
-  const harnessFactory = config.harnessFactory ?? (await import("./createHarness-XHMR3QN3.js")).createPiCodingAgentHarness;
+  const harnessFactory = config.harnessFactory ?? (await import("./createHarness-EEA63XRC.js")).createPiCodingAgentHarness;
   const harnessInput = {
     tools: config.tools ?? [],
     cwd: config.workdir ?? DEFAULT_WORKDIR,
@@ -8702,15 +8709,140 @@ async function compileAgentDirectory(directory) {
   return Object.freeze({ definition, definitionDigest, assets });
 }
 
+// src/server/agentDefinition/resolveAgentDeployment.ts
+import { z } from "zod";
+var AuthorizedAgentDeploymentBindingSchema = z.object({
+  workspaceId: OpaqueRefSchema,
+  defaultDeploymentId: OpaqueRefSchema,
+  workspaceCompositionDigest: Sha256DigestSchema
+});
+var RESOLVED_AGENT_DIGEST_DOMAIN = "boring-agent/resolved-agent:v1";
+function invalidDefinition(field, message) {
+  return new AgentDefinitionValidationError({
+    code: AgentDefinitionErrorCode.enum.AGENT_DEFINITION_INVALID,
+    field,
+    message
+  });
+}
+function invalidDeployment(field, message) {
+  return new AgentDeploymentValidationError({
+    code: AgentDeploymentErrorCode.enum.AGENT_DEPLOYMENT_INVALID,
+    field,
+    message
+  });
+}
+function parseBinding(raw) {
+  const parsed = AuthorizedAgentDeploymentBindingSchema.safeParse(raw);
+  if (parsed.success) return parsed.data;
+  const issue = parsed.error.issues[0];
+  const field = issue.path[0];
+  const bindingField = typeof field === "string" ? field : "workspaceId";
+  throw invalidDeployment(bindingField, `${bindingField} ${issue.message}`);
+}
+function assertEqual(actual, expected, field) {
+  if (actual !== expected) {
+    throw invalidDeployment(field, `${field} does not match the compiled agent bundle`);
+  }
+}
+async function resolveAgentDeployment(bundle, deployment, authorizedBinding) {
+  const binding = parseBinding(authorizedBinding);
+  const definitionDigest = await createAgentDefinitionDigest({
+    definition: bundle.definition,
+    assets: bundle.assets
+  });
+  if (definitionDigest !== bundle.definitionDigest) {
+    throw invalidDefinition(
+      "definitionDigest",
+      "definitionDigest does not match the compiled agent bundle"
+    );
+  }
+  const validatedDeployment = validateAgentDeployment(deployment);
+  if (!validatedDeployment.valid) {
+    throw new AgentDeploymentValidationError(validatedDeployment.issues[0]);
+  }
+  const deploymentSnapshot = validatedDeployment.value;
+  const deploymentDigest = await createAgentDeploymentDigest(deploymentSnapshot);
+  assertEqual(
+    deploymentSnapshot.definition.definitionId,
+    bundle.definition.definitionId,
+    "definition.definitionId"
+  );
+  assertEqual(
+    deploymentSnapshot.definition.version,
+    bundle.definition.version,
+    "definition.version"
+  );
+  assertEqual(deploymentSnapshot.definition.digest, definitionDigest, "definition.digest");
+  if (deploymentSnapshot.agentId !== "default") {
+    throw invalidDeployment("agentId", "agentId must be default in schema version 1");
+  }
+  if (binding.defaultDeploymentId !== deploymentSnapshot.deploymentId) {
+    throw invalidDeployment(
+      "defaultDeploymentId",
+      "defaultDeploymentId does not match the resolved deployment"
+    );
+  }
+  const instructions = bundle.assets.find(
+    (asset) => asset.path === bundle.definition.instructionsRef
+  );
+  if (instructions === void 0) {
+    throw invalidDefinition(
+      "instructionsRef",
+      "instructionsRef must name an included verified asset"
+    );
+  }
+  const resolvedDigest = await createAgentAssetDigest(JSON.stringify({
+    domain: RESOLVED_AGENT_DIGEST_DOMAIN,
+    workspaceId: binding.workspaceId,
+    defaultDeploymentId: binding.defaultDeploymentId,
+    workspaceCompositionDigest: binding.workspaceCompositionDigest,
+    definitionDigest,
+    deploymentDigest
+  }));
+  const workspace = Object.freeze({
+    workspaceId: binding.workspaceId,
+    defaultDeploymentId: binding.defaultDeploymentId,
+    compositionDigest: binding.workspaceCompositionDigest
+  });
+  const resolvedDeployment = Object.freeze({
+    deploymentId: deploymentSnapshot.deploymentId,
+    version: deploymentSnapshot.version,
+    agentId: deploymentSnapshot.agentId,
+    digest: deploymentDigest
+  });
+  const definition = Object.freeze({
+    definitionId: bundle.definition.definitionId,
+    version: bundle.definition.version,
+    digest: definitionDigest,
+    instructionsRef: bundle.definition.instructionsRef
+  });
+  const resolvedInstructions = Object.freeze({
+    ref: bundle.definition.instructionsRef,
+    content: instructions.content
+  });
+  return Object.freeze({
+    workspace,
+    deployment: resolvedDeployment,
+    definition,
+    instructions: resolvedInstructions,
+    resolvedDigest
+  });
+}
+
 // src/server/mcp/managedAgentDelegate.ts
-import { randomUUID } from "crypto";
+import { createHash as createHash6, randomUUID } from "crypto";
 var MANAGED_AGENT_MCP_ORIGIN_SURFACE = "mcp-managed-agent";
-var MANAGED_AGENT_MCP_DELIVERY_RULE = "M1-pr1 DELIVERY v0: delegate_task returns final assistant text and artifact file references only; share-link delivery is gated on PR #424.";
-var DEFAULT_MAX_BRIEF_CHARS = 12e3;
-var DEFAULT_MAX_INLINE_ARTIFACT_CONTENT_CHARS = 8e3;
+var MANAGED_AGENT_MCP_DELIVERY_RULE = "M1 DELIVERY v0: delegate_task returns bounded final assistant text and at most one complete authorized inline Markdown artifact; no artifact paths, truncation, or share-link delivery.";
+var MAX_FINAL_ASSISTANT_TEXT_BYTES = 96 * 1024;
+var MAX_ARTIFACT_BYTES = 256 * 1024;
+var MAX_SERIALIZED_RESULT_BYTES = 384 * 1024;
+var MARKDOWN_MEDIA_TYPE = "text/markdown";
+var DEFAULT_MAX_BRIEF_BYTES = 32 * 1024;
 var DEFAULT_TERMINAL_RETENTION_MS = 15 * 6e4;
 var DEFAULT_MAX_DELEGATIONS = 100;
 var MAX_RETAINED_PROGRESS = 100;
+var utf8Encoder = new TextEncoder();
+var strictUtf8Decoder = new TextDecoder("utf-8", { fatal: true });
 var ManagedAgentMcpError = class extends Error {
   code;
   constructor(code, message) {
@@ -8724,8 +8856,8 @@ var ManagedAgentMcpDelegateController = class {
     this.options = options;
     this.createDelegationId = options.createDelegationId ?? randomUUID;
     this.now = options.now ?? (() => /* @__PURE__ */ new Date());
-    this.maxBriefChars = options.maxBriefChars ?? DEFAULT_MAX_BRIEF_CHARS;
-    this.maxInlineArtifactContentChars = options.maxInlineArtifactContentChars ?? DEFAULT_MAX_INLINE_ARTIFACT_CONTENT_CHARS;
+    this.maxBriefBytes = options.maxBriefBytes ?? DEFAULT_MAX_BRIEF_BYTES;
+    this.maxBriefChars = options.maxBriefChars;
     this.terminalRetentionMs = Math.max(0, options.terminalRetentionMs ?? DEFAULT_TERMINAL_RETENTION_MS);
     this.maxDelegations = Math.max(1, Math.floor(options.maxDelegations ?? DEFAULT_MAX_DELEGATIONS));
     this.redactionCanaries = options.redactionCanaries ?? [];
@@ -8734,8 +8866,8 @@ var ManagedAgentMcpDelegateController = class {
   delegations = /* @__PURE__ */ new Map();
   createDelegationId;
   now;
+  maxBriefBytes;
   maxBriefChars;
-  maxInlineArtifactContentChars;
   terminalRetentionMs;
   maxDelegations;
   redactionCanaries;
@@ -8755,19 +8887,13 @@ var ManagedAgentMcpDelegateController = class {
       await input.onDelegationCreated?.(this.getStatus(delegationId, ctx));
       this.assertNotAborted(input.signal);
       const actor = await this.resolveActor(brief, ctx, request);
-      const receipt = await this.options.agent.start({
-        content: brief,
-        actor,
-        ctx,
-        originSurface: MANAGED_AGENT_MCP_ORIGIN_SURFACE
-      });
-      if (input.signal?.aborted) {
-        await this.stopDelegatedSession(receipt.sessionId, ctx);
-        throw new ManagedAgentMcpError(ErrorCode.enum.ABORTED, "delegation was cancelled");
-      }
+      const bound = await this.resolveRunnerWorkspace(brief, ctx, request, actor);
+      this.assertNotAborted(input.signal);
+      let activeSessionId;
       let abortStopPromise;
       const abortListener = () => {
-        abortStopPromise ??= this.stopDelegatedSession(receipt.sessionId, ctx);
+        if (!activeSessionId) return;
+        abortStopPromise ??= this.stopDelegatedSession(bound.runner, activeSessionId, ctx);
       };
       input.signal?.addEventListener("abort", abortListener, { once: true });
       await this.pushProgress(record, "agent-started", "Agent session accepted for delegated task.", input.onProgress);
@@ -8775,11 +8901,21 @@ var ManagedAgentMcpDelegateController = class {
       let terminal = false;
       let terminalStatus;
       try {
-        for await (const event of this.options.agent.stream(receipt.sessionId, { startIndex: receipt.startIndex, ctx })) {
+        for await (const event of bound.runner.run({
+          brief,
+          ctx,
+          request,
+          actor,
+          signal: input.signal,
+          onSessionStarted: (sessionId) => {
+            activeSessionId = sessionId;
+          }
+        })) {
           if (input.signal?.aborted) {
             await abortStopPromise;
             throw new ManagedAgentMcpError(ErrorCode.enum.ABORTED, "delegation was cancelled");
           }
+          activeSessionId = event.sessionId;
           events.push(event);
           await this.observeEvent(record, event, input.onProgress);
           if (isTerminalAgentEvent(event)) {
@@ -8801,20 +8937,21 @@ var ManagedAgentMcpDelegateController = class {
       if (terminalStatus !== "ok") {
         throw terminalError(terminalStatus, events);
       }
-      const finalAssistantText = extractFinalAssistantText(events);
+      const finalAssistantText = this.validateFinalAssistantText(extractFinalAssistantText(events));
       const artifacts = await this.collectArtifacts({
         delegationId,
-        sessionId: receipt.sessionId,
+        sessionId: activeSessionId ?? "",
         ctx,
+        request,
         finalAssistantText,
         events
-      });
+      }, bound.workspace);
       const result = {
         delegationId,
         status: "completed",
         finalAssistantText,
-        artifacts,
-        deliveryRule: MANAGED_AGENT_MCP_DELIVERY_RULE
+        deliveryRule: MANAGED_AGENT_MCP_DELIVERY_RULE,
+        ...artifacts[0] ? { artifact: artifacts[0] } : {}
       };
       this.assertPublicPayloadSafe(result);
       record.result = result;
@@ -8896,9 +9033,12 @@ var ManagedAgentMcpDelegateController = class {
     if (typeof value !== "string") throw new ManagedAgentMcpError(ErrorCode.enum.TOOL_INVALID_INPUT, "brief must be a string");
     const brief = value.trim();
     if (!brief) throw new ManagedAgentMcpError(ErrorCode.enum.TOOL_INVALID_INPUT, "brief is required");
-    if (brief.length > this.maxBriefChars) {
+    if (this.maxBriefChars !== void 0 && brief.length > this.maxBriefChars) {
       throw new ManagedAgentMcpError(ErrorCode.enum.TOOL_INVALID_INPUT, `brief must be ${this.maxBriefChars} characters or fewer`);
     }
+    if (utf8ByteLength(brief) > this.maxBriefBytes) {
+      throw new ManagedAgentMcpError(ErrorCode.enum.TOOL_INVALID_INPUT, `brief must be ${this.maxBriefBytes} UTF-8 bytes or fewer`);
+    }
     return brief;
   }
   async resolveSessionCtx(brief, request) {
@@ -8911,11 +9051,56 @@ var ManagedAgentMcpDelegateController = class {
     }
     return { workspaceId: ctx.workspaceId, userId: ctx.userId };
   }
+  async resolveWorkspace(brief, ctx, request) {
+    const resolveWorkspace = this.options.resolveWorkspace;
+    if (!resolveWorkspace) {
+      throw new ManagedAgentMcpError(ErrorCode.enum.CONFIG_INVALID, "MCP delegate requires a host-resolved Workspace");
+    }
+    const workspace = await resolveWorkspace({ brief, ctx, request });
+    if (!workspace || typeof workspace.stat !== "function" || typeof workspace.readFile !== "function") {
+      throw new ManagedAgentMcpError(ErrorCode.enum.CONFIG_INVALID, "MCP delegate requires a host-resolved Workspace");
+    }
+    return workspace;
+  }
+  async resolveRunnerWorkspace(brief, ctx, request, actor) {
+    const resolved = this.options.resolveRunnerWorkspace ? await this.options.resolveRunnerWorkspace({ brief, ctx, request, actor }) : {
+      runner: this.createAgentDelegateRunner(),
+      workspace: await this.resolveWorkspace(brief, ctx, request)
+    };
+    if (!resolved || !resolved.runner || typeof resolved.runner.run !== "function") {
+      throw new ManagedAgentMcpError(ErrorCode.enum.CONFIG_INVALID, "MCP delegate requires a host-resolved runner");
+    }
+    if (!resolved.workspace || typeof resolved.workspace.stat !== "function" || typeof resolved.workspace.readFile !== "function") {
+      throw new ManagedAgentMcpError(ErrorCode.enum.CONFIG_INVALID, "MCP delegate requires a host-resolved Workspace");
+    }
+    return resolved;
+  }
+  createAgentDelegateRunner() {
+    const agent = this.options.agent;
+    if (!agent) {
+      throw new ManagedAgentMcpError(ErrorCode.enum.CONFIG_INVALID, "MCP delegate requires a host-resolved runner");
+    }
+    return {
+      async *run(input) {
+        const receipt = await agent.start({
+          content: input.brief,
+          actor: input.actor,
+          ctx: input.ctx,
+          originSurface: MANAGED_AGENT_MCP_ORIGIN_SURFACE
+        });
+        input.onSessionStarted?.(receipt.sessionId);
+        yield* agent.stream(receipt.sessionId, { startIndex: receipt.startIndex, ctx: input.ctx });
+      },
+      async stop(sessionId, ctx) {
+        await agent.stop(sessionId, ctx);
+      }
+    };
+  }
   assertNotAborted(signal) {
     if (signal?.aborted) throw new ManagedAgentMcpError(ErrorCode.enum.ABORTED, "delegation was cancelled");
   }
-  async stopDelegatedSession(sessionId, ctx) {
-    await this.options.agent.stop(sessionId, ctx).catch(() => void 0);
+  async stopDelegatedSession(runner, sessionId, ctx) {
+    await Promise.resolve(runner.stop?.(sessionId, ctx)).catch(() => void 0);
   }
   async resolveActor(brief, ctx, request) {
     const actor = await this.options.resolveActor?.({ brief, ctx, request });
@@ -8943,13 +9128,40 @@ var ManagedAgentMcpDelegateController = class {
     } catch {
     }
   }
-  async collectArtifacts(input) {
+  validateFinalAssistantText(value) {
+    const byteSize = utf8ByteLength(value);
+    if (byteSize > MAX_FINAL_ASSISTANT_TEXT_BYTES) {
+      throw new ManagedAgentMcpError(
+        ErrorCode.enum.MCP_AGENT_ARTIFACT_TOO_LARGE,
+        `final assistant text must be ${MAX_FINAL_ASSISTANT_TEXT_BYTES} bytes or fewer`
+      );
+    }
+    if (looksLikeSinglePath(value)) {
+      throw new ManagedAgentMcpError(
+        ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID,
+        "final assistant text must not be only an artifact path"
+      );
+    }
+    return value;
+  }
+  async collectArtifacts(input, workspace) {
     const supplied = await this.options.collectArtifacts?.(input);
-    const artifacts = (supplied ?? extractArtifactRefs(input.events)).map(
-      (artifact) => normalizeArtifactRef(artifact, this.maxInlineArtifactContentChars)
-    );
-    this.assertPublicPayloadSafe(artifacts);
-    return artifacts;
+    const rawCandidates = supplied ?? extractArtifactRefs(input.events);
+    if (!Array.isArray(rawCandidates)) {
+      throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact references must be an array");
+    }
+    const candidates = rawCandidates.map((artifact2) => normalizeArtifactCandidate(artifact2));
+    this.assertPublicPayloadSafe(candidates);
+    if (candidates.length === 0) return [];
+    if (candidates.length > 1) {
+      throw new ManagedAgentMcpError(
+        ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID,
+        "MCP delegate delivery supports at most one artifact"
+      );
+    }
+    const artifact = await resolveMarkdownArtifact(candidates[0], workspace);
+    this.assertPublicPayloadSafe(artifact);
+    return [artifact];
   }
   toSafeError(error) {
     if (error instanceof ManagedAgentMcpError) {
@@ -8962,6 +9174,12 @@ var ManagedAgentMcpDelegateController = class {
   }
   assertPublicPayloadSafe(payload) {
     const serialized = JSON.stringify(payload);
+    if (utf8ByteLength(serialized) > MAX_SERIALIZED_RESULT_BYTES) {
+      throw new ManagedAgentMcpError(
+        ErrorCode.enum.MCP_AGENT_ARTIFACT_TOO_LARGE,
+        `MCP delegate result must be ${MAX_SERIALIZED_RESULT_BYTES} bytes or fewer`
+      );
+    }
     if (this.containsSecret(serialized)) {
       throw new ManagedAgentMcpError(ErrorCode.enum.INTERNAL_ERROR, "MCP delegate payload failed secret redaction guard");
     }
@@ -9052,39 +9270,178 @@ function extractArtifactRefs(events) {
   }
   return artifacts;
 }
-function normalizeArtifactRef(artifact, maxInlineArtifactContentChars) {
-  const path4 = normalizeArtifactPath(artifact.path);
-  const normalized = {
+function normalizeArtifactCandidate(artifact) {
+  if (!artifact || typeof artifact !== "object") {
+    throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact reference is invalid");
+  }
+  const record = artifact;
+  if (record.content !== void 0) {
+    throw new ManagedAgentMcpError(
+      ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID,
+      "artifact content must be resolved through the authorized workspace"
+    );
+  }
+  if (record.truncated !== void 0) {
+    throw new ManagedAgentMcpError(
+      ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID,
+      "artifact content must be complete and untruncated"
+    );
+  }
+  const path4 = normalizeArtifactPath(record.path);
+  const mediaType = optionalNonEmptyString(record.mediaType);
+  if (mediaType !== void 0 && mediaType.toLowerCase().split(";", 1)[0]?.trim() !== MARKDOWN_MEDIA_TYPE) {
+    throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact must be Markdown");
+  }
+  if (mediaType === void 0 && !isMarkdownPath(path4)) {
+    throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact must be Markdown");
+  }
+  const candidate = {
     path: path4,
-    mediaType: optionalNonEmptyString(artifact.mediaType),
-    title: optionalNonEmptyString(artifact.title)
+    mediaType: MARKDOWN_MEDIA_TYPE
   };
-  if (artifact.content !== void 0) {
-    if (typeof artifact.content !== "string") {
-      throw new ManagedAgentMcpError(ErrorCode.enum.INTERNAL_ERROR, "artifact content must be text");
-    }
-    if (artifact.content.length <= maxInlineArtifactContentChars) {
-      normalized.content = artifact.content;
-    } else {
-      normalized.truncated = true;
-    }
-  }
-  if (artifact.truncated === true) normalized.truncated = true;
-  return normalized;
+  const title = optionalNonEmptyString(record.title);
+  if (title !== void 0) candidate.title = title;
+  return candidate;
 }
 function normalizeArtifactPath(path4) {
-  if (typeof path4 !== "string") throw new ManagedAgentMcpError(ErrorCode.enum.INTERNAL_ERROR, "artifact path must be a string");
+  if (typeof path4 !== "string") throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact path must be a string");
   const trimmed = path4.trim();
-  if (!trimmed) throw new ManagedAgentMcpError(ErrorCode.enum.INTERNAL_ERROR, "artifact path is required");
-  if (trimmed.includes("\0")) throw new ManagedAgentMcpError(ErrorCode.enum.INTERNAL_ERROR, "artifact path is invalid");
-  if (trimmed.startsWith("/") || /^[A-Za-z]:[\\/]/.test(trimmed)) {
-    throw new ManagedAgentMcpError(ErrorCode.enum.INTERNAL_ERROR, "artifact path must be workspace-relative");
+  if (!trimmed) throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact path is required");
+  if (trimmed.includes("\0")) throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact path is invalid");
+  const decoded = safeDecodeArtifactPath(trimmed);
+  const traversalCandidate = decoded.replace(/\\/g, "/");
+  if (trimmed.startsWith("/") || traversalCandidate.startsWith("/") || /^[A-Za-z]:[\\/]/.test(trimmed) || /^[A-Za-z]:[\\/]/.test(traversalCandidate) || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(trimmed)) {
+    throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact path must be workspace-relative");
+  }
+  const parts = traversalCandidate.split("/");
+  if (traversalCandidate.startsWith("~") || traversalCandidate.startsWith("$") || /[\r\n]/.test(traversalCandidate) || parts.some((part) => part === ".." || part.startsWith(".."))) {
+    throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact path must stay within the workspace");
+  }
+  const normalized = parts.filter((part) => part && part !== ".").join("/");
+  if (!normalized) throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact path is required");
+  return normalized;
+}
+async function resolveMarkdownArtifact(candidate, workspace) {
+  const { content, bytes, byteSize } = await readStableArtifact(candidate.path, workspace);
+  validateMarkdownContent(content);
+  const artifact = {
+    content,
+    sha256: sha256(bytes),
+    byteSize,
+    mediaType: MARKDOWN_MEDIA_TYPE,
+    ...candidate.title ? { title: candidate.title } : {}
+  };
+  return artifact;
+}
+async function readStableArtifact(path4, workspace) {
+  const before = await statArtifact(workspace, path4);
+  assertArtifactStat(before);
+  if (before.size > MAX_ARTIFACT_BYTES) {
+    throw new ManagedAgentMcpError(
+      ErrorCode.enum.MCP_AGENT_ARTIFACT_TOO_LARGE,
+      `artifact must be ${MAX_ARTIFACT_BYTES} bytes or fewer`
+    );
+  }
+  const read = await readArtifactContent(workspace, path4);
+  const after = await statArtifact(workspace, path4);
+  assertArtifactStat(after);
+  if (!sameStat(before, after) || read.byteSize !== before.size) {
+    throw new ManagedAgentMcpError(
+      ErrorCode.enum.MCP_AGENT_ARTIFACT_UNAVAILABLE,
+      "artifact changed while it was being read"
+    );
+  }
+  if (read.byteSize > MAX_ARTIFACT_BYTES) {
+    throw new ManagedAgentMcpError(
+      ErrorCode.enum.MCP_AGENT_ARTIFACT_TOO_LARGE,
+      `artifact must be ${MAX_ARTIFACT_BYTES} bytes or fewer`
+    );
+  }
+  return read;
+}
+async function statArtifact(workspace, path4) {
+  try {
+    return await workspace.stat(path4);
+  } catch (error) {
+    throw artifactReadError(error);
+  }
+}
+function assertArtifactStat(stat13) {
+  if (stat13.kind !== "file") {
+    throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact must be a file");
+  }
+  if (!Number.isFinite(stat13.size) || stat13.size < 0) {
+    throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact size is invalid");
+  }
+}
+async function readArtifactContent(workspace, path4) {
+  try {
+    if (!workspace.readBinaryFile) {
+      throw new ManagedAgentMcpError(
+        ErrorCode.enum.MCP_AGENT_ARTIFACT_UNAVAILABLE,
+        "artifact bytes are unavailable through the authorized workspace"
+      );
+    }
+    const bytes = await workspace.readBinaryFile(path4);
+    const content = decodeUtf82(bytes);
+    return { content, bytes, byteSize: bytes.byteLength };
+  } catch (error) {
+    if (error instanceof ManagedAgentMcpError) throw error;
+    throw artifactReadError(error);
   }
-  const parts = trimmed.split(/[\\/]+/);
-  if (parts.some((part) => part === "..")) {
-    throw new ManagedAgentMcpError(ErrorCode.enum.INTERNAL_ERROR, "artifact path must stay within the workspace");
+}
+function artifactReadError(error) {
+  const code = error?.code;
+  const reason = error?.reason;
+  if (code === ErrorCode.enum.PATH_ESCAPE || code === ErrorCode.enum.PATH_ABSOLUTE || code === ErrorCode.enum.PATH_NULL_BYTE || code === ErrorCode.enum.PATH_SYMLINK_ESCAPE || reason === "path-escape" || reason === "absolute-path" || reason === "null-byte" || reason === "symlink-escape") {
+    return new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact path is invalid");
+  }
+  return new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_UNAVAILABLE, "artifact is unavailable");
+}
+function decodeUtf82(bytes) {
+  try {
+    return strictUtf8Decoder.decode(bytes);
+  } catch {
+    throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact must be well-formed UTF-8");
   }
-  return parts.filter((part) => part && part !== ".").join("/");
+}
+function validateMarkdownContent(content) {
+  if (!content.trim()) {
+    throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact Markdown must not be empty");
+  }
+  for (let index = 0; index < content.length; index += 1) {
+    const code = content.charCodeAt(index);
+    if (code === 0 || code < 32 && code !== 9 && code !== 10 && code !== 13) {
+      throw new ManagedAgentMcpError(ErrorCode.enum.MCP_AGENT_ARTIFACT_INVALID, "artifact must be text Markdown");
+    }
+  }
+}
+function sameStat(left, right) {
+  return left.kind === right.kind && left.size === right.size && left.mtimeMs === right.mtimeMs;
+}
+function sha256(bytes) {
+  return `sha256:${createHash6("sha256").update(bytes).digest("hex")}`;
+}
+function safeDecodeArtifactPath(path4) {
+  try {
+    return decodeURIComponent(path4);
+  } catch {
+    return path4;
+  }
+}
+function utf8ByteLength(value) {
+  return utf8Encoder.encode(value).byteLength;
+}
+function isMarkdownPath(path4) {
+  return /\.(md|markdown)$/i.test(path4);
+}
+function looksLikeSinglePath(value) {
+  const trimmed = value.trim();
+  if (!trimmed || /\s/.test(trimmed)) return false;
+  if (!isMarkdownPath(trimmed)) return false;
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(trimmed)) return true;
+  if (trimmed.startsWith("/") || /^[A-Za-z]:[\\/]/.test(trimmed)) return true;
+  return trimmed.includes("/") || trimmed.includes("\\");
 }
 function optionalNonEmptyString(value) {
   if (value === void 0) return void 0;
@@ -9099,18 +9456,21 @@ function sameSessionCtx(a, b) {
 // src/server/mcp/managedAgentMcpServer.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { z } from "zod";
-var DEFAULT_MAX_BRIEF_CHARS2 = 12e3;
+import { z as z2 } from "zod";
+var DEFAULT_MAX_BRIEF_SCHEMA_CHARS = 32 * 1024;
 var delegateTaskStatusInputSchema = {
-  delegationId: z.string().min(1)
+  delegationId: z2.string().min(1)
 };
-function createManagedAgentMcpServer(options, controller = createManagedAgentMcpDelegateController(options)) {
+function createManagedAgentMcpServer(options) {
+  return createManagedAgentMcpServerWithController(options, createManagedAgentMcpDelegateController(options));
+}
+function createManagedAgentMcpServerWithController(options, controller) {
   const server = new McpServer({
     name: options.name ?? "boring-managed-agent",
     version: options.version ?? "0.0.0"
   });
   const registerTool = server.registerTool.bind(server);
-  const delegateTaskInputSchema = createDelegateTaskInputSchema(options.maxBriefChars ?? DEFAULT_MAX_BRIEF_CHARS2);
+  const delegateTaskInputSchema = createDelegateTaskInputSchema(options.maxBriefChars ?? DEFAULT_MAX_BRIEF_SCHEMA_CHARS);
   registerTool(
     "delegate_task",
     {
@@ -9186,7 +9546,7 @@ function createManagedAgentMcpServer(options, controller = createManagedAgentMcp
 function createManagedAgentMcpHttpHandler(options) {
   const controller = options.controller ?? createManagedAgentMcpDelegateController(options);
   return async (req, res, parsedBody) => {
-    const server = createManagedAgentMcpServer(options, controller);
+    const server = createManagedAgentMcpServerWithController(options, controller);
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: void 0,
       enableJsonResponse: false
@@ -9207,7 +9567,7 @@ function requestContextFromExtra(extra) {
 }
 function createDelegateTaskInputSchema(maxBriefChars) {
   return {
-    brief: z.string().min(1).max(maxBriefChars)
+    brief: z2.string().min(1).max(maxBriefChars)
   };
 }
 async function sendMcpProgress(extra, progress, message) {
@@ -11420,26 +11780,26 @@ function skillsRoutes(app, opts, done) {
 
 // src/server/http/routes/piChat.ts
 import { PassThrough } from "stream";
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 var DEFAULT_WORKSPACE_ID2 = "default";
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 25e3;
 var DEFAULT_SESSION_LIST_LIMIT = 50;
 var MAX_SESSION_LIST_LIMIT = 100;
 var SAFE_SESSION_LIST_INCLUDE_ID = /^[a-zA-Z0-9_-]{1,128}$/;
-var SessionParamsSchema = z2.object({
-  sessionId: z2.string().min(1).max(128)
+var SessionParamsSchema = z3.object({
+  sessionId: z3.string().min(1).max(128)
 });
-var CursorValueSchema = z2.preprocess((value) => {
+var CursorValueSchema = z3.preprocess((value) => {
   if (value === void 0) return 0;
   if (typeof value === "string" && value.length > 0) return Number(value);
   return value;
-}, z2.number().int().nonnegative());
-var EventsQuerySchema = z2.object({
+}, z3.number().int().nonnegative());
+var EventsQuerySchema = z3.object({
   cursor: CursorValueSchema
 });
-var EmptyBodySchema = z2.preprocess((value) => value ?? {}, z2.object({}).strict());
-var CreateSessionBodySchema = z2.preprocess((value) => value ?? {}, z2.object({
-  title: z2.string().min(1).max(200).optional()
+var EmptyBodySchema = z3.preprocess((value) => value ?? {}, z3.object({}).strict());
+var CreateSessionBodySchema = z3.preprocess((value) => value ?? {}, z3.object({
+  title: z3.string().min(1).max(200).optional()
 }).strict());
 var PiChatRouteError = class extends Error {
   statusCode;
@@ -12402,6 +12762,92 @@ function createWorkspaceAgentDispatcherError(code, message, statusCode) {
   return error;
 }
 
+// src/server/agentReadiness.ts
+var READINESS_PROBE_TOOL = {
+  name: "agent_readiness_probe",
+  description: "Internal readiness probe.",
+  parameters: { type: "object", properties: {} },
+  async execute() {
+    return { content: [] };
+  }
+};
+function collectToolReadinessRequirements(tools) {
+  const requirements = /* @__PURE__ */ new Set();
+  for (const tool of tools) {
+    for (const requirement of tool.readinessRequirements ?? []) requirements.add(requirement);
+  }
+  return [...requirements];
+}
+function createAgentReadinessFromTracker(options) {
+  const requirements = [...new Set(options.requirements)];
+  return {
+    requirements,
+    async status() {
+      return requirements.map((requirement) => readinessStatusForRequirement(requirement, options));
+    }
+  };
+}
+function readinessStatusForRequirement(requirement, options) {
+  const snapshot = options.tracker.getReadiness();
+  if (requirement === "workspace-fs") {
+    return statusFromCapability(requirement, snapshot.capabilities.workspace, ErrorCode.enum.WORKSPACE_NOT_READY);
+  }
+  if (requirement === "sandbox-exec") {
+    return snapshot.sandboxReady ? { key: requirement, ready: true, state: "ready" } : {
+      key: requirement,
+      ready: false,
+      state: "preparing",
+      errorCode: ErrorCode.enum.SANDBOX_NOT_READY,
+      retryable: true
+    };
+  }
+  if (isRuntimeReadinessRequirement(requirement)) {
+    const status = statusFromCapability(
+      requirement,
+      snapshot.capabilities.runtimeDependencies,
+      ErrorCode.enum.AGENT_RUNTIME_NOT_READY
+    );
+    if (status.ready || !options.checkReadiness) return status;
+    return enrichRuntimeStatus(
+      status,
+      options.checkReadiness(requirement, READINESS_PROBE_TOOL)
+    );
+  }
+  return { key: requirement, ready: false };
+}
+function enrichRuntimeStatus(status, readiness) {
+  if (readiness === true || typeof readiness === "object" && readiness !== null && readiness.ready === true) {
+    return status;
+  }
+  if (readiness === false) {
+    return { ...status, retryable: status.retryable ?? true };
+  }
+  return {
+    ...status,
+    ...readiness.errorCode ? { errorCode: readiness.errorCode } : {},
+    ...readiness.causeCode ? { causeCode: readiness.causeCode } : {},
+    ...readiness.message ? { message: readiness.message } : {},
+    ...readiness.workspaceId ? { workspaceId: readiness.workspaceId } : {},
+    retryable: readiness.retryable ?? status.retryable ?? true
+  };
+}
+function statusFromCapability(key, detail, fallbackErrorCode) {
+  const ready = detail.state === "ready";
+  const errorCode = detail.errorCode ?? (detail.state === "failed" && isRuntimeReadinessRequirement(key) ? ErrorCode.enum.RUNTIME_PROVISIONING_FAILED : fallbackErrorCode);
+  return {
+    key,
+    ready,
+    state: detail.state,
+    ...!ready ? { errorCode } : {},
+    ...detail.causeCode ? { causeCode: detail.causeCode } : {},
+    ...detail.message ? { message: detail.message } : {},
+    ...detail.retryable !== void 0 ? { retryable: detail.retryable } : {}
+  };
+}
+function isRuntimeReadinessRequirement(requirement) {
+  return requirement === "runtime-dependencies" || requirement.startsWith("runtime:");
+}
+
 // src/server/createAgentApp.ts
 var DEFAULT_VERSION = "0.1.0-dev";
 var DEFAULT_SESSION_ID = "default";
@@ -12553,9 +12999,16 @@ async function createWorkspaceAgentAppProfile(opts, sessionId, resolvedMode, app
     sessionRoot: opts.sessionRoot,
     sessionDir: opts.sessionDir ?? input.sessionDir
   }));
+  const readyTracker = createRuntimeReadyStatusTracker(modeAdapter, {
+    harnessReady: true
+  });
   const coreAgent = createAgentRuntimeBridge2({
     runtime: modeAdapter,
     tools,
+    readiness: createAgentReadinessFromTracker({
+      requirements: collectToolReadinessRequirements(tools),
+      tracker: readyTracker
+    }),
     harnessFactory,
     systemPromptAppend: opts.systemPromptAppend,
     systemPromptDynamic: opts.systemPromptDynamic,
@@ -12573,9 +13026,6 @@ async function createWorkspaceAgentAppProfile(opts, sessionId, resolvedMode, app
   opts.onWorkspaceAgentDispatcher?.(createStaticWorkspaceAgentDispatcherResolver(coreAgent.agent, sessionId));
   const harness = agentRuntime.harness;
   harnessRef = harness;
-  const readyTracker = createRuntimeReadyStatusTracker(modeAdapter, {
-    harnessReady: true
-  });
   const filesystemBindingsForRequest = opts.getFilesystemBindings ? (request) => {
     const user = request.user;
     return opts.getFilesystemBindings?.({
@@ -13194,7 +13644,7 @@ function createRuntimeProvisioningFailedError(workspaceId, cause) {
     }
   );
 }
-function isRuntimeReadinessRequirement(requirement) {
+function isRuntimeReadinessRequirement2(requirement) {
   return requirement === "runtime-dependencies" || requirement.startsWith("runtime:");
 }
 function causeCodeFrom(error) {
@@ -13203,7 +13653,7 @@ function causeCodeFrom(error) {
 }
 function createRuntimeReadinessCheck(workspaceId, getRuntimeDependencies) {
   return (requirement) => {
-    if (!isRuntimeReadinessRequirement(requirement)) return true;
+    if (!isRuntimeReadinessRequirement2(requirement)) return true;
     const runtimeDependencies = getRuntimeDependencies();
     if (runtimeDependencies.state === "ready" || runtimeDependencies.state === "not-started") return true;
     return {
@@ -13532,6 +13982,11 @@ var registerAgentRoutes = async (app, opts) => {
     const coreAgent = createAgentRuntimeBridge2({
       runtime: modeAdapter,
       tools,
+      readiness: createAgentReadinessFromTracker({
+        requirements: collectToolReadinessRequirements(tools),
+        tracker: readyTracker,
+        checkReadiness
+      }),
       harnessFactory,
       systemPromptAppend: opts.systemPromptAppend,
       systemPromptDynamic,
@@ -13752,6 +14207,9 @@ var registerAgentRoutes = async (app, opts) => {
   }
   opts.onWorkspaceAgentDispatcher?.({
     async resolve(ctx, options) {
+      return (await this.resolveWithWorkspace(ctx, options)).dispatcher;
+    },
+    async resolveWithWorkspace(ctx, options) {
       const boundCtx = normalizeWorkspaceAgentDispatcherContext(ctx);
       assertWorkspaceAgentDispatcherRequestContext(boundCtx, options?.request);
       bindingLifecycle.assertAdmission(boundCtx.workspaceId, options?.request);
@@ -13763,11 +14221,17 @@ var registerAgentRoutes = async (app, opts) => {
             401
           );
         }
-        return createLeasedWorkspaceAgentDispatcher(staticBinding, boundCtx, options?.request);
+        return {
+          dispatcher: createLeasedWorkspaceAgentDispatcher(staticBinding, boundCtx, options?.request),
+          workspace: staticBinding.runtimeBundle.workspace
+        };
       }
       const binding = await getOrCreateRuntimeBinding(boundCtx.workspaceId, options?.request, { trustedCtx: boundCtx });
       bindingLifecycle.assertAdmission(boundCtx.workspaceId, options?.request);
-      return createLeasedWorkspaceAgentDispatcher(binding, boundCtx, options?.request);
+      return {
+        dispatcher: createLeasedWorkspaceAgentDispatcher(binding, boundCtx, options?.request),
+        workspace: binding.runtimeBundle.workspace
+      };
     }
   });
   function getSkillsScopeForRequest(request) {
@@ -14024,6 +14488,7 @@ export {
   createAgent,
   AgentDirectoryCompilerError,
   compileAgentDirectory,
+  resolveAgentDeployment,
   MANAGED_AGENT_MCP_ORIGIN_SURFACE,
   MANAGED_AGENT_MCP_DELIVERY_RULE,
   ManagedAgentMcpError,