@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/lib/task_delivery.mjs

@@ -0,0 +1,219 @@
+// APort owns OAuth, audience/region/repository authorization. This adapter has no
+// anonymous fallback; every operation reauthorizes before touching scoped state.
+import Ajv from "ajv";
+import { MAX_DELIVERY_OPERATIONS, receiptCapacityError } from "./task_delivery_store.mjs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { createTaskService } from "./tasks.mjs";
+import { executionCapabilities, capabilitiesFor } from "./harness.mjs";
+import { unsubmittedInitialDispatch } from "./execution.mjs";
+import { runtimePinManifest, assertRuntimePin } from "./runtime_state.mjs";
+import { acquireRuntimeOwner } from "./daemon.mjs";
+import { requestControl } from "./control.mjs";
+import { reconcileDeliveryCancellation } from "./task_delivery_cancel.mjs";
+import { controlAvailability } from "./control_contract.mjs";
+import { logWindow } from "./run_log.mjs";
+import { idSlug } from "./state.mjs";
+import { redact } from "./execution_io.mjs";
+import { canonical } from "./learning_data.mjs";
+import { scopeKey } from "./task_delivery_store.mjs";
+import { TASK_OPERATIONS, REPOSITORY_ID_SCHEMA, DELIVERY_VERSION, deliveryError, settledTaskRejection } from "./task_delivery_contract.mjs";
+import { taskView } from "./task_delivery_view.mjs";
+import { readJson } from "./fs.mjs";
+import { COMPLETION_CAPABILITIES } from "./task_completion.mjs";
+const validators = new Map(TASK_OPERATIONS.map(op => [op.name, new Ajv({ strict: true, allErrors: true }).compile(op.inputSchema)]));
+const validRepositoryId = new Ajv({ strict: true }).compile(REPOSITORY_ID_SCHEMA);
+const hash = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+
+export function createTaskDelivery({ authorize, contextFor, store, schedule, manifest, secretsFor = () => [] }) {
+  if (typeof authorize !== "function" || typeof contextFor !== "function" || !store?.transaction || !store?.read || typeof schedule !== "function") throw deliveryError("DELIVERY_CONFIG", "Supply APort authorization, scoped context, durable receipt store and wake-up scheduling adapters");
+  manifest = runtimePinManifest(manifest);
+  const owned = (data, taskId) => {
+    if (!Object.hasOwn(data.tasks, taskId)) throw deliveryError("DELIVERY_NOT_FOUND", "Task is unavailable in this account");
+    return data.tasks[taskId];
+  };
+  async function dispatch(name, input, identity) {
+    const op = TASK_OPERATIONS.find(o => o.name === name), validate = validators.get(name);
+    if (!op || !validate(input)) throw deliveryError("DELIVERY_INPUT", `Invalid ${name} request; use its documented schema (no paths, endpoints or credentials)`);
+    const scope = await authorize({ identity, operation: name, requiredScope: op.scope, taskId: input.taskId, repositoryId: input.repositoryId });
+    scopeKey(scope);
+    const secrets = secretsFor(scope);
+    const serialized = JSON.stringify(input);
+    if (serialized !== redact(serialized, secrets)) throw deliveryError("DELIVERY_SECRET", "Remove credential material from task text, answers or notes before sending them to a model");
+    if (!Array.isArray(scope.scopes) || !scope.scopes.includes(op.scope) || !Array.isArray(scope.repositories)) throw deliveryError("DELIVERY_AUTHORIZATION", "APort did not grant the required scope and repository set");
+    if (!scope.repositories.every(id => validRepositoryId(id))) throw deliveryError("DELIVERY_CONFIG", "APort returned an unsupported repository ID; use the bounded repository-ID schema");
+    const allowedRepo = id => { if (!scope.repositories.includes(id)) throw deliveryError("DELIVERY_AUTHORIZATION", "Repository is unavailable in this account"); };
+    const project = (ctx, task) => {
+      const entry = task.implementation && ctx.state.get(task.implementation.id);
+      const execution = entry && (ctx.executionFor ? ctx.executionFor(task.implementation.id, task.harness) : ctx.runnerFor(task.implementation.id));
+      const run = execution?.current();
+      const result = run?.id && execution.result?.(run.id);
+      const verification = run?.id && /^[A-Za-z0-9_-]+$/.test(run.id) ? readJson(join(ctx.home, "runs", idSlug(task.implementation.id), run.id, "verification.json")) : null;
+      const capability = execution?.capabilities ?? executionCapabilities().find(c => c.name === task.harness);
+      let resumable = Boolean(entry?.session);
+      if (entry && execution && !resumable) {
+        try { resumable = Boolean(unsubmittedInitialDispatch(entry, execution)); }
+        catch (error) { if (!["EXECUTION_STOPPED", "EXECUTION_UNKNOWN"].includes(error.code)) throw error; }
+      }
+      return taskView(task, { entry, run, result, verification, capabilities: capability, controls: controlAvailability(entry, run, capability, { resumable }), secrets: [...secretsFor(scope), ctx.home, task.checkout].filter(Boolean) });
+    };
+    const getContext = async (repoId, allowance) => {
+      allowedRepo(repoId);
+      // Server configuration resolves all filesystem paths and transport URLs.
+      const bound = await contextFor(scope, repoId);
+      if (!bound?.ctx || !bound.repository?.dir || !bound.repository?.repo) throw deliveryError("DELIVERY_CONFIG", "APort must bind the authorized repository to a scoped runtime context");
+      const ctx = bound.ctx;
+      let scopedCtx = { ...ctx, taskSecrets: secrets, enforceTaskAllowance: true };
+      if (allowance) {
+        if (allowance.budgetUsd > ctx.config.max_budget_usd || allowance.runtimeMs > ctx.config.run_timeout_minutes * 60000) throw deliveryError("DELIVERY_ALLOWANCE", "Requested allowance exceeds the configured account limit");
+        // Narrow a copy: shared account settings are never mutated by requests.
+        scopedCtx = { ...scopedCtx, config: { ...ctx.config, max_budget_usd: allowance.budgetUsd, run_timeout_minutes: allowance.runtimeMs / 60000 } };
+      }
+      return { ...bound, ctx: scopedCtx, service: createTaskService(scopedCtx, bound.taskOptions) };
+    };
+    if (name === "capabilities") {
+      const repositories = [];
+      const ids = [...new Set(scope.repositories)].sort().filter(id => !input.cursor || id > input.cursor);
+      for (const id of ids.slice(0, 100)) {
+        const { ctx } = await getContext(id);
+        repositories.push({ id, completion: COMPLETION_CAPABILITIES, providers: executionCapabilities().map(capability => ({ ...capability,
+          configured: Boolean(ctx.config.harness[capability.name]),
+          available: capability.available && Boolean(ctx.config.harness[capability.name]),
+          accountAccess: "unverified-until-setup-check", setup: capability.reason || (!ctx.config.harness[capability.name] ? "APort must configure this provider for the authorized account" : "Dispatch validates the configured account/model/environment and allowance"),
+          canPrepare: Boolean(capability.preparation && capability.available && ctx.config.harness[capability.name]),
+          preparationSetup: capability.preparation ? "Uses the declared bounded preparation adapter" : "Bounded preparation is unavailable; use the existing hand-authored ready/start workflow until this provider supports an enforced tool-free boundary",
+        })) });
+      }
+      return redact({ version: DELIVERY_VERSION, providers: executionCapabilities(), repositories,
+        truncated: ids.length > 100, nextCursor: ids.length > 100 ? repositories.at(-1).id : null }, secretsFor(scope));
+    }
+    if (op.annotations.readOnlyHint) {
+      const data = await store.read(scope);
+      if (name === "list") {
+        const tasks = [], authorized = Object.entries(data.tasks).filter(([, record]) => scope.repositories.includes(record.repositoryId)).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).filter(([id]) => !input.cursor || id > input.cursor);
+        for (const [taskId, record] of authorized.slice(0, 100)) {
+          const { ctx, service } = await getContext(record.repositoryId);
+          tasks.push(project(ctx, await service.inspect({ taskId })));
+        }
+        return { version: DELIVERY_VERSION, tasks, truncated: authorized.length > 100, nextCursor: authorized.length > 100 ? tasks.at(-1).taskId : null };
+      }
+      const record = owned(data, input.taskId), { ctx, service } = await getContext(record.repositoryId);
+      const task = await service.inspect({ taskId: input.taskId }), view = project(ctx, task);
+      if (name === "logs") {
+        if (!task.implementation?.run) return { version: DELIVERY_VERSION, taskId: view.taskId, revision: view.revision, lines: [], ids: [], total: 0, from: 1, to: 0, gap: null };
+        const runId = view.implementation.run;
+        if (!/^[A-Za-z0-9_-]+$/.test(runId || "")) throw deliveryError("DELIVERY_STATE", "Saved run identity is invalid; repair the scoped runtime record");
+        const root = join(ctx.home, "runs", idSlug(task.implementation.id), runId);
+        return redact({ version: DELIVERY_VERSION, taskId: view.taskId, revision: view.revision, ...logWindow(root, { after: input.after, count: input.count || 100 }) }, [...secretsFor(scope), ctx.home, task.checkout].filter(Boolean));
+      }
+      if (name === "evidence") return { version: DELIVERY_VERSION, taskId: view.taskId, revision: view.revision, completion: view.completion, brief: view.brief, sources: view.sources, artifacts: view.artifacts, readiness: view.readiness, implementation: view.implementation, evidence: view.evidence };
+      return view;
+    }
+    return store.transaction(scope, async (data, save) => {
+      const key = input.operationId, signature = "canonical-v1:" + createHash("sha256").update(canonical(JSON.parse(JSON.stringify([name, input])))).digest("hex");
+      const cancellation = name === "control" && input.action === "cancel";
+      const cancellations = data.cancellations || {};
+      const previous = Object.hasOwn(data.operations, key) ? data.operations[key] : Object.hasOwn(cancellations, key) ? cancellations[key] : null;
+      // One compact safety receipt per retained task, independent of ordinary
+      // count/byte capacity. Never evict identities or allow one task to consume
+      // another task's cancellation reserve.
+      if (!previous && cancellation && Object.values(cancellations).some(receipt => receipt.taskId === input.taskId && !(receipt.status === "acknowledged" && receipt.rejection))) throw deliveryError("DELIVERY_CAPACITY", "This task already has a retained cancellation; retry its original operation ID or inspect the task's cancellation status");
+      if (!previous && !cancellation && Object.keys(data.operations).length >= MAX_DELIVERY_OPERATIONS) throw receiptCapacityError();
+      if (!previous && cancellation && Object.keys(cancellations).length >= MAX_DELIVERY_OPERATIONS) throw receiptCapacityError();
+      const reserved = cancellation && !Object.hasOwn(data.operations, key);
+      const receipts = reserved ? cancellations : data.operations;
+      if (previous && previous.signature !== signature && previous.signature !== hash([name, input])) throw deliveryError("DELIVERY_CONFLICT", "Operation identity already belongs to different input");
+      // Only the original request may advance a task while its intent is open.
+      // Preparation IDs deterministically allocate distinct tasks; an unpublished
+      // preparation has no owned task binding available to competing requests.
+      if (!cancellation && Object.entries(data.operations).some(([id, receipt]) => id !== key && receipt.status === "intent" &&
+        (input.taskId && receipt.taskId === input.taskId))) throw deliveryError("DELIVERY_PENDING", "Retry the unresolved operation with its original identity before another task mutation; cancellation remains available");
+      const record = name === "prepare" ? { repositoryId: input.repositoryId, allowance: input.allowance } : owned(data, input.taskId);
+      const { ctx, taskOptions, repository } = await getContext(record.repositoryId, record.allowance);
+      // Share ownership with coordinator wakes, backup and migration. Claim
+      // before durable intent or task effects, and retain it through receipt saves.
+      const runtimeOwner = acquireRuntimeOwner(ctx.home);
+      try {
+        assertRuntimePin({ home: ctx.home, manifest });
+        const service = createTaskService(ctx, { ...taskOptions, mutationOwner: runtimeOwner });
+        if (previous?.status === "acknowledged") {
+          if (previous.rejection) throw settledTaskRejection(previous.rejection.code, previous.rejection.message);
+          if (cancellation) {
+            const task = await service.inspect({ taskId: previous.taskId });
+            if (!task.implementation) throw deliveryError("DELIVERY_CONTROL", "No implementation exists to control");
+            previous.wakePending = true; await save(data);
+            const cancellationPending = await reconcileDeliveryCancellation(ctx, task.implementation.id, hash([scopeKey(scope), key]));
+            await schedule(scope); previous.wakePending = false; await save(data);
+            return { ...project(ctx, await service.inspect({ taskId: previous.taskId })), cancellationPending };
+          }
+          if (previous.wakePending) { await schedule(scope); previous.wakePending = false; await save(data); }
+          return previous.result ?? project(ctx, await service.inspect({ taskId: previous.taskId }));
+        }
+        const task = name === "prepare" ? null : await service.inspect({ taskId: input.taskId });
+        const rejectWithoutEffects = async error => {
+          const rejection = { code: error.code, message: redact(String(error.message), [...secretsFor(scope), ctx.home, task?.checkout].filter(Boolean)).slice(0, 500) };
+          receipts[key] = { signature, name, taskId: input.taskId || null, status: "acknowledged", wakePending: false, rejection };
+          if (reserved) data.cancellations = receipts;
+          await save(data);
+          throw settledTaskRejection(rejection.code, rejection.message);
+        };
+        // Only this pre-intent check proves a stale request had no effects.
+        // Keep its identity forever; a new cancellation may use a fresh ID,
+        // but the retained receipt still counts against bounded capacity.
+        if (!previous && task?.revision !== input.expectedRevision && name !== "prepare") return await rejectWithoutEffects(deliveryError("DELIVERY_CONFLICT", "Task revision changed; inspect before retrying"));
+        if (cancellation && !task.implementation) throw deliveryError("DELIVERY_CONTROL", "No implementation exists to control");
+        const ctxPaths = (input.contextIds || []).map(id => {
+          if (!Object.hasOwn(repository.context || {}, id)) throw deliveryError("DELIVERY_INPUT", "Selected context ID is unavailable");
+          return repository.context[id];
+        });
+        if (!previous) Object.defineProperty(receipts, key, { value: { signature, status: "intent", mutationFence: true, name, taskId: input.taskId || null }, enumerable: true, writable: true, configurable: true });
+        if (reserved) data.cancellations = receipts;
+        // A compact acknowledgement plus the bounded repository/task binding
+        // must fit before effects. Legacy intents also reserve before recovery.
+        if (!reserved) receipts[key].acknowledgementReserve = " ".repeat(4096);
+        await save(data); // crash-safe intent before any inference, readiness or execution
+        let result, cancellationPending;
+        const shared = { taskId: input.taskId, expectedRevision: input.expectedRevision, noDaemon: true };
+        try {
+        if (name === "prepare") result = await service.prepare({ text: input.text, dir: repository.dir, repo: repository.repo, harness: input.harness, context: ctxPaths, verifyCommands: input.verifyCommands || [], completion: input.completion, requestId: hash([scopeKey(scope), key]), noDaemon: true });
+        else if (name === "answer") result = await service.answer({ ...shared, answers: input.answers, verifyCommands: input.verifyCommands || [], operationId: key });
+        else if (name === "control") {
+          if (!task.implementation) throw deliveryError("DELIVERY_CONTROL", "No implementation exists to control");
+          const requestId = hash([scopeKey(scope), key]);
+          const entry = ctx.state.get(task.implementation.id);
+          // Cancellation can safely be re-enqueued with its deterministic ID
+          // after intent-only crashes; it only fences dispatch, never starts work.
+          // Other controls remain ambiguous when their bounded history is gone.
+          if (previous && !cancellation && ![entry?.control, ...(entry?.control_history || [])].some(c => c?.id === requestId)) throw deliveryError("DELIVERY_UNKNOWN", "Interrupted control has no retained acknowledgement; inspect its effects before authorizing a new request identity");
+          requestControl(ctx, { handle: task.implementation.id, action: input.action, note: input.note || "", interrupt: input.interrupt || false, requestId });
+          if (cancellation) cancellationPending = await reconcileDeliveryCancellation(ctx, task.implementation.id, requestId);
+          result = await service.inspect({ taskId: input.taskId });
+        } else {
+          // A moved revision settles an interrupted request with the current
+          // saved outcome, including denial or incomplete preparation. Never
+          // repeat effects or grant authority from its stale revision; further
+          // recovery requires a new request against the inspected revision.
+          if (previous && task.revision !== input.expectedRevision) {
+            if (!previous.mutationFence) throw deliveryError("DELIVERY_UNKNOWN", "Legacy intent lacks exclusive mutation evidence; preserve it for reconciliation with its original runtime");
+            result = task;
+          }
+          else result = await service[name]({ ...shared, ...(name === "start" ? { run: true } : {}) });
+        }
+        } catch (error) {
+          if (error.taskEffects === "none") {
+            return await rejectWithoutEffects(error);
+          }
+          throw error;
+        }
+        data.tasks[result.taskId] = record;
+        receipts[key] = { signature, name, taskId: result.taskId, status: "acknowledged", wakePending: true };
+        await save(data);
+        await schedule(scope); // adapter enqueues/alarm; never runs a second poll loop
+        receipts[key].wakePending = false;
+        await save(data);
+        return { ...project(ctx, result), ...(cancellation ? { cancellationPending } : {}) };
+      } finally { runtimeOwner.release(); }
+    });
+  }
+  return { version: DELIVERY_VERSION, operations: TASK_OPERATIONS, dispatch };
+}

