@awebai/oats 0.23.2 → 0.24.0

package/lib/captured-scaffold.mjs

@@ -0,0 +1,87 @@
+/** Materialize one already-verified captured composition into a new private home.
+ * Home placement is supplied by the lifecycle owner; this module never discovers
+ * config, souls, work targets, launch software or instance roots. */
+import { existsSync, lstatSync, mkdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { capturedDirectoryIdentity, registerCapturedInstance, syncCapturedMetadata } from "./captured-instance-index.mjs";
+import { copyTreeSafe } from "./artifact-tree.mjs";
+import { canonicalJson } from "./portable-values.mjs";
+import { portableScope } from "./portable-state.mjs";
+import { oatsError } from "./errors.mjs";
+
+const INSTANCE_RE = /^[a-z0-9][a-z0-9-]{0,127}$/;
+
+function sameDirectory(path, witness) {
+  try {
+    const current = lstatSync(path);
+    return current.isDirectory() && current.dev === witness.dev && current.ino === witness.ino;
+  } catch { return false; }
+}
+
+export function validateCapturedDirectoryTarget(home, instance) {
+  if (typeof home !== "string" || !isAbsolute(home) || resolve(home) !== home || basename(home) !== instance || !INSTANCE_RE.test(instance)) {
+    throw oatsError("invalid-declaration", "captured scaffold needs a normalized absolute home whose basename is its instance name");
+  }
+}
+
+export function materializeCapturedDirectoryScaffold({ home, instance, loaded }) {
+  validateCapturedDirectoryTarget(home, instance);
+  if (!loaded?.record || !loaded?.composition || !loaded?.resolution || typeof loaded.deployment !== "string") throw oatsError("invalid-resolution", "captured scaffold requires a verified composition load");
+  const { record, composition } = loaded;
+  if (record.dispatch.composition?.mode !== "directory") throw oatsError("needs-configuration", "captured scaffold currently requires retained directory work mode");
+  if (existsSync(home)) throw oatsError("E_INSTANCE_EXISTS", `instance home already exists: ${home}`);
+  const parent = dirname(home), parentStat = lstatSync(parent);
+  if (!parentStat.isDirectory() || realpathSync(parent) !== parent) throw oatsError("E_NO_CANONICAL_ROOT", "captured scaffold parent must be a physical directory");
+  const subject = record.subject, agent = subject.kind === "persistent" ? subject.soul.alias : subject.name;
+  const responsibleHuman = record.messagingChoice.enabled ? record.messagingChoice.privateKey.human : null;
+  const executionBinding = { schemaVersion: 1, deployment: portableScope(loaded.deployment), resolution: loaded.resolution };
+  const bodyFile = loaded.resources.get(record.dispatch.composition.body);
+  if (!bodyFile) throw oatsError("invalid-resolution", "captured scaffold body is absent from verified resources");
+  const sourceRoot = dirname(bodyFile);
+  const metadata = {
+    instance, agent, kind: subject.kind, home, work: "directory", launched: false, incarnationId: randomUUID(),
+    executionBinding, responsibleHuman,
+    captured: { schemaVersion: 1, resolution: loaded.resolution, lifecycle: "scaffolded-hooks-pending" },
+    capabilities: [...loaded.capabilities.values()].map(({ id, manifest, settings }) => ({ id, version: manifest.version, settings })),
+  };
+  let owned, primary, indexAttempted = false;
+  try {
+    mkdirSync(home, { mode: 0o700 }); owned = lstatSync(home);
+    symlinkSync(sourceRoot, join(home, "soul"));
+    writeFileSync(join(home, "AGENTS.md"), composition.text, { mode: 0o600 });
+    symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
+    mkdirSync(join(home, ".agents", "skills"), { recursive: true, mode: 0o700 });
+    mkdirSync(join(home, ".claude"), { mode: 0o700 });
+    for (const skill of composition.skills) copyTreeSafe(skill.path, join(home, ".agents", "skills", skill.name));
+    symlinkSync(join("..", ".agents", "skills"), join(home, ".claude", "skills"));
+    mkdirSync(join(home, "work"), { mode: 0o700 });
+    for (const skill of composition.skills) {
+      const file = join(home, ".agents", "skills", skill.name, "SKILL.md");
+      if (!existsSync(file) || !lstatSync(file).isFile()) throw oatsError("resolution-incomplete", `captured skill ${skill.name} did not materialize`);
+    }
+    metadata.captured.custody = { home: capturedDirectoryIdentity(home), work: capturedDirectoryIdentity(join(home, "work")) };
+    writeFileSync(join(home, "instance.json"), canonicalJson(metadata), { flag: "wx", mode: 0o600 });
+    for (const path of [join(home, "instance.json"), join(home, "work"), home, parent]) syncCapturedMetadata(path);
+    indexAttempted = true;
+    registerCapturedInstance(loaded.deployment, home);
+    return { home, instance, agent, work: "directory", incarnationId: metadata.incarnationId, executionBinding, responsibleHuman, launched: false, hooksPending: true };
+  } catch (error) {
+    primary = error;
+    // Publication/guard cleanup may fail AFTER index publication. Retain the
+    // home rather than erase evidence just because the call did not return.
+    if (indexAttempted) { error.home = home; error.cleanupRequired = true; }
+    throw error;
+  }
+  finally {
+    if (primary && owned && !indexAttempted) {
+      try {
+        if (!sameDirectory(home, owned)) throw oatsError("integrity-drift", "captured scaffold home ownership changed during rollback");
+        rmSync(home, { recursive: true });
+      } catch (cleanup) {
+        const error = new AggregateError([primary, cleanup], "captured scaffold and rollback failed", { cause: primary });
+        error.code = primary.code; throw error;
+      }
+    }
+  }
+}

package/lib/captured-selector.mjs

@@ -0,0 +1,28 @@
+/** Explicit independent-dispatch selectors, with the captured command's own
+ * environment as a propagation channel. Never infer a record from cwd/locks. */
+import { isAbsolute } from "node:path";
+import { validateResolutionRef } from "./resolution-shape.mjs";
+import { oatsError } from "./errors.mjs";
+
+export function capturedSelector(argv, env = process.env) {
+  const values = new Map(), args = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") { args.push(...argv.slice(i)); break; }
+    const match = /^(--deployment|--resolution|--artifact-set)(?:=(.*))?$/.exec(arg);
+    if (!match) { args.push(arg); continue; }
+    const name = match[1].slice(2), value = match[2] ?? argv[++i];
+    if (values.has(name) || !value || value.startsWith("--")) throw oatsError("E_BAD_ARGS", `--${name} needs one unambiguous value`);
+    values.set(name, value);
+  }
+  const explicit = values.size > 0;
+  const deployment = explicit ? values.get("deployment") : env.OATS_DEPLOYMENT;
+  if (values.has("resolution") && values.has("artifact-set")) throw oatsError("E_BAD_ARGS", "choose a resolution or an artifact set, never both");
+  const artifactSet = values.get("artifact-set");
+  const id = explicit ? artifactSet ?? values.get("resolution") : env.OATS_RESOLUTION;
+  if (!explicit && deployment === undefined && id === undefined) return null;
+  if (typeof deployment !== "string" || !isAbsolute(deployment) || typeof id !== "string") throw oatsError("E_BAD_ARGS", "portable selectors need --deployment <absolute path> and one --resolution or --artifact-set <sha256-id>");
+  const resolution = { schemaVersion: 1, id };
+  validateResolutionRef(resolution);
+  return { deployment, ...(artifactSet === undefined ? { resolution } : { artifactSet }), args, explicit };
+}

