@awebai/oats 0.45.0 → 0.47.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.
@@ -17,7 +17,7 @@ const wait = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0,
17
17
  * frames (text, width, height), never a substring or whitespace normalization.
18
18
  * audit receives launch-prompt event data and returns appendEvent's checked result.
19
19
  */
20
- export function createLaunchPromptController({ home, startId, harness, policy = {}, transport, audit,
20
+ export function createLaunchPromptController({ home, startId, harness, policy = {}, transport, audit, retainFrame, classifyCompletion,
21
21
  now = () => performance.now(), sleep = wait, fixtures = [], geometry, validateExecutable, expectedHomeIdentity }) {
22
22
  const selectedHarness = typeof harness === "string" ? { name: harness } : { ...harness };
23
23
  const consent = { ...policy };
@@ -96,6 +96,12 @@ export function createLaunchPromptController({ home, startId, harness, policy =
96
96
  return candidates.length === 1 ? candidates[0] : null;
97
97
  }
98
98
  const exact = (a, b) => sameTarget(a, b) && a.width === b.width && a.height === b.height && a.text === b.text;
99
+ function retain(screen, outcome, recognition) {
100
+ try {
101
+ return retainFrame?.({ home, homeIdentity: { ...identity }, startId, target: { ...target },
102
+ screen: { text: screen.text, width: screen.width, height: screen.height }, outcome, recognition })?.ok === true;
103
+ } catch { return false; } // No raw text, OS diagnostic or private receipt escapes.
104
+ }
99
105
  function observe(t, before) {
100
106
  if (used) return terminal ?? { status: "blocked", answers: [], reason: "blocked: launch authority already used", receipt: [] };
101
107
  used = true;
@@ -140,8 +146,24 @@ export function createLaunchPromptController({ home, startId, harness, policy =
140
146
  sleep(Math.min(INTERVAL, remaining()));
141
147
  continue;
142
148
  }
143
- const match = matching(screen);
144
- if (!match) return finish("blocked", "blocked: unexpected prompt");
149
+ const submitted = answers.length === 1 && answers[0].status === "submitted";
150
+ // The initial exact question contains these same markers: completion
151
+ // policy is reachable ONLY after its sole key was durably submitted.
152
+ const completion = submitted ? classifyCompletion?.(screen) : null;
153
+ const match = completion === "blocked" ? null : matching(screen);
154
+ if (!match && completion === "completed") {
155
+ if (!retain(screen, "completed", "structural")) return finish("incomplete", "private launch evidence retention failed");
156
+ return finish("completed", "recognized launch boundary");
157
+ }
158
+ if (!match) {
159
+ let reason = "blocked: unexpected prompt";
160
+ if (submitted && screen.width === 110 && screen.height === 35 && retainFrame) {
161
+ // This is the exact object just compared, not a later pane capture.
162
+ // Private evidence cannot authorize input or change the launch outcome.
163
+ if (!retain(screen, "blocked", "unmatched")) reason += "; private launch evidence retention failed";
164
+ }
165
+ return finish("blocked", reason);
166
+ }
145
167
  const { fixture, frame } = match;
146
168
  const prior = answers.map(a => a.class);
147
169
  if (frame.kind === "completed") return finish("completed", "recognized launch boundary");
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
+ }
@@ -38,7 +38,7 @@
38
38
  },
39
39
  "oats.framework": {
40
40
  "url": "https://github.com/awebai/oats.git",
41
- "ref": "oats-framework/v1.6.1",
41
+ "ref": "oats-framework/v1.7.0",
42
42
  "path": "oats-package"
43
43
  }
44
44
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.45.0",
3
+ "version": "0.47.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",
@@ -60,7 +60,7 @@ members:
60
60
  - git:github.com/acme/agents # the host is a member too
61
61
  - git:github.com/acme/platform
62
62
  packages:
63
- oats.framework: v1.6.1 # bare versions resolve through the official catalog
63
+ oats.framework: v1.7.0 # bare versions resolve through the official catalog
64
64
  oats.okf: v4.1.1
65
65
  defaults:
66
66
  capabilities: { oats.core: { from: package } }
@@ -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,8 +192,22 @@ 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 retains the exact empty-frame families and, only after the submitted
196
+ channel Enter, can recognize the qualified bottom composer/effort-footer region.
197
+ See [the bounded completion contract](../../docs/launch-prompt-completion.md).
198
+ Known question markers block first; normal shortcut/interrupt hints do not.
199
+ Unknown dialogs retaining that region may be misclassified completed. Completion
200
+ closes input authority, not a readiness or idle-state promise. Missing effort or
201
+ trailing notices still block. Required private evidence failure is incomplete.
188
202
 
189
203
  Create and spawn only when asked. After the first spawn, the `oats.setup`
190
204
  skills carry the rest of the deployment (messaging, more souls, rebuilds); the
191
205
  `oats.authoring` package teaches writing capabilities, skills and souls. The
192
206
  model in full is `docs/workspaces.md` in the OATS repository.
207
+
208
+ For a retained launch-prompt block after a submitted answer, inspect the existing
209
+ launch event and private frame receipt as described in
210
+ `docs/execution-targets.md#private-unmatched-launch-evidence`. Do not transmit raw
211
+ screen text or treat a saved frame as a new accepted signature. A structurally completed frame is also saved privately. A saved artifact alone
212
+ does not establish completion: verify the final checked launch outcome. Missing
213
+ effort or unsupported footer shapes can block while the pane is active.