package/lib/task_delivery_cancel.mjs

@@ -0,0 +1,34 @@
+import { cancelControl, cancellationStatus } from "./control.mjs";
+import { executionRunner, executionLive } from "./execution.mjs";
+import { deliveryError } from "./task_delivery_contract.mjs";
+import { nowIso } from "./time.mjs";
+
+// A cancellation-scoped host may replay only this exact retained control. It
+// never runs a coordinator tick, advances another task, or collects/publishes a
+// late result. Provider ownership, backoff and idempotency remain in execution.
+export async function reconcileDeliveryCancellation(ctx, id, requestId) {
+  let entry = ctx.state.get(id);
+  const request = [entry?.control, ...(entry?.control_history || [])].find(control => control?.id === requestId);
+  if (request?.action !== "cancel" || !entry.dispatch_stopped) {
+    throw deliveryError("DELIVERY_CONTROL", "The retained cancellation no longer owns this task control; inspect before recovery");
+  }
+  if (entry.control?.id === requestId) await cancelControl(ctx, id);
+  entry = ctx.state.get(id);
+  if (entry.control?.id === requestId && entry.control.status === "queued") return true; // another execution owner
+  if (entry.reason === "cancelled") return false;
+  const runner = executionRunner(ctx, id);
+  // Legacy local runners retain their existing verified-stop behavior. Remote
+  // execution must have its durable stop before reconcile is allowed to run.
+  if (!runner.state || !runner.reconcile) return true;
+  if (!runner.state().stopped) await runner.cancel();
+  if (!runner.state().stopped) throw deliveryError("DELIVERY_CONTROL", "Cancellation has not durably fenced provider dispatch");
+  await runner.reconcile();
+  const run = runner.current();
+  const pending = Boolean(run && executionLive(run));
+  if (!pending) {
+    const status = cancellationStatus({ confirmed: !run || run.execution?.providerState === "cancelled", terminal: Boolean(run) });
+    ctx.state.update(id, { state: "needs-human", reason: status.reason,
+      ...(entry.control?.id === requestId ? { control: { ...entry.control, status: "applied", message: status.message, finished_at: nowIso(ctx.clock) } } : {}) });
+  }
+  return pending;
+}