package/lib/captured-session-backend.mjs

@@ -0,0 +1,52 @@
+/** Closed inputs for the existing native session adapters. No config lookup,
+ * endpoint allocation, backend registry or runtime/provider readiness probe. */
+import { isAbsolute, resolve } from 'node:path';
+import { canonicalJson } from './portable-values.mjs';
+import { objectAt } from './portable-shape.mjs';
+import { HERDR_SUPPORTED_PROTOCOLS, isSupportedHerdrProtocol, validHerdrTarget } from './herdr.mjs';
+import { oatsError } from './errors.mjs';
+
+const same = (a,b) => canonicalJson(a) === canonicalJson(b);
+const absolute = value => typeof value === 'string' && isAbsolute(value) && resolve(value) === value && !value.includes('\0');
+export function validateCapturedSessionBackend(value) {
+  canonicalJson(value);
+  const fields=value?.backend==='herdr'?['backend','binary','socket','protocol']:['backend','binary','socket','session'];
+  objectAt(value,fields,fields);
+  if(!['tmux','herdr'].includes(value.backend)||!absolute(value.binary)||!absolute(value.socket))throw oatsError('needs-configuration','captured native backend needs explicit normalized host binary/socket');
+  if(value.backend==='herdr'){
+    if(!isSupportedHerdrProtocol(value.protocol))throw oatsError('needs-configuration',`captured Herdr requires an explicitly selected protocol in ${HERDR_SUPPORTED_PROTOCOLS.join(', ')}`);
+  }else if(typeof value.session!=='string'||!/^[A-Za-z0-9_-]+$/.test(value.session))throw oatsError('needs-configuration','captured tmux needs an explicit supported session name');
+  return value;
+}
+
+export function validateCapturedSessionTarget(value,backend,instance) {
+  validateCapturedSessionBackend(backend);canonicalJson(value);
+  if(backend.backend==='tmux'){
+    objectAt(value,['backend','session','window','socket'],['backend','session','window','socket']);
+    if(!same(value,{backend:'tmux',session:backend.session,window:instance,socket:backend.socket}))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','captured tmux target differs from admitted endpoint');
+  }else{
+    objectAt(value,['backend','binary','socket','protocol','workspaceId','paneId','terminalId'],['backend','binary','socket','protocol','workspaceId','paneId','terminalId']);
+    if(!validHerdrTarget(value)||value.binary!==backend.binary||value.socket!==backend.socket||value.protocol!==backend.protocol
+      ||[value.workspaceId,value.paneId,value.terminalId].some(id=>id.includes('\0')))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','captured Herdr target differs from admitted endpoint/identifier contract');
+  }
+  return value;
+}
+
+/** First placement admits a server endpoint, not caller-chosen Herdr IDs.
+ * Subsequent IDs must come from independently retained native observations. */
+export function assertCapturedSessionPlacement(metadata,backend,knownTargets=[]) {
+  validateCapturedSessionBackend(backend);
+  if(typeof metadata.launched!=='boolean')throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','captured metadata lacks native launch state');
+  if(metadata.launched&&!Object.hasOwn(metadata,backend.backend==='herdr'?'sessionTarget':'tmux'))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','launched metadata lacks its native target');
+  if(Object.hasOwn(metadata,'backend')&&metadata.backend!==backend.backend)throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','captured metadata selects a different backend');
+  if(backend.backend==='tmux'){
+    if(Object.hasOwn(metadata,'sessionTarget'))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','Herdr target cannot redirect captured tmux');
+    if(Object.hasOwn(metadata,'tmux'))validateCapturedSessionTarget({backend:'tmux',...metadata.tmux},backend,metadata.instance);
+  }else{
+    if(Object.hasOwn(metadata,'tmux'))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','tmux metadata cannot redirect captured Herdr');
+    if(Object.hasOwn(metadata,'sessionTarget')){
+      validateCapturedSessionTarget(metadata.sessionTarget,backend,metadata.instance);
+      if(!knownTargets.some(target=>same(target,metadata.sessionTarget)))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','Herdr metadata target lacks independent indexed custody');
+    }
+  }
+}

