@awebai/oats 0.45.0 → 0.46.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -24,6 +24,7 @@ import { loadLocal } from "./workspace.mjs";
24
24
  import { ensureModuleTree } from "./operator-dispatch.mjs";
25
25
  import { operatorCoverage, operatorProblems } from "./operator-coverage.mjs";
26
26
  import { readLockIfPresent } from "./packages.mjs";
27
+ import { composeSoulInstructions } from "./soul-composition.mjs";
27
28
  /** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
28
29
  const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
29
30
  import { parseStrictJson } from "./canonical-json.mjs";
@@ -248,7 +249,25 @@ function soulRow(t) {
248
249
  return { soulsApi: SOULS_API, name: s.name, repoKey: s.repoKey, commit: s.commit, kind: s.external === true ? "external" : s.external === false ? "member" : null, path: s.path,
249
250
  description: def.description ?? null, work: def.work ?? null, harness: def.harness ?? null, model: def.model ?? null,
250
251
  declarations: declarationsOf(s.definition), declarationProblems: s.problems,
251
- instructions: s.soulDir ? readTextCapped(join(s.soulDir, "AGENTS.md")) : null };
252
+ instructions: s.soulDir ? readTextCapped(join(s.soulDir, "AGENTS.md")) : null,
253
+ // Feature soul-composed-instructions: only on a soul target that asked (inspect --instructions).
254
+ ...(t.kind === "soul" && t.composedInstructions !== undefined ? { composedInstructions: t.composedInstructions } : {}) };
255
+ }
256
+
257
+ /** The soul target with `composedInstructions` (feature soul-composed-instructions): the AGENTS.md a
258
+ * spawn of it here with no flags would write (lib/soul-composition.mjs), or null when the soul
259
+ * resolves but cannot be composed here — with the kernel's refusal as a problem naming
260
+ * composedInstructions, unless the soul copy's own problem (copyError) already says why. */
261
+ export async function withComposedInstructions(t, { compose = composeSoulInstructions } = {}) {
262
+ if (t.kind !== "soul") return t;
263
+ if (t.soul.copyError || !t.soul.soulDir || !t.prepared) return { ...t, composedInstructions: null };
264
+ try {
265
+ const { composedInstructions } = await compose({ deployment: t.deployment, prepared: t.prepared, soulDir: t.soul.soulDir });
266
+ return { ...t, composedInstructions };
267
+ } catch (e) {
268
+ if (typeof e?.code !== "string" || !e.code.startsWith("E_")) throw e;
269
+ return { ...t, composedInstructions: null, composedInstructionsProblem: { code: e.code, message: `composedInstructions: ${e.message}` } };
270
+ }
252
271
  }
253
272
 
254
273
  /** `oats inspect --json` on the workspace model. */
@@ -280,7 +299,7 @@ export function inspectDocument(t, { kernel }) {
280
299
  launchConfig: m.launch?.launchConfig ?? null, launchConfigDefault: m.launch?.launchConfigDefault === true, launched: !!m.launched, createdAt: m.createdAt || null,
281
300
  resolution: m.workspace?.resolution ?? null, soulDir: t.soul.soulDir, instructions: { ...readTextCapped(join(t.home, "AGENTS.md")), sources: m.instructions || [] } } : null,
282
301
  ...(m ? { identity: servedIdentityOf(m) } : {}),
283
- problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.discoveryError ? [t.discoveryError] : []),
302
+ problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.composedInstructionsProblem ? [t.composedInstructionsProblem] : []), ...(t.discoveryError ? [t.discoveryError] : []),
284
303
  ...t.modules.filter((x) => !x.manifest).map((x) => ({ code: "module-missing", message: `${x.name} is recorded but its module copy has no readable oats.json`, capability: x.name })),
285
304
  ...capabilities.filter((c) => !c.compatibility.ok).map((c) => ({ code: "capability-incompatible", message: `${c.id} requires oats ${c.compatibility.range}; this kernel is ${c.compatibility.kernel} (re-spawn from the deployment with a release whose range admits it)`, capability: c.id, range: c.compatibility.range, kernel: c.compatibility.kernel }))],
286
305
  };
@@ -1,11 +1,24 @@
1
1
  /** Formatting shared by current preparation and retained instruction projection.
2
2
  * Selection/order is supplied by the caller; this module never discovers config. */
3
3
 