package/lib/task_delivery_contract.mjs

@@ -0,0 +1,61 @@
+// Portable wire contract. No filesystem, credentials, configuration or providers.
+import { COMPLETION_SCHEMA } from "./task_completion.mjs";
+export { COMPLETION_SCHEMA, COMPLETION_CAPABILITIES, coordinatorEntryActive } from "./task_completion.mjs";
+export const DELIVERY_VERSION = 1;
+export const CORE_VERSION = "0.2.0";
+// One byte limit for the built APort MCP resource, package and runtime reader.
+export const MAX_TASK_UI_BYTES = 2_000_000;
+export const deliveryError = (code, message) => Object.assign(new Error(message), { code, version: DELIVERY_VERSION });
+// Only the delivery receipt boundary may label a bounded/redacted rejection.
+// Arbitrary provider errors with a TASK_* code must not expose their message.
+const settledRejections = new WeakMap();
+const safeRejectionCodes = new Set(["DELIVERY_CONFLICT", "TASK_INPUT", "TASK_DELIVERY_SCOPE", "TASK_CONFLICT", "TASK_NOT_READY", "TASK_AUTHORIZATION", "TASK_SECRET", "TASK_PREPARATION_BOUNDARY"]);
+export function settledTaskRejection(code, message) {
+  const error = deliveryError(code, message);
+  if (safeRejectionCodes.has(code) && typeof message === "string") settledRejections.set(error, { code, message: message.slice(0, 500) });
+  return error;
+}
+export const taskRejectionForModel = error => settledRejections.get(error) || null;
+
+const id = { type: "string", pattern: "^[A-Za-z0-9_-]{1,128}$" };
+export const REPOSITORY_ID_SCHEMA = { type: "string", maxLength: 128, pattern: "^[A-Za-z0-9_-][A-Za-z0-9_.-]*(/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$" };
+const taskId = { type: "string", pattern: "^task-[a-f0-9]{24}$" };
+const text = { type: "string", minLength: 1, maxLength: 32768 };
+const revision = { type: "integer", minimum: 1 };
+const verifyCommands = { type: "array", maxItems: 32, uniqueItems: true, items: { type: "string", minLength: 1, maxLength: 500 } };
+const object = (properties, required = Object.keys(properties)) => ({ type: "object", properties, required, additionalProperties: false });
+const mutation = (properties, required = Object.keys(properties)) => object({ ...properties, operationId: id, expectedRevision: revision }, [...required, "operationId", "expectedRevision"]);
+const definition = (name, description, inputSchema, { write = false, destructive = false, open = false } = {}) => ({
+  name, description, inputSchema, scope: write ? "task-delivery:write" : "task-delivery:read",
+  annotations: { readOnlyHint: !write, destructiveHint: destructive, idempotentHint: true, openWorldHint: open },
+});
+export const TASK_OPERATIONS = Object.freeze([
+  definition("capabilities", "Read up to 100 authorized repositories and configured harness capabilities; pass nextCursor as cursor for more. Does not probe providers.", object({ cursor: REPOSITORY_ID_SCHEMA }, [])),
+  definition("prepare", "Prepare requirements using an authorized repository and allowance; may use paid inference.", object({
+    repositoryId: REPOSITORY_ID_SCHEMA, text, harness: id, contextIds: { type: "array", items: id, maxItems: 100, uniqueItems: true }, verifyCommands, completion: COMPLETION_SCHEMA,
+    allowance: object({ budgetUsd: { type: "number", exclusiveMinimum: 0 }, runtimeMs: { type: "integer", minimum: 1 } }),
+    operationId: id, expectedRevision: { type: "integer", const: 0 },
+  }, ["repositoryId", "text", "harness", "allowance", "operationId", "expectedRevision"]), { write: true, open: true }),
+  definition("answer", "Answer saved question IDs and optionally select verification commands on the expected revision; may continue paid preparation.", mutation({ taskId, answers: { type: "object", minProperties: 1, maxProperties: 100, propertyNames: id, additionalProperties: text }, verifyCommands }, ["taskId", "answers"]), { write: true, open: true }),
+  definition("resume", "Resume owned preparation without allocating another task.", mutation({ taskId }), { write: true, open: true }),
+  definition("validate", "Run the canonical readiness gate and preserve its decision.", mutation({ taskId }), { write: true, open: true }),
+  definition("start", "Start the exact approved task revision with explicit execution authorization.", mutation({ taskId, run: { type: "boolean", const: true } }), { write: true, open: true }),
+  definition("list", "Read up to 100 authorized saved tasks; pass nextCursor as cursor for more. Does not poll providers.", object({ cursor: taskId }, [])),
+  definition("inspect", "Read a saved task, brief, progress and supported controls.", object({ taskId })),
+  definition("evidence", "Read bounded saved evidence and artifact identities; does not reconcile providers.", object({ taskId })),
+  definition("logs", "Read one bounded saved log window; does not create a provider poller.", object({ taskId, after: { type: "integer", minimum: 0 }, count: { type: "integer", minimum: 1, maximum: 100 } }, ["taskId"])),
+  definition("control", "Queue a supported control for the existing coordinator; cancellation may leave remote compute running.", mutation({ taskId, action: { type: "string", enum: ["recheck", "resume", "message", "cancel"] }, note: { type: "string", maxLength: 4000 }, interrupt: { type: "boolean" } }, ["taskId", "action"]), { write: true, destructive: true, open: true }),
+]);
+
+export function assertCompatible({ coreVersion, operationVersion, taskVersion, executionVersion }) {
+  if (!/^0\.2\.\d+$/.test(coreVersion || "") || operationVersion !== DELIVERY_VERSION || taskVersion !== 1 || executionVersion !== 1) {
+    throw deliveryError("DELIVERY_VERSION", "Incompatible core or contract. Stop wake-ups, back up the durable namespace, migrate with a compatible package, or restore the matching package and state backup. Never replace active-job code.");
+  }
+}
+
+export function uiResourceConfiguration({ uri, domain, connectDomains = [], resourceDomains = [] }) {
+  const origin = value => { const u = new URL(value); if (u.protocol !== "https:" || u.origin !== value || u.username || u.password) throw deliveryError("DELIVERY_RESOURCE", "UI configuration needs exact HTTPS origins"); return value; };
+  if (typeof uri !== "string" || !/^ui:\/\/[A-Za-z0-9/-]+$/.test(uri)) throw deliveryError("DELIVERY_RESOURCE", "Configure a registered ui:// resource URI");
+  return { uri, mimeType: "text/html;profile=mcp-app", toolMeta: { ui: { resourceUri: uri }, "openai/ui": { entrypoints: [{ type: "global" }, { type: "thread" }] } },
+    resourceMeta: { ui: { domain: origin(domain), csp: { connectDomains: connectDomains.map(origin), resourceDomains: resourceDomains.map(origin) } } } };
+}

