@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.
- package/bin/oats.mjs +62 -32
- package/docs/configuration.md +26 -14
- package/docs/desktop-cli-api.md +82 -5
- package/docs/desktop.md +2 -2
- package/docs/execution-targets.md +82 -3
- package/docs/first-team.md +10 -10
- package/docs/harness-trust.md +147 -0
- package/docs/implementation.md +10 -4
- package/docs/launch-prompt-completion.md +70 -0
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.46.0.md +71 -0
- package/docs/release-notes/v0.47.0.md +93 -0
- package/docs/servers.md +1 -1
- package/docs/souls-and-instances.md +14 -9
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +2 -1
- package/lib/harness-trust-json.mjs +81 -0
- package/lib/harness-trust-toml.mjs +138 -0
- package/lib/harness-trust-write.mjs +221 -0
- package/lib/harness-trust.mjs +12 -11
- package/lib/instance-inspect.mjs +21 -2
- package/lib/instruction-composition.mjs +16 -3
- package/lib/launch-prompt-completion.mjs +67 -0
- package/lib/launch-prompt-evidence.mjs +159 -0
- package/lib/launch-prompt-fixtures/README.md +107 -4
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +88 -0
- package/lib/launch-prompt-fixtures/structural-completion.json +205 -0
- package/lib/launch-prompt-fixtures.mjs +21 -4
- package/lib/launch-prompts.mjs +25 -3
- package/lib/servers.mjs +3 -0
- package/lib/soul-composition.mjs +97 -0
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +23 -2
package/lib/launch-prompts.mjs
CHANGED
|
@@ -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
|
|
144
|
-
|
|
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
|
+
}
|
package/package-catalog.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "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.
|
|
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
|
|
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.
|