4
- export function renderInstructionText(body, blocks) {
4
+ /** The composed document and where each part of it is: `body` and every `blocks[i]` as
5
+ * `[start, end)` in JS string units. The parts tile the text: the body starts at 0, each
6
+ * part ends where the next starts (after the blank separator line before the next opening
7
+ * marker), and the last part ends at `text.length`. A block starts at the `<` of its opening
8
+ * marker. The one renderer: renderInstructionText is its `.text`. */
9
+ export function renderInstructionParts(body, blocks) {
5
10
  let text = body.replace(/\n*$/, "\n");
11
+ const spans = [];
6
12
  for (const { source, file, content } of blocks) {
7
- text += `\n<!-- oats:${source} src=${file} -->\n${content.trim()}\n<!-- /oats:${source} -->\n`;
13
+ text += "\n";
14
+ const start = text.length;
15
+ text += `<!-- oats:${source} src=${file} -->\n${content.trim()}\n<!-- /oats:${source} -->\n`;
16
+ spans.push({ start });
8
17
  }
9
- return text;
18
+ const bodyEnd = spans.length ? spans[0].start : text.length;
19
+ return { text, body: { start: 0, end: bodyEnd }, blocks: spans.map(({ start }, i) => ({ start, end: i + 1 < spans.length ? spans[i + 1].start : text.length })) };
10
20
  }
11
21
 
22
+ export function renderInstructionText(body, blocks) {
23
+ return renderInstructionParts(body, blocks).text;
24
+ }
@@ -27,8 +27,8 @@ blocked outcome and sends no key. Captured folder-trust screens live only in
27
27
  `test/fixtures/launch-prompts/` as negative test evidence.
28
28
 
29
29
  Normal-output completion has a separate accepted finite policy: all surrounding
30
- bytes must equal one of the captured normal banners, and only its directory line may
31
- vary. Candidates are the exact home, a home-directory-relative `~` spelling,
30
+ bytes must equal one of the captured normal banners, except for its bounded
31
+ directory line and the source-derived billing atoms described below. Candidates are the exact home, a home-directory-relative `~` spelling,
32
32
  and `~/…/` followed by nonempty whole-component suffixes within the user home.
33
33
  Every complete line must fit 110 columns. Only conservative ASCII path components
34
34
  without traversal or empty segments qualify. These variants can only terminate
@@ -45,5 +45,40 @@ network and real-home access, seeded onboarding/trust/feature flag, one Enter,
45
45
  stable bytes at 200ms/1s/3s, and verified private-server cleanup. The prompt and
46
46
  blank transition were byte-identical to the earlier captures. No configuration,
47
47
  credentials or extracted source is included. No task or real-account/channel
48
- connection was tested. Other model/billing/effort/permission variants remain
49
- unqualified; a submitted answer can be followed by a retained blocked result.
48
+ connection was tested. Apart from the billing atoms below, other
49
+ model/billing/effort/permission variants remain unqualified; a submitted answer can be followed by a retained blocked result.
50
+
51
+ ## Source-derived subscription billing variants
52
+
53
+ **SOURCE-DERIVED / SYNTHETIC, not observed subscription captures:** the adapter
54
+ also constructs complete empty-frame variants for `Claude Max`, `Claude Pro`,
55
+ `Claude Team` and `Claude Enterprise`. It substitutes only the billing atom in
56
+ row 2 of each accepted API frame. Opus 5.5, auto mode, medium effort, separators,
57
+ empty input, notices and all remaining rows stay exact. The existing bounded
58
+ home-row policy is unchanged. These variants cannot authorize input.
59
+
60
+ Provenance is the same pinned 2.1.289 darwin-arm64 executable SHA256 above,
61
+ rechecked by read-only inspection. In that binary, `Knr` at the region containing
62
+ byte offset 182366506 falls back to the four subscription labels (or
63
+ `Claude API` by default). Before that fallback it may return
64
+ `Claude ${planDisplayName}` when the account value and gates permit it. Those
65
+ custom display names are not qualified unless their complete bytes equal an
66
+ explicitly accepted label; subscription membership alone does not qualify a
67
+ banner. The welcome-data
68
+ region containing offset 197387574 selects that billing value independently;
69
+ `Hgr` at offset 197387656 splits model/billing only when their display widths
70
+ plus the three-character separator exceed the available width. These four
71
+ short labels fit the accepted Opus 5.5 header at 110 columns. The test generates
72
+ these explicitly synthetic derivatives and checks the real qualification and
73
+ controller path with a test-local executable hash substitution. No binary or
74
+ proprietary extracted module is included.
75
+
76
+ The reported Max journey is different evidence: its later retained pane has
77
+ SHA256 `9eb587ab3ac7f97b746169619e02e3c8dd7df2c9069ff4368b6f0858c0964c68`,
78
+ 1597 bytes and 51 newline rows. It shows task activity and bypass-permissions
79
+ mode. Captured at 2026-10-07T14:31:54.028296Z, it follows the submitted Enter at
80
+ 14:31:45.365Z and block at 14:31:45.476Z. Its geometry, executable digest and
81
+ plugin version were not independently recorded; no earlier raw frame exists.
82
+ It is not padded, cropped or claimed as a qualified 110x35 first frame. See the
83
+ [published operator evidence](https://github.com/awebai/oats/issues/754#issuecomment-6040215059).
84
+ The billing-only extension does not recognize that later task-filled screen.
@@ -58,7 +58,8 @@ function captured(name) {
58
58
  }
59
59
 
60
60
  // Accepted as a completion-only finite policy, not a general claim about
61
- // Claude's path renderer. All surrounding bytes remain the captured frame.
61
+ // Claude's path renderer. Apart from the source-derived billing atom below,
62
+ // all surrounding bytes remain the captured frame.
62
63
  // Nothing produced here can match a prompt or authorize an input action.
63
64
  function completedFrames(home) {
64
65
  if (typeof home !== "string" || !/^\/[A-Za-z0-9_./-]+$/.test(home)) return [];
@@ -74,11 +75,16 @@ function completedFrames(home) {
74
75
  }
75
76
  const banners = ["frame-07-after-channel-200ms.txt", "frame-08-installed-after-channel-200ms.txt"];
76
77
  const prefix = " ▝▝ ▝▝ ";
77
- return banners.flatMap(name => [...paths].filter(path => prefix.length + path.length <= MANIFEST.geometry.width).map(path => {
78
+ // Source-derived billing atoms change only this header row. The complete
79
+ // empty input/status frame remains exact; these are not account captures.
80
+ // See launch-prompt-fixtures/README.md for the pinned source provenance.
81
+ const billings = ["API Usage Billing", "Claude Max", "Claude Pro", "Claude Team", "Claude Enterprise"];
82
+ return banners.flatMap(name => [...paths].filter(path => prefix.length + path.length <= MANIFEST.geometry.width).flatMap(path => billings.map(billing => {
78
83
  const variant = captured(name).split("\n");
84
+ variant[1] = "▝▜██████▀ Opus 5.5 · " + billing;
79
85
  variant[2] = prefix + path;
80
86
  return variant.join("\n");
81
- }));
87
+ })));
82
88
  }
83
89
 
84
90
  /** Read-only qualification: no version command or harness invocation. argv is
package/lib/servers.mjs CHANGED
@@ -708,6 +708,9 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
708
708
  if (!Array.isArray(remote.features) || !remote.features.includes("operations") || ![1, 2].includes(remote.operationsApi)) {
709
709
  throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise the operations contract (kernels from ${OPERATIONS_REMOTE_VERSION} do); upgrade it there; nothing was sent`);
710
710
  }
711
+ // `inspect --instructions` (feature soul-composed-instructions): an older host would ignore the
712
+ // flag and answer without the field — refused here instead, nothing sent.
713
+ if (cmd === "inspect" && args.includes("--instructions")) requireRemoteFeature(remote, target, "soul-composed-instructions");
711
714
  const scoped = args.includes("--dir") || args.includes("--home") ? args : [...args, "--dir", target.workspace];
712
715
  const { envelope, stderr } = runRemote(target, json([cmd, ...scoped]), io);
713
716
  return { envelope: envelope.result && typeof envelope.result === "object" ? { ...envelope, result: { ...envelope.result, server: serverId, ...(route ? { route: { home: route.home, instance: route.snapshot?.instance || null, frozen: !!route.snapshot } } : {}) } } : envelope, stderr };
@@ -0,0 +1,97 @@
1
+ /** The instructions a spawn of a soul would write, composed WITHOUT a spawn: the one path
2
+ * behind `oats doctor --soul` and `oats inspect --soul --instructions`.
3
+ *
4
+ * It runs spawn's own two halves: the kernel half (composeInstanceAgentsMd: the soul's
5
+ * AGENTS.md, the instance-boundary and work-mode blocks) and materialize (each capability's
6
+ * inject), into a scratch home OUTSIDE the deployment that is removed before it returns (and
7
+ * at exit). Nothing in the deployment is written. Capability blocks are reported
8
+ * home-relative (`.oats/modules/<cap>/<inject>`, where an instance carries them); kernel
9
+ * blocks keep the installed package's absolute path, as spawn writes them.
10
+ *
11
+ * Single-path guard: the reported text is re-rendered by renderInstructionParts (for the
12
+ * ranges), so rendering the same parts with the scratch paths must give back, byte for byte,
13
+ * the AGENTS.md materialize wrote — else E_COMPOSITION_INCOMPLETE, never a second answer. */
14
+ import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
15
+ import { tmpdir } from "node:os";
16
+ import { isAbsolute, join, relative, sep } from "node:path";
17
+ import { composeInstanceAgentsMd, findAgentAt } from "./core.mjs";
18
+ import { agentDirOf, materializePrepared } from "./instance-resolution.mjs";
19
+ import { renderInstructionParts } from "./instruction-composition.mjs";
20
+ import { oatsError } from "./errors.mjs";
21
+
22
+ /** The cap of a reported text, as inspect's `instructions` (JS string length). */
23
+ export const COMPOSED_TEXT_CAP = 200_000;
24
+
25
+ const fail = (code, message, details) => Object.assign(oatsError(code, message), details ? { details } : {});
26
+
27
+ /** A Node.js filesystem/system error (EACCES, EISDIR, ENOENT…), as opposed to a kernel refusal (E_…)
28
+ * or a programming error: the composition reports it as its own refusal, never a crash. */
29
+ const systemError = (e) => typeof e?.syscall === "string" && typeof e.code === "string" && !e.code.startsWith("E_");
30
+
31
+ /** `[start, end)` clamped to the capped text; `truncated` when the cap cut into the part. */
32
+ function clampSpan({ start, end }, length) {
33
+ return { start: Math.min(start, length), end: Math.min(end, length), truncated: end > length };
34
+ }
35
+
36
+ /** Compose `prepared`'s soul, whose copy is at `soulDir`, as a spawn here with no flags would.
37
+ * → { text, blocks, resolved, oatsCoreDeclared, composedInstructions }
38
+ * - text: the full document (capability markers home-relative);
39
+ * - blocks: every block in text order ({ source, file, content }, capability blocks
40
+ * home-relative and `materialized: true`);
41
+ * - composedInstructions: inspect's `{ file: null, text, truncated, resolution, body, sources }`,
42
+ * `text` capped at `cap` and every range clamped to it.
43
+ * Throws an E_ coded error when the soul cannot be composed here. `materialize` is a test seam. */
44
+ export async function composeSoulInstructions({ deployment, prepared, soulDir, cap = COMPOSED_TEXT_CAP, materialize = materializePrepared }) {
45
+ const soulName = prepared.soulEntry?.name ?? agentDirOf(prepared.soulEntry);
46
+ let agent, composition, body;
47
+ try {
48
+ agent = findAgentAt(join(deployment, "agents"), agentDirOf(prepared.soulEntry), soulDir);
49
+ if (!agent) throw fail("E_SOUL_UNKNOWN", `soul "${soulName}" was fetched but is not readable as a soul`);
50
+ const bodyFile = join(soulDir, "AGENTS.md");
51
+ if (!existsSync(bodyFile)) throw fail("E_SOUL_INCOMPLETE", `soul "${soulName}" has no canonical AGENTS.md (${bodyFile})`);
52
+ // The work mode and kind as a spawn with no flags derives them (spawnInstance: o.work || agent.work || "checkout").
53
+ composition = composeInstanceAgentsMd(soulDir, deployment, agent.name, agent.work || "checkout", agent.kind, prepared);
54
+ body = readFileSync(bodyFile, "utf8");
55
+ } catch (e) {
56
+ if (systemError(e)) throw fail("E_SOUL_INCOMPLETE", `soul "${soulName}" cannot be read here: ${e.message}`, { cause: e.code });
57
+ throw e;
58
+ }
59
+ let scratch;
60
+ try { scratch = realpathSync(mkdtempSync(join(tmpdir(), "oats-compose-home-"))); }
61
+ catch (e) { throw fail("E_MATERIALIZE_HOME", `cannot create a scratch home to compose soul "${soulName}" in under ${tmpdir()}: ${e.message}`, { why: "unwritable", cause: e.code }); }
62
+ const remove = () => { try { rmSync(scratch, { recursive: true, force: true }); } catch { /* best effort: a temporary copy only */ } };
63
+ process.once("exit", remove);
64
+ try {
65
+ const outcome = await materialize({ ...prepared, soulAgentsMd: composition.text, soulDir }, scratch);
66
+ const written = readFileSync(join(scratch, "AGENTS.md"), "utf8");
67
+ const materialized = Array.isArray(outcome?.blocks) ? outcome.blocks : [];
68
+ if (renderInstructionParts(body, [...composition.blocks, ...materialized]).text !== written) {
69
+ throw fail("E_COMPOSITION_INCOMPLETE", `soul "${soulName}": the instructions materialize wrote are not the kernel's composition plus the capability blocks it reported; nothing is reported in their place`);
70
+ }
71
+ const homeRelative = (file) => {
72
+ const rel = relative(scratch, file);
73
+ if (!rel || rel.startsWith("..") || isAbsolute(rel)) throw fail("E_COMPOSITION_INCOMPLETE", `soul "${soulName}": a capability block (${file}) is not inside the composed home`);
74
+ return rel.split(sep).join("/");
75
+ };
76
+ const capabilityBlocks = materialized.map((b) => ({ source: b.source, file: homeRelative(b.file), content: b.content, materialized: true }));
77
+ const blocks = [...composition.blocks, ...capabilityBlocks];
78
+ const parts = renderInstructionParts(body, blocks);
79
+ const length = Math.min(parts.text.length, cap);
80
+ const kernelBlocks = composition.blocks.length;
81
+ return {
82
+ text: parts.text, blocks, resolved: composition.resolved, oatsCoreDeclared: composition.oatsCoreDeclared,
83
+ composedInstructions: {
84
+ file: null, text: parts.text.slice(0, length), truncated: parts.text.length > length,
85
+ resolution: prepared.resolution?.revision ?? null,
86
+ body: clampSpan(parts.body, length),
87
+ sources: parts.blocks.map((span, i) => ({ source: blocks[i].source, file: i < kernelBlocks ? null : blocks[i].file, ...clampSpan(span, length) })),
88
+ },
89
+ };
90
+ } catch (e) {
91
+ if (systemError(e)) throw fail("E_MATERIALIZE_HOME", `soul "${soulName}" could not be composed in a scratch home: ${e.message}`, { why: "scratch", cause: e.code });
92
+ throw e;
93
+ } finally {
94
+ remove();
95
+ process.removeListener("exit", remove);
96
+ }
97
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.45.0",
3
+ "version": "0.46.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -177,7 +177,14 @@ Before configuring unattended development-channel confirmation, read
177
177
  it defaults false and requires the owner's explicit authorization for that home.
178
178
  Never infer consent from provider development mode, harness trust settings or
179
179
  a request to spawn. `workspaceTrust` is unsupported; remove it and handle
180
- folder trust with the harness (separate automation work: oats#712). Folder-trust
180
+ folder trust explicitly with `oats harness trust --dir D --harness claude --plan`,
181
+ then the same command without `--plan` to apply. Run it on the target host with
182
+ native configuration writers quiescent. Use `codex` or `all` for those selected
183
+ harnesses; inspect the exact canonical root and effective native file first.
184
+ The command changes only deployment-root trust and records an audit under
185
+ `D/.agents/harness-trust.jsonl`. A failure can retain an applied native change;
186
+ inspect its per-file outcome and audit before retrying. Nested Git boundaries
187
+ can prevent Claude inheritance. See [harness trust](../../docs/harness-trust.md). Folder-trust
181
188
  and API-key questions remain unexpected and blocked. Only the qualified Claude
182
189
  2.1.289 executable digest, `darwin-arm64` platform and 110x35 geometry documented
183
190
  there can match the exact aweb development-channel frame. A reported version
@@ -185,6 +192,9 @@ alone is insufficient. Preview reports policy without terminal input;
185
192
  `--no-launch` never answers. If launch returns `E_SPAWN_INCOMPLETE`, inspect the
186
193
  retained home/pane: do not respawn, repeat keys or treat `launched:false` as an
187
194
  absent process.
195
+ Completion additionally accepts source-derived Max/Pro/Team/Enterprise labels
196
+ on the exact empty Opus 5.5 / auto / medium frame. This interim support does not
197
+ cover task-filled or bypass-permissions screens and does not prove readiness.
188
198
 
189
199
  Create and spawn only when asked. After the first spawn, the `oats.setup`
190
200
  skills carry the rest of the deployment (messaging, more souls, rebuilds); the