package/lib/task_delivery_mcp.mjs

@@ -0,0 +1,40 @@
+// Transport registration only. Production identity and OAuth stay with APort.
+import { TASK_OPERATIONS, MAX_TASK_UI_BYTES, taskRejectionForModel } from "./task_delivery_contract.mjs";
+import { modelSummary, taskListSummary, capabilitySummary, evidenceSummary, logSummary } from "./task_delivery_view.mjs";
+
+export async function registerTaskDelivery(server, { delivery, identityFor, resource = null, readResource = null }) {
+  if (!delivery?.dispatch || typeof identityFor !== "function") throw new Error("Supply the scoped dispatcher and APort's authenticated request identity resolver");
+  const { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } = await import("@modelcontextprotocol/sdk/types.js");
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TASK_OPERATIONS.map(op => ({ name: `task_${op.name}`, description: op.description,
+    inputSchema: op.inputSchema, annotations: op.annotations, ...(resource ? { _meta: resource.toolMeta } : {}) })) }));
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    const name = request.params.name.replace(/^task_/, "");
+    try {
+      const view = await delivery.dispatch(name, request.params.arguments || {}, await identityFor(extra));
+      const summary = name === "capabilities" ? capabilitySummary(view) : name === "evidence" ? evidenceSummary(view) : name === "logs" ? logSummary(view) : view.tasks ? { version: view.version, tasks: view.tasks.map(taskListSummary), truncated: view.truncated, nextCursor: view.nextCursor } : view.taskId && view.status ? modelSummary(view) : { version: view.version, available: true };
+      return { structuredContent: summary, content: [{ type: "text", text: JSON.stringify(summary) }], _meta: { taskDelivery: name === "list" ? summary : view } };
+    } catch (error) {
+      const rejection = taskRejectionForModel(error);
+      if (rejection) return { isError: true, content: [{ type: "text", text: `${rejection.code}: ${rejection.message}` }] };
+      // Authentication challenges are owned by APort's transport layer. Never
+      // serialize a raw credential/provider/filesystem error into model context.
+      return { isError: true, content: [{ type: "text", text: `${/^DELIVERY_[A-Z_]+$/.test(error.code || "") ? error.code : "DELIVERY_FAILED"}: Inspect the authorized task or reconnect your account before retrying.` }] };
+    }
+  });
+  if (resource) {
+    if (typeof readResource !== "function") throw new Error("Supply the built APort resource reader");
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [{ uri: resource.uri, name: "Task delivery", mimeType: resource.mimeType }] }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request, extra) => {
+      try {
+        if (request.params.uri !== resource.uri) throw new Error("Resource unavailable");
+        const identity = await identityFor(extra);
+        // The supplied asset callback must authorize the identity as well as load
+        // built assets. It receives no path or user-supplied URL.
+        const text = await readResource(identity);
+        if (typeof text !== "string" || Buffer.byteLength(text) > MAX_TASK_UI_BYTES) throw new Error("Built UI resource exceeds the shared byte limit or is unavailable");
+        return { contents: [{ uri: resource.uri, mimeType: resource.mimeType, text, _meta: resource.resourceMeta }] };
+      } catch { throw new Error("Task resource unavailable; reconnect the authorized account or repair its built UI asset"); }
+    });
+  }
+  return server;
+}