package/lib/captured-source-receipt-file.mjs

@@ -0,0 +1,72 @@
+/** Private captured-source registration input. This is a synchronous hook
+ * snapshot, never durable worker authority or an ambient configuration file. */
+import { lstatSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { validateSoulIdentity } from "./portable-identity.mjs";
+import { canonicalJson } from "./portable-values.mjs";
+import { objectAt, stringAt } from "./portable-shape.mjs";
+import { portableStateDirectory } from "./portable-state.mjs";
+import { validateProviderBinding } from "./resolution-shape.mjs";
+import { validateExecutionBinding } from "./schedule-capsule.mjs";
+import { oatsError } from "./errors.mjs";
+
+export const CAPTURED_SOURCE_RECEIPT_LIMITS = Object.freeze({ maxBytes: 256 * 1024, maxDepth: 32, maxEntries: 16_384 });
+const RECEIPT_FIELDS = ["schemaVersion", "kind", "home", "work", "context", "agent", "instance", "sourceIdentity", "role", "executionBinding", "responsibleHuman", "binding"];
+
+function absolutePath(value, pointer) {
+  stringAt(value, pointer);
+  if (!isAbsolute(value) || resolve(value) !== value || value.includes("\0")) throw oatsError("invalid-declaration", `${pointer} must be a normalized absolute path`);
+}
+
+function human(value) {
+  if (value === null) return;
+  objectAt(value, ["provider", "id"], ["provider", "id"], "/responsibleHuman");
+  stringAt(value.provider, "/responsibleHuman/provider");
+  stringAt(value.id, "/responsibleHuman/id");
+}
+
+export function validateCapturedSourceReceipt(value) {
+  canonicalJson(value, CAPTURED_SOURCE_RECEIPT_LIMITS);
+  objectAt(value, RECEIPT_FIELDS, RECEIPT_FIELDS);
+  if (value.schemaVersion !== 1) throw oatsError("unsupported-wire-version", "captured source receipt schemaVersion must be 1");
+  if (!["persistent", "helper"].includes(value.kind)) throw oatsError("invalid-declaration", "captured source receipt kind must be persistent or helper");
+  for (const [key, field] of [["home", value.home], ["work", value.work], ["context", value.context]]) absolutePath(field, `/${key}`);
+  if (value.context !== value.executionBinding?.deployment) throw oatsError("invalid-declaration", "captured source receipt context must equal its execution deployment");
+  stringAt(value.agent, "/agent"); stringAt(value.instance, "/instance"); stringAt(value.role, "/role");
+  for (const [pointer, text] of [["/agent", value.agent], ["/instance", value.instance], ["/role", value.role]]) if (text.includes("\0")) throw oatsError("invalid-declaration", `${pointer} contains NUL`);
+  if (!value.agent || !value.instance || Buffer.byteLength(value.role, "utf8") > 128 * 1024) throw oatsError("invalid-declaration", "captured source receipt identity/role is empty or exceeds its bound");
+  if (value.kind === "persistent") {
+    if (value.sourceIdentity === null) throw oatsError("invalid-declaration", "persistent captured source receipt needs a qualified soul identity");
+    validateSoulIdentity(value.sourceIdentity);
+  } else if (value.sourceIdentity !== null) throw oatsError("invalid-declaration", "helper captured source receipt must not claim a persistent soul identity");
+  validateExecutionBinding(value.executionBinding); human(value.responsibleHuman); validateProviderBinding(value.binding);
+  return value;
+}
+
+export function withCapturedSourceReceiptFile(home, receipt, run) {
+  validateCapturedSourceReceipt(receipt);
+  if (typeof run !== "function") throw oatsError("invalid-declaration", "captured source receipt consumer must be a function");
+  if (resolve(home) !== receipt.home) throw oatsError("invalid-declaration", "captured source receipt home differs from its invocation home");
+  const directory = mkdtempSync(join(portableStateDirectory(receipt.executionBinding.deployment, true), ".source-receipt-"));
+  const owned = lstatSync(directory), file = join(directory, "receipt.json"); let primary, result, completed = false;
+  try {
+    writeFileSync(file, canonicalJson(receipt, CAPTURED_SOURCE_RECEIPT_LIMITS), { flag: "wx", mode: 0o600 });
+    result = run({ OATS_SOURCE_RECEIPT_FILE: file }); completed = true; return result;
+  } catch (error) { primary = error; throw error; }
+  finally {
+    try {
+      const current = lstatSync(directory);
+      if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError("integrity-drift", "source receipt invocation directory ownership changed");
+      rmSync(directory, { recursive: true });
+    } catch (cleanup) {
+      if (!primary) {
+        const error = new AggregateError([cleanup], "captured source receipt cleanup failed after invocation", { cause: cleanup });
+        error.code = cleanup.code; error.invocationCompleted = completed; error.invocationResult = result; throw error;
+      }
+      const error = new AggregateError([primary, cleanup], "captured source receipt invocation and cleanup failed", { cause: primary });
+      error.code = primary.code;
+      if (primary.invocationCompleted) { error.invocationCompleted = true; error.invocationResult = primary.invocationResult; }
+      throw error;
+    }
+  }
+}

package/lib/config-data.mjs

@@ -0,0 +1,104 @@
+/** One bounded decoder for new portable documents. YAML is syntax, not an
+ * object-construction language: no tags, anchors, aliases, merges or coercive keys.
+ * Legacy core readers are unchanged until the explicit consumer migration. */
+import { Composer, CST, Lexer, Parser, isAlias, isMap, isScalar, isSeq } from "yaml";
+import { bytesIntegrity } from "./portable-digest.mjs";
+import { byteView, canonicalJson, dataLimits, decodeUtf8, parseStrictJson } from "./portable-values.mjs";
+import { oatsError } from "./errors.mjs";
+
+const pointerKey = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
+const SYNTAX_NODES = new Set(["scalar", "single-quoted-scalar", "double-quoted-scalar", "map-value-ind", "seq-item-ind", "flow-map-start", "flow-seq-start", "doc-mode", "doc-start"]);
+function boundedYaml(source, limits) {
+  const parser = new Parser();
+  // Duplicate decoded keys are checked in our linear own-key traversal below,
+  // not the composer's quadratic scan of every preceding mapping pair.
+  const composer = new Composer({ version: "1.2", schema: "core", uniqueKeys: false, strict: true, merge: false });
+  function* tokens() {
+    let nodes = 0;
+    for (const lexeme of new Lexer().lex(source)) {
+      const type = CST.tokenType(lexeme);
+      if (SYNTAX_NODES.has(type) && ++nodes > limits.maxEntries * 4 + 8) {
+        throw oatsError("resource-limit", "portable YAML syntax entry limit exceeded");
+      }
+      yield* parser.next(lexeme);
+      if (parser.stack.length > limits.maxDepth + 3) {
+        throw oatsError("resource-limit", "portable YAML syntax depth limit exceeded");
+      }
+    }
+    yield* parser.end();
+  }
+  let result;
+  for (const document of composer.compose(tokens(), true, source.length)) {
+    if (result) throw oatsError("invalid-declaration", "multiple portable YAML documents are not supported");
+    result = document;
+  }
+  return result;
+}
+export function parseConfigData(input, { format = "auto", origin = null, limits: requested = {} } = {}) {
+  const limits = dataLimits({ maxBytes: 1024 * 1024, ...requested });
+  const data = typeof input === "string" ? input : byteView(input);
+  const size = typeof data === "string" ? Buffer.byteLength(data, "utf8") : data.byteLength;
+  if (size > limits.maxBytes) throw oatsError("resource-limit", "portable document byte limit exceeded");
+  const source = decodeUtf8(input);
+  canonicalJson(origin, { maxBytes: 64 * 1024, maxDepth: 16, maxEntries: 1024 });
+  if (!["auto", "json", "yaml"].includes(format)) throw oatsError("invalid-declaration", "unsupported configuration syntax");
+  const json = format === "json" || (format === "auto" && /^[\s]*[\[{]/.test(source));
+  const origins = Object.create(null);
+  let entries = 0;
+  const mark = (pointer, depth, node) => {
+    if (depth > limits.maxDepth || ++entries > limits.maxEntries) {
+      throw oatsError("resource-limit", "portable document depth/entry limit exceeded");
+    }
+    origins[pointer] = { document: origin, pointer };
+    if (node?.range) origins[pointer].span = { start: node.range[0], end: node.range[1] };
+  };
+  let value;
+  if (json) {
+    value = parseStrictJson(source, limits);
+    const walk = (item, pointer, depth) => {
+      mark(pointer, depth);
+      if (item && typeof item === "object") {
+        for (const [key, child] of Object.entries(item)) walk(child, `${pointer}/${pointerKey(key)}`, depth + 1);
+      }
+    };
+    walk(value, "", 0);
+  } else {
+    let document;
+    try { document = boundedYaml(source, limits); }
+    catch (error) {
+      if (error.code === "resource-limit" || error.code === "invalid-declaration") throw error;
+      throw oatsError(error instanceof RangeError ? "resource-limit" : "invalid-declaration", "portable YAML could not be decoded");
+    }
+    if (document.errors.length || document.warnings.length || document.directives.yaml.version !== "1.2") {
+      const issue = document.errors[0] ?? document.warnings[0];
+      throw oatsError("invalid-declaration", `invalid portable YAML${issue ? ` (${issue.code})` : " version"}`);
+    }
+    const decode = (node, pointer, depth) => {
+      mark(pointer, depth, node);
+      if (node === null) return null;
+      if (isAlias(node) || node.anchor || node.tag) {
+        throw oatsError("invalid-declaration", "YAML anchors, aliases and explicit tags are not portable data");
+      }
+      if (isScalar(node)) return node.value;
+      if (isSeq(node)) return node.items.map((child, i) => decode(child, `${pointer}/${i}`, depth + 1));
+      if (isMap(node)) {
+        const result = Object.create(null);
+        for (const pair of node.items) {
+          const key = pair.key;
+          if (!isScalar(key) || typeof key.value !== "string" || key.anchor || key.tag
+              || (key.value === "<<" && key.type !== "QUOTE_DOUBLE" && key.type !== "QUOTE_SINGLE")) {
+            throw oatsError("invalid-declaration", "portable YAML mapping keys must be literal strings without merge syntax");
+          }
+          if (Object.hasOwn(result, key.value)) throw oatsError("invalid-declaration", "duplicate portable YAML key");
+          result[key.value] = decode(pair.value, `${pointer}/${pointerKey(key.value)}`, depth + 1);
+        }
+        return result;
+      }
+      throw oatsError("invalid-declaration", "unsupported portable YAML node");
+    };
+    value = decode(document.contents, "", 0);
+    // Enforce Unicode-scalar/finite JSON semantics even for YAML core scalars.
+    canonicalJson(value, limits);
+  }
+  return { value, origins, integrity: bytesIntegrity(Buffer.from(source, "utf8")) };
+}