package/lib/task_delivery_store.mjs

@@ -0,0 +1,43 @@
+// Durable single-host adapter. Its root MUST live on the durable coordinator volume.
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { ensureDir, readJson, writeJsonAtomic } from "./fs.mjs";
+import { acquireProcessLock } from "./daemon.mjs";
+import { deliveryError } from "./task_delivery_contract.mjs";
+export const MAX_DELIVERY_OPERATIONS = 256;
+export const MAX_DELIVERY_STORE_BYTES = 32 * 1024 * 1024;
+export const MAX_CANCELLATION_STORE_BYTES = 1024 * 1024;
+const bytes = value => Buffer.byteLength(JSON.stringify(value, null, 2) + "\n");
+const checkSize = data => {
+  const { cancellations, ...ordinary } = data;
+  if (bytes(ordinary) > MAX_DELIVERY_STORE_BYTES || (cancellations && bytes({ cancellations }) > MAX_CANCELLATION_STORE_BYTES)) throw receiptCapacityError();
+};
+export const receiptCapacityError = () => deliveryError("DELIVERY_CAPACITY", "Delivery receipt capacity reached; retain this namespace for retries, drain active work and archive it before provisioning a separate namespace for new operations. Never resend an old operation ID in a new namespace.");
+export const scopeKey = scope => {
+  for (const key of ["tenant", "account", "environment", "region"]) if (typeof scope?.[key] !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(scope[key])) throw deliveryError("DELIVERY_SCOPE", `APort must supply validated ${key}`);
+  return createHash("sha256").update(JSON.stringify([scope.tenant, scope.account, scope.environment, scope.region])).digest("hex");
+};
+export function createDeliveryStore(root) {
+  const folder = scope => ensureDir(join(root, scopeKey(scope)));
+  const read = scope => {
+    const file = join(folder(scope), "delivery.json");
+    try { if (statSync(file).size > MAX_DELIVERY_STORE_BYTES + MAX_CANCELLATION_STORE_BYTES) throw receiptCapacityError(); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+    const data = readJson(file, { version: 1, tasks: {}, operations: {} });
+    if (data.version !== 1) throw deliveryError("DELIVERY_VERSION", "Back up the delivery store and restore a compatible version before reopening tasks");
+    checkSize(data);
+    return data;
+  };
+  return {
+    read,
+    transaction: async (scope, fn) => {
+      const dir = folder(scope), lock = acquireProcessLock(join(dir, "delivery.lock"), "task delivery");
+      try { return await fn(read(scope), data => {
+        checkSize(data);
+        return writeJsonAtomic(join(dir, "delivery.json"), data);
+      }); }
+      finally { lock.release(); }
+    },
+  };
+}

package/lib/task_delivery_view.mjs

@@ -0,0 +1,88 @@
+import { DELIVERY_VERSION } from "./task_delivery_contract.mjs";
+import { redact } from "./execution_io.mjs";
+
+// All inputs are saved observations, never a transport or live credential.
+export function taskView(task, { entry = null, run = null, result = null, verification = null, capabilities = {}, controls = {}, secrets = [] } = {}) {
+  // Preparation is real provider work too. Keep its saved status visible until
+  // the implementation owns an execution, without polling from the projection.
+  const ex = run?.execution || entry?.execution || task.preparation?.attempts?.at(-1)?.execution || {};
+  const pr = task.implementation?.pr || entry?.pr || null;
+  const url = pr && /^[-\w.]+\/[-\w.]+$/.test(task.repo) ? `https://github.com/${task.repo}/pull/${Number(pr)}` : null;
+  return redact({ version: DELIVERY_VERSION, taskId: task.taskId, revision: task.revision, status: task.status,
+    repo: task.repo, base: task.base, harness: task.harness, original: task.original,
+    questions: task.questions, answers: task.answers, requirements: task.requirements,
+    assumptions: task.assumptions, mapping: task.mapping, stories: task.stories,
+    brief: task.draft ? { hash: task.draft.hash, revision: task.draft.revision, current: task.draft.current, text: task.draft.text } : null,
+    readiness: task.readiness, validation: task.validation, allowance: task.preparation?.allowance, completion: task.completion,
+    failures: task.failures, errorCode: task.errorCode, nextAction: task.nextAction,
+    progress: { workflowState: entry?.state || task.status, providerState: ex.providerState || null,
+      observedAt: ex.observedAt || null, reconciledAt: ex.reconciledAt || null, nextAttemptAt: ex.nextAttemptAt || null,
+      recoveryAction: ex.recoveryAction || null, costUsd: ex.costUsd ?? null, continuity: capabilities.continuation || null },
+    implementation: task.implementation ? { id: task.implementation.id, run: run?.id || entry?.last?.run || task.implementation.run, state: entry?.state || task.implementation.state, pr, url } : null,
+    sources: task.sources, artifacts: [
+      ...(task.artifacts || []).filter(a => a.id === "brief").slice(0, 1).map(a => ({ id: a.id, hash: a.hash })),
+      ...(result?.files || []).slice(0, 100).map((a, i) => ({ id: `result-${i}`, path: a.path, hash: a.afterHash || a.hash || null })),
+      ...(task.artifacts || []).filter(a => a.id !== "brief").slice(0, 100).map(a => ({ id: a.id, hash: a.hash })),
+    ].slice(0, 100),
+    evidence: { providerTests: (result?.tests || []).slice(0, 100), verification: verification ? { inputHead: verification.inputHead, head: verification.head, ok: verification.ok, commands: verification.commands, status: verification.status, observations: verification.evidence } : null },
+    controls, capability: capabilities,
+  }, secrets);
+}
+
+export function modelSummary(view) {
+  // Only bounded redacted recovery reasons enter model context; raw diagnostics,
+  // briefs and logs remain in the explicit UI/evidence projection.
+  return { version: view.version, taskId: view.taskId, revision: view.revision, status: view.status, harness: view.harness, repo: boundedText(view.repo, 256), completion: view.completion,
+    recovery: view.status === "blocked" ? {
+      code: /^TASK_[A-Z_]{1,64}$/.test(view.errorCode || "") ? view.errorCode : "TASK_BLOCKED",
+      reasons: (Array.isArray(view.failures) ? view.failures : []).slice(0, 5).map(reason => boundedText(reason, 500)).filter(Boolean),
+      nextAction: boundedText(view.nextAction, 500),
+    } : null,
+    controls: Object.fromEntries(["recheck", "resume", "message", "cancel", "interrupt"].map(key => [key, view.controls?.[key] === true])),
+    cancellation: ["stop-future-dispatch; remote-compute-may-continue", "requires-provider-confirmation"].includes(view.controls?.cancellation) ? view.controls.cancellation : null,
+    questionIds: (view.questions || []).map(q => q.id),
+    questions: (view.questions || []).map(q => ({ id: q.id, text: q.text })), workflowState: view.progress?.workflowState, pr: view.implementation?.url || null };
+}
+
+// Discovery must reach the model as well as the UI. Only public capability
+// fields are projected; server config, paths and arbitrary adapter extras stay out.
+export function capabilitySummary(view) {
+  return { version: view.version, repositories: view.repositories.slice(0, 100).map(repo => ({
+    id: repo.id, completion: repo.completion, providers: repo.providers.map(provider => ({
+      name: provider.name, configured: provider.configured, available: provider.available,
+      transport: provider.transport, continuation: provider.continuation,
+      controls: { cancel: provider.controls?.cancel, interrupt: provider.controls?.interrupt },
+      cost: { source: provider.cost?.source, hardCap: provider.cost?.hardCap },
+      canPrepare: provider.canPrepare, accountAccess: provider.accountAccess,
+      setup: provider.setup, preparationSetup: provider.preparationSetup,
+    })),
+  })), truncated: view.truncated, nextCursor: view.nextCursor };
+}
+
+
+// Explicit requested evidence only: no raw brief, source paths, logs or diagnostics.
+const boundedText = (value, limit = 300) => typeof value === "string" ? value.slice(0, limit) : null;
+export function evidenceSummary(view) {
+  const verification = view.evidence?.verification;
+  return { version: view.version, taskId: view.taskId, revision: view.revision, completion: view.completion,
+    artifacts: (view.artifacts || []).slice(0, 100).map(a => ({ id: boundedText(a.id, 128), hash: boundedText(a.hash, 128) })),
+    providerTests: (view.evidence?.providerTests || []).slice(0, 100).map(t => ({ command: boundedText(t.command), inputHead: boundedText(t.inputHead, 128), exit: Number.isInteger(t.exit) ? t.exit : null })),
+    verification: verification ? { ok: typeof verification.ok === "boolean" ? verification.ok : null, status: boundedText(verification.status), inputHead: boundedText(verification.inputHead, 128), head: boundedText(verification.head, 128),
+      observations: (verification.observations || []).slice(0, 100).map(t => ({ command: boundedText(t.command), head: boundedText(t.head, 128), exit: Number.isInteger(t.exit) ? t.exit : null })),
+      commands: (Array.isArray(verification.commands) ? verification.commands : []).slice(0, 100).map(command => boundedText(command)) } : null,
+    pr: view.implementation?.url || null };
+}
+export function logSummary(view) {
+  return { version: view.version, taskId: view.taskId, revision: view.revision,
+    total: view.total ?? 0, from: view.from ?? null, to: view.to ?? null, nextAfter: view.to ?? null,
+    returnedLines: view.lines?.length || 0, gap: boundedText(view.gap), rawLogsInUi: true };
+}
+
+
+// List pages identify tasks; inspect supplies question text and recovery detail.
+export function taskListSummary(view) {
+  return { version: view.version, taskId: view.taskId, revision: view.revision,
+    status: boundedText(view.status, 64), harness: boundedText(view.harness, 128),
+    repo: boundedText(view.repo, 256), questionCount: view.questions?.length || 0,
+    workflowState: boundedText(view.progress?.workflowState, 64), completion: view.completion, pr: boundedText(view.implementation?.url, 512) };
+}