@awebai/oats 0.55.0 → 0.56.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 +78 -62
- package/docs/capabilities.md +67 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
- package/docs/desktop-cli-api.md +317 -35
- package/docs/desktop-instance-start.md +105 -12
- package/docs/desktop.md +54 -7
- package/docs/execution-targets.md +184 -9
- package/docs/harness-trust.md +128 -11
- package/docs/implementation.md +54 -7
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +35 -16
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +26 -1
- package/docs/release-notes/v0.55.1.md +45 -0
- package/docs/release-notes/v0.56.0.md +699 -0
- package/docs/servers.md +21 -5
- package/docs/souls-and-instances.md +8 -4
- package/docs/tui.md +99 -26
- package/docs/upgrading.md +4 -1
- package/docs/workspaces.md +26 -6
- package/lib/automations.mjs +3 -4
- package/lib/bounded-read.mjs +18 -0
- package/lib/capability-show.mjs +13 -2
- package/lib/claim.mjs +3 -4
- package/lib/core.mjs +480 -152
- package/lib/errors.mjs +39 -0
- package/lib/harness-trust-write.mjs +119 -40
- package/lib/harness-trust.mjs +31 -18
- package/lib/instance-inspect.mjs +160 -11
- package/lib/instance-lifecycle.mjs +47 -30
- package/lib/packages.mjs +8 -5
- package/lib/pi-bridge.mjs +18 -19
- package/lib/remote.mjs +88 -51
- package/lib/retire-output.mjs +9 -4
- package/lib/schedule.mjs +3 -4
- package/lib/servers.mjs +39 -6
- package/lib/session-viewer.mjs +25 -1
- package/lib/triggers.mjs +3 -4
- package/lib/workspace.mjs +6 -6
- package/lib/worktree.mjs +10 -6
- package/lib/write-through-private-file.mjs +26 -0
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +108 -13
- package/packages/client/cli-locator.mjs +16 -14
- package/packages/client/deployment-panel.mjs +4 -3
- package/packages/client/display-text.mjs +2 -1
- package/packages/client/instance-events-contract.mjs +4 -3
- package/packages/client/instance-lifecycle.mjs +228 -0
- package/packages/client/instance-presentation.mjs +9 -0
- package/packages/client/instance-tree.mjs +10 -8
- package/packages/client/kernel-lines.mjs +3 -3
- package/packages/client/launch-contract.mjs +11 -0
- package/packages/client/lifecycle-cli.mjs +12 -6
- package/packages/client/lifecycle-confirmation.mjs +407 -0
- package/packages/client/lifecycle-contract.mjs +6 -2
- package/packages/client/own-codes.mjs +1 -0
- package/packages/client/panel-views.mjs +39 -2
- package/packages/client/readiness-contract.mjs +2 -2
- package/packages/client/remote-roster.mjs +50 -5
- package/packages/client/roster-sections.mjs +3 -3
- package/packages/client/session-start.mjs +98 -0
- package/packages/client/start-gate.mjs +46 -0
- package/packages/client/start-messages.mjs +17 -0
- package/packages/client/workspace-views.mjs +2 -2
- package/packages/record/README.md +4 -0
- package/packages/record/bin/recall.mjs +3 -2
- package/packages/tui/README.md +10 -6
- package/packages/tui/lib/actions.mjs +4 -2
- package/packages/tui/lib/client.mjs +5 -2
- package/packages/tui/lib/config.mjs +39 -9
- package/packages/tui/lib/main.mjs +83 -13
- package/packages/tui/lib/model.mjs +116 -11
- package/packages/tui/lib/open.mjs +45 -0
- package/packages/tui/lib/read.mjs +46 -10
- package/packages/tui/lib/store.mjs +64 -9
- package/packages/tui/lib/term/tty.mjs +71 -12
- package/packages/tui/lib/views/frame.mjs +115 -33
- package/packages/tui/lib/views/help.mjs +37 -8
- package/skills/oats-getting-started/SKILL.md +6 -3
package/lib/errors.mjs
CHANGED
|
@@ -45,6 +45,45 @@ export function errorCause(e) {
|
|
|
45
45
|
if (!isDefect(e)) return undefined;
|
|
46
46
|
return { name: e instanceof Error && typeof e.name === "string" && e.name ? e.name : "Error" };
|
|
47
47
|
}
|
|
48
|
+
/** The details of a spawn's refusal, by its code: the codes whose answer had details of its own
|
|
49
|
+
* before a spawn went through the door (awebai/oats#1047), each with exactly the keys it had. Every
|
|
50
|
+
* other code, and an error with none, carries the error's details only when `unconfirmed` is true
|
|
51
|
+
* (spawnFailedDetails): never a `home` taken from the error, which a consumer reads as retained
|
|
52
|
+
* effects. The table decides details, never the code. */
|
|
53
|
+
const hookReceipt = (e) => ({ hooks: e.details?.hooks ?? [], ...(e.details?.unconfirmed === true ? { unconfirmed: true } : {}) });
|
|
54
|
+
const SPAWN_REFUSAL_DETAILS = Object.freeze({
|
|
55
|
+
// A launch refusal is a fact about the selection: its own details, as the `E_LAUNCH_…` family's.
|
|
56
|
+
E_MODEL_UNKNOWN: (e) => e.details,
|
|
57
|
+
E_UNSUPPORTED_HARNESS: (e) => e.details,
|
|
58
|
+
E_HARNESS_UNAVAILABLE: (e) => e.details,
|
|
59
|
+
E_CLAUDE_CONFIG_REMOVED: (e) => e.details,
|
|
60
|
+
E_CHILD_SPAWNS_DISABLED: (e) => ({ parent: e.parent, policy: e.policy }),
|
|
61
|
+
E_BRANCH_EXISTS: () => undefined,
|
|
62
|
+
E_BASE_UNKNOWN: () => undefined,
|
|
63
|
+
// Interrupted while its worktree hooks ran (#796): rolled back, the message says how far.
|
|
64
|
+
E_INTERRUPTED: (e) => e.details,
|
|
65
|
+
// The hooks' receipt (paths only), and `unconfirmed` when the rollback could not confirm its effects.
|
|
66
|
+
E_REQUIRED_HOOK_FAILED: hookReceipt,
|
|
67
|
+
E_HOOK_ENVIRONMENT_CONTRACT: hookReceipt,
|
|
68
|
+
// The observed base could not be fetched into the clone: the clone, the repository and the commit.
|
|
69
|
+
E_REMOTE_UNREADABLE: (e) => (e.details?.commit ? e.details : spawnFailedDetails(e)),
|
|
70
|
+
// K6b: the fresh decision travels with the refusal, so a client previews again.
|
|
71
|
+
E_DECISION_STALE: (e) => ({ decision: e.decision }),
|
|
72
|
+
E_IDEMPOTENCY_CONFLICT: (e) => ({ instance: e.instance, home: e.home }),
|
|
73
|
+
E_PLACEMENT_TAKEN: (e) => ({ instance: e.instance, home: e.home }),
|
|
74
|
+
E_INSTANCE_NAME_TAKEN: (e) => ({ instance: e.instance, home: e.home ?? null, ...(e.session ? { session: e.session } : {}) }),
|
|
75
|
+
E_INSTANCE_NAME_INVALID: (e) => e.details,
|
|
76
|
+
E_SPAWN_INCOMPLETE: (e) => ({ ...e.details, instance: e.instance, home: e.home, launched: e.launched }),
|
|
77
|
+
});
|
|
78
|
+
const spawnFailedDetails = (e) => (e?.details?.unconfirmed === true ? e.details : undefined);
|
|
79
|
+
/** The `details` of the answer to an error `e` of `oats spawn` (bin/oats.mjs spawnFail): the table's
|
|
80
|
+
* for a code it holds, a launch refusal's own (`E_LAUNCH_…`), else spawnFailedDetails. */
|
|
81
|
+
export function spawnRefusalDetails(e) {
|
|
82
|
+
const code = kernelCode(e, null);
|
|
83
|
+
if (code && Object.hasOwn(SPAWN_REFUSAL_DETAILS, code)) return SPAWN_REFUSAL_DETAILS[code](e);
|
|
84
|
+
if (code?.startsWith("E_LAUNCH_")) return e.details;
|
|
85
|
+
return spawnFailedDetails(e);
|
|
86
|
+
}
|
|
48
87
|
/** `e` as a kernel error. One whose code an answer carries (isAnswerCode) is returned as it is. Any other is wrapped:
|
|
49
88
|
* the code `fallback`, `message` (default: its own), `details.cause` when it has one (errorCause)
|
|
50
89
|
* and the error itself as `cause`, so that whoever prints the answer still has a defect's stack. */
|
|
@@ -3,15 +3,40 @@
|
|
|
3
3
|
* but cannot eliminate, the race immediately before rename. No rollback. */
|
|
4
4
|
import * as fs from 'node:fs';
|
|
5
5
|
import { join, dirname, basename, resolve, isAbsolute } from 'node:path';
|
|
6
|
-
import { homedir } from 'node:os';
|
|
7
6
|
import { createHash, randomUUID } from 'node:crypto';
|
|
8
7
|
import { execFileSync } from 'node:child_process';
|
|
9
8
|
import { editClaudeTrust } from './harness-trust-json.mjs';
|
|
10
9
|
import { editCodexTrust } from './harness-trust-toml.mjs';
|
|
11
|
-
import { CONFIG_DIR_VAR, claudeTrusts, codexTrustsRoot, codexTrustedDirs,
|
|
10
|
+
import { CONFIG_DIR_VAR, claudeTrusts, codexTrustsRoot, codexTrustedDirs, launchConfigFolder } from './harness-trust.mjs';
|
|
11
|
+
import { launchEnvironment, unestablishedNote } from './core.mjs';
|
|
12
12
|
const digest = bytes => createHash('sha256').update(bytes).digest('hex');
|
|
13
13
|
const error = (code, message, details) => Object.assign(new Error(message), { code, details });
|
|
14
|
-
const broken = () => error('E_CONFIG_BROKEN', 'Native trust configuration is unreadable, unsafe, invalid, or outside the supported format; inspect the selected file before retrying.');
|
|
14
|
+
const broken = (refusal) => Object.assign(error('E_CONFIG_BROKEN', 'Native trust configuration is unreadable, unsafe, invalid, or outside the supported format; inspect the selected file before retrying.'), { refusal });
|
|
15
|
+
/** Which check refused a configuration file: fixed wording, never the file's content, a parser
|
|
16
|
+
* message or another configuration value. The marker case also gives the way forward. */
|
|
17
|
+
const REFUSALS = {
|
|
18
|
+
type: 'is not a regular file (a symbolic link, directory or other type)',
|
|
19
|
+
links: 'has more than one hard link',
|
|
20
|
+
owner: 'is owned by another user',
|
|
21
|
+
'special-mode': 'has setuid, setgid or sticky bits set',
|
|
22
|
+
marker: ({ harness, root }) => `has an extended-attribute (@) or ACL (+) marker in ls, which this writer neither copies nor removes; leave the file and its attributes as they are: accept ${harness}'s own folder-trust dialog for ${root} in a ${harness} session that uses this file, then check the harness-trust item of oats readiness`,
|
|
23
|
+
context: 'has a Linux security context that cannot be read',
|
|
24
|
+
metadata: 'its metadata could not be read (the ls probe failed or its answer is not recognized)',
|
|
25
|
+
changed: 'changed while it was being read',
|
|
26
|
+
// Raised while resolving a target, whose callers name it first; kept so the set is closed.
|
|
27
|
+
directory: 'is not in a usable configuration directory (a path that is not a directory, or one with no existing ancestor)',
|
|
28
|
+
size: 'is larger than 8 MiB',
|
|
29
|
+
utf8: 'is not valid UTF-8',
|
|
30
|
+
format: 'is not in the supported format (see "Qualified scope and formats" in docs/harness-trust.md)',
|
|
31
|
+
};
|
|
32
|
+
/** The `problem` of a file the plan refused. An exception no check named is reported by its errno
|
|
33
|
+
* code alone, else by the generic sentence; its message is never echoed. Exported for tests. */
|
|
34
|
+
export function refusalProblem(e, file, context) {
|
|
35
|
+
const wording = REFUSALS[e?.refusal];
|
|
36
|
+
if (wording) return `${file}: ${typeof wording === 'function' ? wording(context) : wording}`;
|
|
37
|
+
if (typeof e?.code === 'string' && /^E[A-Z0-9]+$/.test(e.code)) return `${file}: could not be read (${e.code})`;
|
|
38
|
+
return `${file}: ${broken().message}`;
|
|
39
|
+
}
|
|
15
40
|
const identity = s => `${s.dev}:${s.ino}`;
|
|
16
41
|
function stat(path) { try { return fs.lstatSync(path); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } }
|
|
17
42
|
/** GNU ls uses '.' for a security context alone, '+' for an ACL. macOS
|
|
@@ -19,18 +44,23 @@ function stat(path) { try { return fs.lstatSync(path); } catch (e) { if (e.code
|
|
|
19
44
|
* context is checked on the same-directory candidate before any replacement. */
|
|
20
45
|
export function nativeSecurityContext(path, { platform = process.platform, run = execFileSync } = {}) {
|
|
21
46
|
const flags = platform === 'darwin' ? ['-lde', path] : ['-ld', '--', path];
|
|
22
|
-
|
|
47
|
+
let mode; try { mode = run('ls', flags, { encoding: 'utf8' }).split(/\s/, 1)[0]; } catch { throw broken('metadata'); }
|
|
23
48
|
if (!/^-[-rwxStTs]{9}$/.test(mode)) {
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
if (
|
|
49
|
+
const marker = /^-[-rwxStTs]{9}(.)$/.exec(mode)?.[1];
|
|
50
|
+
if (marker === '+' || (platform === 'darwin' && marker === '@')) throw broken('marker');
|
|
51
|
+
if (platform !== 'linux' || marker !== '.') throw broken('metadata');
|
|
52
|
+
let context; try { context = run('ls', ['-Zd', '--', path], { encoding: 'utf8' }).trim().split(/\s/, 1)[0]; } catch { throw broken('context'); }
|
|
53
|
+
if (!context || context === '?' || context.split(':').length < 3) throw broken('context');
|
|
27
54
|
return context;
|
|
28
55
|
}
|
|
29
56
|
return null;
|
|
30
57
|
}
|
|
31
58
|
function regular(path, metadataProbe) {
|
|
32
59
|
const s = stat(path); if (!s) return null;
|
|
33
|
-
if (!s.isFile()
|
|
60
|
+
if (!s.isFile()) throw broken('type');
|
|
61
|
+
if (s.nlink !== 1) throw broken('links');
|
|
62
|
+
if (s.uid !== process.getuid?.()) throw broken('owner');
|
|
63
|
+
if (s.mode & 0o7000) throw broken('special-mode');
|
|
34
64
|
s.securityContext = metadataProbe(path);
|
|
35
65
|
return s;
|
|
36
66
|
}
|
|
@@ -39,28 +69,30 @@ function canonicalMissingDirectory(path) {
|
|
|
39
69
|
for (;;) {
|
|
40
70
|
const s = stat(at);
|
|
41
71
|
if (s) {
|
|
42
|
-
const real = fs.realpathSync.native(at); if (!fs.statSync(real).isDirectory()) throw broken();
|
|
72
|
+
const real = fs.realpathSync.native(at); if (!fs.statSync(real).isDirectory()) throw broken('directory');
|
|
43
73
|
return join(real, ...tail.reverse());
|
|
44
74
|
}
|
|
45
|
-
const parent = dirname(at); if (parent === at) throw broken(); tail.push(basename(at)); at = parent;
|
|
75
|
+
const parent = dirname(at); if (parent === at) throw broken('directory'); tail.push(basename(at)); at = parent;
|
|
46
76
|
}
|
|
47
77
|
}
|
|
48
78
|
function snapshot(file, metadataProbe) {
|
|
49
79
|
const s = regular(file, metadataProbe); if (!s) return { bytes: null, digest: null, identity: null, mode: null, securityContext: null };
|
|
50
80
|
const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
|
|
51
81
|
try {
|
|
52
|
-
if (identity(fs.fstatSync(fd)) !== identity(s)) throw broken();
|
|
53
|
-
const bytes = fs.readFileSync(fd); if (bytes.length > 8 * 1024 * 1024) throw broken();
|
|
54
|
-
if (identity(fs.lstatSync(file)) !== identity(s)) throw broken();
|
|
82
|
+
if (identity(fs.fstatSync(fd)) !== identity(s)) throw broken('changed');
|
|
83
|
+
const bytes = fs.readFileSync(fd); if (bytes.length > 8 * 1024 * 1024) throw broken('size');
|
|
84
|
+
if (identity(fs.lstatSync(file)) !== identity(s)) throw broken('changed');
|
|
55
85
|
return { bytes, digest: digest(bytes), identity: identity(s), mode: s.mode & 0o777, uid: s.uid, gid: s.gid, securityContext: s.securityContext };
|
|
56
86
|
} finally { fs.closeSync(fd); }
|
|
57
87
|
}
|
|
58
88
|
const same = (a, b) => a.digest === b.digest && a.identity === b.identity && a.mode === b.mode && a.uid === b.uid && a.gid === b.gid && a.securityContext === b.securityContext;
|
|
89
|
+
/** The native file `harness` reads under `env`, which holds exactly what selects it: the
|
|
90
|
+
* harness's selector, or the HOME its default folder is under. Nothing is read from this process. */
|
|
59
91
|
function nativePath(harness, env) {
|
|
60
|
-
const home = env.HOME || homedir(); if (!isAbsolute(home)) throw broken();
|
|
61
92
|
const override = harness === 'claude' ? env.CLAUDE_CONFIG_DIR : env.CODEX_HOME;
|
|
62
|
-
if (override && !isAbsolute(override)) throw broken();
|
|
63
|
-
|
|
93
|
+
if (override && !isAbsolute(override)) throw broken('relative-override');
|
|
94
|
+
if (!override && !(env.HOME && isAbsolute(env.HOME))) throw broken('relative-home');
|
|
95
|
+
const dir = override || (harness === 'claude' ? env.HOME : join(env.HOME, '.codex'));
|
|
64
96
|
return join(canonicalMissingDirectory(dir), harness === 'claude' ? '.claude.json' : 'config.toml');
|
|
65
97
|
}
|
|
66
98
|
function validAudit(file, metadataProbe) {
|
|
@@ -80,78 +112,125 @@ function ensureDirectory(path) {
|
|
|
80
112
|
if (stat(path)) { if (!fs.lstatSync(path).isDirectory() || fs.realpathSync.native(path) !== path) throw broken(); return; }
|
|
81
113
|
ensureDirectory(dirname(path)); fs.mkdirSync(path, { mode: 0o700 }); syncDirectory(dirname(path));
|
|
82
114
|
}
|
|
83
|
-
/** The configuration files `name` reads: the ambient one
|
|
84
|
-
*
|
|
85
|
-
* deduplicated by canonical directory.
|
|
115
|
+
/** The configuration files `name` reads: the ambient one, then one per launch configuration
|
|
116
|
+
* whose env moves the harness's configuration directory (its references resolved from `env`, this
|
|
117
|
+
* process), in name order, deduplicated by canonical directory. A configuration moves it with the
|
|
118
|
+
* harness's selector, or, when the launch has no selector at all (it sets none and the pane has
|
|
119
|
+
* none), with HOME: its default file is then under that HOME, which is the file its launch reads
|
|
120
|
+
* (the same answer, launchEnvironment over the same pane). The ambient file is the one a
|
|
121
|
+
* launch with no launch configuration reads, by the one answer every launch check reads
|
|
122
|
+
* (`launch`: core.mjs launchEnvironment over the deployment's session): the file its selector
|
|
123
|
+
* names, else the default one under its HOME; never this process's own, unless no pane's
|
|
124
|
+
* environment is established, which `note` then says with what was read instead. When that
|
|
125
|
+
* environment cannot be read the ambient target is `unreadable`, with the `problem`: refused, never
|
|
126
|
+
* a file guessed from this process. That holds for a tmux that could not say whether a server
|
|
127
|
+
* runs as well (`unread` on the answer): a failed read. A server known not to run, and a process
|
|
128
|
+
* with no tmux on its PATH to ask with (no prediction is made), leave this process's file as the
|
|
129
|
+
* one to write, with the `note`. No configuration directory is ever created. A launch
|
|
86
130
|
* configuration's directory that cannot be resolved or does not exist is a target with a
|
|
87
131
|
* `problem`: refused. A missing ambient directory means the harness has not run as this user:
|
|
88
132
|
* `skipped` when every harness was asked for (`named` false), a `problem` when this one was named. */
|
|
89
|
-
function trustTargets(name, env, launchConfigs, named) {
|
|
133
|
+
function trustTargets(name, env, launchConfigs, named, launch) {
|
|
90
134
|
const variable = CONFIG_DIR_VAR[name], targets = [], byFile = new Map();
|
|
91
135
|
const add = (target) => {
|
|
92
136
|
if (target.file && byFile.has(target.file)) { byFile.get(target.file).launchConfigs.push(...target.launchConfigs); return; }
|
|
93
137
|
if (target.file) byFile.set(target.file, target);
|
|
94
138
|
targets.push(target);
|
|
95
139
|
};
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
140
|
+
const selector = launch.of(variable);
|
|
141
|
+
// The default file is under HOME: read only when a launch has no selector.
|
|
142
|
+
const base = selector.absent ? launch.of('HOME') : null;
|
|
143
|
+
const failed = selector.problem ? selector : base?.problem ? base : null;
|
|
144
|
+
const unread = selector.unread ?? base?.unread;
|
|
145
|
+
const unestablished = what => `the file a ${name} launch with no launch configuration reads could not be established: ${what}`;
|
|
146
|
+
if (failed) add({ ambient: true, unreadable: true, launchConfigs: [], file: null, problem: unestablished(`${failed.problem}${failed.remedy ? `: ${failed.remedy}` : ''}`) });
|
|
147
|
+
else if (unread) add({ ambient: true, unreadable: true, launchConfigs: [], file: null, problem: unestablished(`${unread}. A server that could not be asked may run under another account than this process's, so this process's file is not written in its place`) });
|
|
148
|
+
else {
|
|
149
|
+
const ambientEnv = base ? { HOME: base.value } : { [variable]: selector.value };
|
|
150
|
+
let ambientFile = null, ambientProblem;
|
|
151
|
+
try { ambientFile = nativePath(name, ambientEnv); } catch (e) {
|
|
152
|
+
// What selects it names no usable file: say which name and where it was read, never its value.
|
|
153
|
+
const { source } = base ?? selector;
|
|
154
|
+
ambientProblem = unestablished(e.refusal === 'relative-home' || e.refusal === 'relative-override' ? `${source} is not an absolute path` : `${source} does not select a usable ${name} configuration directory`);
|
|
155
|
+
}
|
|
156
|
+
add({ env: ambientEnv, ambient: true, launchConfigs: [], file: ambientFile, selected: base ? null : selector, note: unestablishedNote(launch, base ? [variable, 'HOME'] : [variable]), ...(ambientProblem ? { problem: ambientProblem } : {}) });
|
|
157
|
+
}
|
|
99
158
|
for (const config of Object.values(launchConfigs).filter(c => c.harness === name).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
|
|
100
|
-
const resolved =
|
|
101
|
-
if (!resolved) continue;
|
|
159
|
+
const resolved = launchConfigFolder(variable, config.env, env);
|
|
102
160
|
const named = text => `launch configuration ${config.name}: ${text}`;
|
|
161
|
+
if (!resolved) {
|
|
162
|
+
// No selector of its own: its launch reads the pane's, as the ambient one does, and when
|
|
163
|
+
// there is none, the default file under its HOME. A HOME it sets itself moves that file.
|
|
164
|
+
if (!Object.hasOwn(config.env || {}, 'HOME') || !selector.absent) continue;
|
|
165
|
+
const home = launchEnvironment({ configEnv: config.env, configName: config.name, env, pane: launch.pane }).of('HOME');
|
|
166
|
+
if (home.problem) { add({ ambient: false, launchConfigs: [config.name], file: null, problem: named(home.problem) }); continue; }
|
|
167
|
+
const homeEnv = { HOME: home.value };
|
|
168
|
+
let file; try { file = nativePath(name, homeEnv); } catch (e) { add({ ambient: false, launchConfigs: [config.name], file: null, problem: named(`HOME ${JSON.stringify(home.value)} ${e.refusal === 'relative-home' ? 'is not an absolute path' : `does not select a usable ${name} configuration directory`}`) }); continue; }
|
|
169
|
+
add({ env: homeEnv, ambient: false, launchConfigs: [config.name], file, dir: dirname(file), underHome: true });
|
|
170
|
+
continue;
|
|
171
|
+
}
|
|
103
172
|
if (resolved.problem) { add({ ambient: false, launchConfigs: [config.name], file: null, problem: named(resolved.problem) }); continue; }
|
|
104
|
-
const targetEnv = {
|
|
173
|
+
const targetEnv = { [variable]: resolved.dir };
|
|
105
174
|
let file; try { file = nativePath(name, targetEnv); } catch { add({ ambient: false, launchConfigs: [config.name], file: null, problem: named(`${variable} ${resolved.dir} is not a usable directory`) }); continue; }
|
|
106
175
|
add({ env: targetEnv, ambient: false, launchConfigs: [config.name], file, dir: resolved.dir });
|
|
107
176
|
}
|
|
108
177
|
for (const t of targets) if (t.file && !t.problem && !fs.existsSync(dirname(t.file))) {
|
|
109
|
-
if (t.launchConfigs.length) t.problem = `launch configuration ${t.launchConfigs[0]}: ${variable} ${t.dir ?? dirname(t.file)} does not exist; OATS never creates a harness configuration directory: create it, or start ${name} with it once, then rerun`;
|
|
178
|
+
if (t.launchConfigs.length) t.problem = `launch configuration ${t.launchConfigs[0]}: ${t.underHome ? `${t.dir} (${name}'s directory under its HOME)` : `${variable} ${t.dir ?? dirname(t.file)}`} does not exist; OATS never creates a harness configuration directory: create it, or start ${name} with it once, then rerun`;
|
|
110
179
|
else if (named) t.problem = `${dirname(t.file)} does not exist: ${name} has not run as this user; OATS never creates a harness configuration directory: start ${name} once, then rerun`;
|
|
111
180
|
else t.skipped = `${dirname(t.file)} does not exist: ${name} has not run as this user`;
|
|
112
181
|
}
|
|
113
182
|
for (const t of targets) t.launchConfigs.sort();
|
|
114
183
|
return targets;
|
|
115
184
|
}
|
|
116
|
-
/** Planning performs reads only, including when native directories do not exist.
|
|
117
|
-
|
|
185
|
+
/** Planning performs reads only, including when native directories do not exist. `launch`: the
|
|
186
|
+
* one answer for a launch of this deployment with no launch configuration (trustTargets); a caller
|
|
187
|
+
* that gives none has established no pane's environment, so `env` is read and the plan says so.
|
|
188
|
+
* A refusal keeps its code, E_CONFIG_BROKEN, whenever a target is refused for its configuration or
|
|
189
|
+
* its file; E_RUNTIME_ENDPOINT_UNKNOWN when the only refused targets are those whose pane's
|
|
190
|
+
* environment could not be read. Either way the details hold the plan, the refused entries in it. */
|
|
191
|
+
export function planHarnessTrust(root, { harness = 'all', env = process.env, launchConfigs = {}, metadataProbe = nativeSecurityContext, launch = launchEnvironment({ env, pane: { unestablished: ': no launch environment was given' } }) } = {}) {
|
|
118
192
|
if (!['all', 'claude', 'codex'].includes(harness)) throw error('E_BAD_ARGS', '--harness must be claude, codex, or all');
|
|
119
193
|
// Native lookup preserves the on-disk casing on case-insensitive APFS; the
|
|
120
194
|
// JS realpath implementation can retain the caller's spelling as a wrong key.
|
|
121
195
|
root = fs.realpathSync.native(root);
|
|
122
|
-
const result = { operation: 'harness-trust', mode: 'plan', root, entries: [], audit: null, warnings: [] }, plans = [];
|
|
196
|
+
const result = { operation: 'harness-trust', mode: 'plan', root, entries: [], audit: null, warnings: [] }, plans = [], unreadable = new Set();
|
|
123
197
|
for (const name of harness === 'all' ? ['claude', 'codex'] : [harness]) {
|
|
124
|
-
for (const target of trustTargets(name, env, launchConfigs, harness !== 'all')) {
|
|
198
|
+
for (const target of trustTargets(name, env, launchConfigs, harness !== 'all', launch)) {
|
|
199
|
+
if (target.note) result.warnings.push(`${name}: ${target.note}`);
|
|
125
200
|
const key = ['projects', root, name === 'claude' ? 'hasTrustDialogAccepted' : 'trust_level'];
|
|
126
201
|
const entry = { harness: name, file: target.file, ambient: target.ambient, launchConfigs: target.launchConfigs, key, current: null, desired: name === 'claude' ? true : 'trusted', beforeDigest: null, afterDigest: null, status: 'refused', ...(target.problem ? { problem: target.problem } : {}) };
|
|
127
202
|
result.entries.push(entry);
|
|
203
|
+
if (target.unreadable) unreadable.add(entry);
|
|
128
204
|
if (target.skipped) { entry.status = 'skipped'; entry.reason = target.skipped; continue; }
|
|
129
205
|
if (target.problem || !target.file) continue;
|
|
130
206
|
try {
|
|
131
207
|
const file = target.file;
|
|
132
208
|
const before = snapshot(file, metadataProbe); entry.beforeDigest = before.digest;
|
|
133
209
|
const text = before.bytes?.toString('utf8') ?? (name === 'claude' ? '{}' : '');
|
|
134
|
-
if (before.bytes && !Buffer.from(text).equals(before.bytes)) throw broken();
|
|
135
|
-
|
|
210
|
+
if (before.bytes && !Buffer.from(text).equals(before.bytes)) throw broken('utf8');
|
|
211
|
+
// An editor's own exception is a format refusal; its message is never inspected.
|
|
212
|
+
let edited; try { edited = (name === 'claude' ? editClaudeTrust : editCodexTrust)(text, root); } catch { throw broken('format'); }
|
|
136
213
|
// Preflight the existing reader's supported representation as well as
|
|
137
214
|
// native syntax; never discover a known compatibility gap after writing.
|
|
138
|
-
if (name === 'codex' && !codexTrustedDirs(edited.text).has(root)) throw broken();
|
|
215
|
+
if (name === 'codex' && !codexTrustedDirs(edited.text).has(root)) throw broken('format');
|
|
139
216
|
const after = Buffer.from(edited.text);
|
|
140
217
|
entry.current = edited.current; entry.afterDigest = digest(after);
|
|
141
218
|
entry.status = before.bytes?.equals(after) ? 'unchanged' : 'change';
|
|
142
219
|
plans.push({ entry, before, after, env: target.env });
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
} catch { /* Per-file refusal; never echo native content or parser exceptions. */ }
|
|
220
|
+
if (target.ambient && target.selected) result.warnings.push(`${CONFIG_DIR_VAR[name]} selects ${target.selected.value} (${target.selected.source}); effective file ${file}`);
|
|
221
|
+
} catch (e) { if (entry.status === 'refused') entry.problem = refusalProblem(e, target.file, { harness: name, root }); /* Per-file refusal; never echo native content or parser exceptions. */ }
|
|
146
222
|
}
|
|
147
223
|
}
|
|
148
224
|
const problems = result.entries.filter(e => e.problem).map(e => e.problem);
|
|
149
|
-
|
|
225
|
+
const refused = result.entries.filter(e => e.status === 'refused');
|
|
226
|
+
if (refused.length && refused.every(e => unreadable.has(e))) throw error('E_RUNTIME_ENDPOINT_UNKNOWN', `Harness trust targets cannot be established; nothing was written: ${problems.join('; ')}`, result);
|
|
227
|
+
// Every refused entry names its problem; the generic sentence is a fallback that should not occur.
|
|
228
|
+
if (refused.length) throw error('E_CONFIG_BROKEN', problems.length ? `Harness trust refused; nothing was written: ${problems.join('; ')}` : broken().message, result);
|
|
150
229
|
return { result, plans };
|
|
151
230
|
}
|
|
152
|
-
export function harnessTrust(root, { harness = 'all', plan = false, env = process.env, launchConfigs = {}, checkpoint = () => {}, metadataProbe = nativeSecurityContext } = {}) {
|
|
231
|
+
export function harnessTrust(root, { harness = 'all', plan = false, env = process.env, launchConfigs = {}, checkpoint = () => {}, metadataProbe = nativeSecurityContext, launch } = {}) {
|
|
153
232
|
let prepared;
|
|
154
|
-
try { prepared = planHarnessTrust(root, { harness, env, launchConfigs, metadataProbe }); }
|
|
233
|
+
try { prepared = planHarnessTrust(root, { harness, env, launchConfigs, metadataProbe, ...(launch ? { launch } : {}) }); }
|
|
155
234
|
catch (e) { if (e.details?.operation === 'harness-trust') e.details.mode = plan ? 'plan' : 'apply'; throw e; }
|
|
156
235
|
const { result, plans } = prepared;
|
|
157
236
|
if (plan) return result;
|
package/lib/harness-trust.mjs
CHANGED
|
@@ -22,24 +22,32 @@ import { homedir } from "node:os";
|
|
|
22
22
|
const real = (p) => { try { return realpathSync.native(p); } catch { return resolve(p); } };
|
|
23
23
|
const userHome = (env) => env.HOME || homedir();
|
|
24
24
|
|
|
25
|
-
/** The variable that moves each harness's configuration
|
|
26
|
-
export const
|
|
25
|
+
/** The variable that moves each harness's configuration folder: the three selectors. */
|
|
26
|
+
export const HARNESS_FOLDER_VAR = Object.freeze({ claude: "CLAUDE_CONFIG_DIR", codex: "CODEX_HOME", pi: "PI_CODING_AGENT_DIR" });
|
|
27
|
+
/** Of those, the harnesses that have folder trust. */
|
|
28
|
+
export const CONFIG_DIR_VAR = { claude: HARNESS_FOLDER_VAR.claude, codex: HARNESS_FOLDER_VAR.codex };
|
|
27
29
|
/** The configuration file `harness` reads under `env`: $CLAUDE_CONFIG_DIR/.claude.json or
|
|
28
30
|
* ~/.claude.json; $CODEX_HOME/config.toml or ~/.codex/config.toml. */
|
|
29
31
|
export function harnessConfigFile(harness, env = process.env) {
|
|
30
32
|
if (harness === "claude") return join(env.CLAUDE_CONFIG_DIR || userHome(env), ".claude.json");
|
|
31
33
|
return join(env.CODEX_HOME || join(userHome(env), ".codex"), "config.toml");
|
|
32
34
|
}
|
|
33
|
-
/** The
|
|
34
|
-
* literal or a {fromEnv} resolved from the host `base`;
|
|
35
|
-
*
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
35
|
+
/** The harness folder a launch configuration's `env` names with `variable` (one of
|
|
36
|
+
* HARNESS_FOLDER_VAR): `{dir}` from a literal or a {fromEnv} resolved from the host `base`;
|
|
37
|
+
* `{problem}` when the reference is not set on this host (with its `fromEnv`) or the path is not
|
|
38
|
+
* absolute; null when the configuration leaves it to the host. The one reader of a launch
|
|
39
|
+
* configuration's folder, for every harness: the trust code (claude, codex) and the pi bridge. It
|
|
40
|
+
* lives here because this module owns the table of which variable moves which harness's folder and
|
|
41
|
+
* reads nothing but files, so core.mjs, harness-trust-write.mjs and pi-bridge.mjs each import it and
|
|
42
|
+
* none imports another for it. pi expands a leading `~` itself, against HOME, so its folder is read
|
|
43
|
+
* that way; Claude Code and Codex take the value as it is. */
|
|
44
|
+
export function launchConfigFolder(variable, configEnv = {}, base = process.env) {
|
|
45
|
+
if (!variable || !Object.hasOwn(configEnv || {}, variable)) return null;
|
|
46
|
+
const v = configEnv[variable];
|
|
47
|
+
const named = typeof v === "string" ? v : base[v?.fromEnv];
|
|
48
|
+
if (named === undefined) return { problem: `${variable} references ${v?.fromEnv}, not set on this host`, fromEnv: v?.fromEnv };
|
|
49
|
+
const dir = variable === HARNESS_FOLDER_VAR.pi ? named.replace(/^~(?=$|\/)/, () => userHome(base)) : named;
|
|
50
|
+
return isAbsolute(dir) ? { dir } : { problem: `${variable} ${JSON.stringify(named)} is not an absolute path` };
|
|
43
51
|
}
|
|
44
52
|
|
|
45
53
|
/** `dir` and its ancestors, nearest first. */
|
|
@@ -147,12 +155,17 @@ export function codexTrustsRoot(root, { env = process.env } = {}) {
|
|
|
147
155
|
const shellWord = value => /^[A-Za-z0-9_\/.,:@%+=-]+$/.test(value) ? value : "'" + value.replaceAll("'", "'\"'\"'") + "'";
|
|
148
156
|
|
|
149
157
|
/** The spawn and readiness warning for a launch whose harness configuration does not trust the
|
|
150
|
-
* deployment (`file`, the file the launch reads
|
|
151
|
-
*
|
|
152
|
-
*
|
|
153
|
-
*
|
|
154
|
-
|
|
158
|
+
* deployment (`file`, the file the launch reads, and `from`, where the launch gets the variable
|
|
159
|
+
* that selects it; `problem` when the launch configuration does not resolve it); null when
|
|
160
|
+
* `covered`, or for a harness without folder trust. A missing root entry does not prove the
|
|
161
|
+
* harness will prompt (a native gate may skip it), so this says only what the file lacks, and the
|
|
162
|
+
* one operator command that writes it (never run by readiness or a launch). `unreadable` (why,
|
|
163
|
+
* and what would make it readable): the environment of the launch's pane could not be read, so
|
|
164
|
+
* which file the launch will read is not known; the warning then says that, and nothing about
|
|
165
|
+
* trust. */
|
|
166
|
+
export function harnessTrustWarning({ harness, root, file, from, problem, unreadable, covered }) {
|
|
155
167
|
if (covered || !Object.hasOwn(CONFIG_DIR_VAR, harness)) return null;
|
|
168
|
+
if (unreadable) return `${harness} folder trust: the configuration file this launch will read could not be established (${unreadable}); nothing is said about its trust`;
|
|
156
169
|
if (problem) return `${harness} folder trust is not established: ${problem}`;
|
|
157
|
-
return `${harness} folder trust is not established in ${file}: oats harness trust --dir ${shellWord(root)}`;
|
|
170
|
+
return `${harness} folder trust is not established in ${file}${from ? ` (${from})` : ""}: oats harness trust --dir ${shellWord(root)}`;
|
|
158
171
|
}
|
package/lib/instance-inspect.mjs
CHANGED
|
@@ -11,12 +11,14 @@
|
|
|
11
11
|
* block or config levels, and there is no `trusted` check: declaring a package
|
|
12
12
|
* in `packages:` is the trust decision. */
|
|
13
13
|
import { spawnSync } from "node:child_process";
|
|
14
|
-
import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
|
|
14
|
+
import { accessSync, constants as fsConstants, existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
|
|
15
15
|
import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
16
|
-
import { capabilityManifests, kernelBin, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
|
|
16
|
+
import { capabilityManifests, skillEntriesIn, kernelBin, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, previewLaunchEnvironment, removedLaunchEnv, homeDeclaredLaunchEnv, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
|
|
17
17
|
import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests, soulsOffered } from "./instance-resolution.mjs";
|
|
18
18
|
import { declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
|
|
19
|
-
import { kernelCompatibility } from "./resolve.mjs";
|
|
19
|
+
import { kernelCompatibility, unsafeRelPath } from "./resolve.mjs";
|
|
20
|
+
import { compareCodepoints, decodeText, FILES_PER_SKILL, SKILL_DOC_BUDGET, skillDocDescription, TEXT_LIMIT } from "./capability-show.mjs";
|
|
21
|
+
import { readFileHead } from "./bounded-read.mjs";
|
|
20
22
|
import { discoveredTeamKeys, isRemovedTeamKeys, isTeamRefusal, recordedTeams, reportRows, soulKeyOf, teamKeyOf, soulTeams, teamModel, teamProblems } from "./teams.mjs";
|
|
21
23
|
import { launchLayers, launchReport } from "./launch-preference.mjs";
|
|
22
24
|
import { loadLocal } from "./workspace.mjs";
|
|
@@ -41,7 +43,7 @@ const real = (p) => { try { return realpathSync(p); } catch { return resolve(p);
|
|
|
41
43
|
/** A resolution refusal that is a readiness FACT (the soul cannot resolve as the
|
|
42
44
|
* lock stands), not a failure to answer: reported as a failing `installed` item —
|
|
43
45
|
* or, for a refusal of the soul's teams (isTeamRefusal), as a team item in `configured`. */
|
|
44
|
-
const RESOLUTION_FACTS = new Set(["E_PACKAGE_MISSING", "E_PACKAGE_INTEGRITY", "E_CAPABILITY_MISSING", "E_LOCK_SCHEMA"
|
|
46
|
+
const RESOLUTION_FACTS = new Set(["E_PACKAGE_MISSING", "E_PACKAGE_INTEGRITY", "E_CAPABILITY_MISSING", "E_LOCK_SCHEMA"]);
|
|
45
47
|
const isResolutionFact = (e) => RESOLUTION_FACTS.has(e?.code) || isTeamRefusal(e);
|
|
46
48
|
|
|
47
49
|
/** Is `name` an executable on PATH? (manifest `requires`, no shell). */
|
|
@@ -265,7 +267,9 @@ function soulRow(t) {
|
|
|
265
267
|
declarations: declarationsOf(s.definition), declarationProblems: s.problems,
|
|
266
268
|
instructions: s.soulDir ? readTextCapped(join(s.soulDir, "AGENTS.md")) : null,
|
|
267
269
|
// Feature soul-composed-instructions: only on a soul target that asked (inspect --instructions).
|
|
268
|
-
...(t.kind === "soul" && t.composedInstructions !== undefined ? { composedInstructions: t.composedInstructions } : {})
|
|
270
|
+
...(t.kind === "soul" && t.composedInstructions !== undefined ? { composedInstructions: t.composedInstructions } : {}),
|
|
271
|
+
// Feature soul-skills: only on a soul target that asked (inspect --skills).
|
|
272
|
+
...(t.kind === "soul" && t.skills !== undefined ? { skills: t.skills } : {}) };
|
|
269
273
|
}
|
|
270
274
|
|
|
271
275
|
/** The soul target with `composedInstructions` (feature soul-composed-instructions): the AGENTS.md a
|
|
@@ -284,6 +288,137 @@ export async function withComposedInstructions(t, { compose = composeSoulInstruc
|
|
|
284
288
|
}
|
|
285
289
|
}
|
|
286
290
|
|
|
291
|
+
// ---------- the soul's own skills (feature soul-skills) ----------
|
|
292
|
+
/** The whole `skills` field carries at most this many UTF-8 bytes of `text`, summed in answer order. */
|
|
293
|
+
export const SOUL_SKILLS_TEXT_BUDGET = 1024 * 1024;
|
|
294
|
+
const SKILLS_UNREADABLE = "soul-skills-unreadable", SKILL_FILES_UNREADABLE = "soul-skill-files-unreadable";
|
|
295
|
+
/** What readFileHead refuses: not a regular file, or not the file lstat found. */
|
|
296
|
+
const HEAD_REFUSALS = new Set(["invalid-declaration", "integrity-drift"]);
|
|
297
|
+
/** An entry the listing refuses, or a file it lists and cannot read safely: that skill's files are not listed. */
|
|
298
|
+
class Unlisted extends Error {}
|
|
299
|
+
/** A name that is not a safe relative path component (unsafeRelPath), or holds a control character. */
|
|
300
|
+
const unsafeName = (name) => unsafeRelPath(name) || /[\x00-\x1f\x7f]/.test(name);
|
|
301
|
+
/** A filesystem error (it has a syscall), a readFileHead refusal or one of ours, as the short reason a problem
|
|
302
|
+
* gives; anything else is a defect and is thrown. */
|
|
303
|
+
function unlistedReason(e, path) {
|
|
304
|
+
if (e instanceof Unlisted) return e.message;
|
|
305
|
+
if (typeof e?.syscall === "string") return `could not read ${path} (${e.code ?? e.syscall})`;
|
|
306
|
+
if (HEAD_REFUSALS.has(e?.code)) return `could not read ${path} (${e.message})`;
|
|
307
|
+
throw e;
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/* Containment, by the kernel's realpath idiom (manifestPath): every directory is listed, and every file read, only
|
|
311
|
+
* once its realpath lies inside the realpath of its skill, and the skill's inside the soul's. No symlink is ever
|
|
312
|
+
* followed: the walk takes entry types from readdir (lstat semantics), and a file is read through readFileHead
|
|
313
|
+
* (lstat a regular file, open O_NOFOLLOW|O_NONBLOCK, fstat the same file).
|
|
314
|
+
* The residual race, deliberately left: an ancestor directory swapped for a symlink in the instant between a check
|
|
315
|
+
* and the open can redirect a read (O_NOFOLLOW guards the last component only; Node has no openat). Only someone
|
|
316
|
+
* who can write the deployment's agents/ tree can do that, and that person already controls the soul copy and
|
|
317
|
+
* every instance's AGENTS.md. */
|
|
318
|
+
function insideOf(real, root, shown, where) {
|
|
319
|
+
const rel = relative(root, real);
|
|
320
|
+
if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Unlisted(`${shown} resolves outside ${where}`);
|
|
321
|
+
return real;
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/** Every regular file under the skill directory `dir` (`path` relative to the soul), recursively: paths relative
|
|
325
|
+
* to it, in codepoint order. A symlink (never followed), FIFO, socket or device is not listed; an entry with an
|
|
326
|
+
* unsafe name refuses the listing. */
|
|
327
|
+
function skillFilePaths(dir, realSkill, path) {
|
|
328
|
+
const out = [];
|
|
329
|
+
const walk = (abs, rel) => {
|
|
330
|
+
insideOf(realpathSync(abs), realSkill, rel ? `${path}/${rel}` : path, "its skill");
|
|
331
|
+
const dirs = [];
|
|
332
|
+
for (const e of readdirSync(abs, { withFileTypes: true })) {
|
|
333
|
+
const entry = rel ? `${rel}/${e.name}` : e.name;
|
|
334
|
+
if (unsafeName(e.name)) throw new Unlisted(`${JSON.stringify(entry)} is not a safe file name`);
|
|
335
|
+
if (e.isDirectory()) dirs.push(e.name);
|
|
336
|
+
else if (e.isFile()) out.push(entry);
|
|
337
|
+
}
|
|
338
|
+
for (const d of dirs) walk(join(abs, d), rel ? `${rel}/${d}` : d);
|
|
339
|
+
};
|
|
340
|
+
walk(dir, "");
|
|
341
|
+
return out.sort(compareCodepoints);
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
/** A listed file of the skill, proved inside it, read up to `max` bytes. → { bytes, size } */
|
|
345
|
+
function readSkillFile(dir, realSkill, path, rel, max) {
|
|
346
|
+
const abs = join(dir, ...rel.split("/"));
|
|
347
|
+
insideOf(realpathSync(abs), realSkill, `${path}/${rel}`, "its skill");
|
|
348
|
+
return readFileHead(abs, max);
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
/** One skill's row. Its files are listed and read in order against `budget` ({used, spent}); the budget is
|
|
352
|
+
* charged only when the skill's files are listed (a `files: null` skill is not in the answer's text). */
|
|
353
|
+
function soulSkillRow(soulDir, realSoul, { name, src }, budget) {
|
|
354
|
+
const path = relative(soulDir, src).split(sep).join("/");
|
|
355
|
+
const row = { name, path, description: null, files: null, filesTruncated: false };
|
|
356
|
+
const problem = (reason) => ({ row, problem: { code: SKILL_FILES_UNREADABLE, message: `skills: ${path}: could not list its files: ${reason}` } });
|
|
357
|
+
if (unsafeName(name)) return problem(`${JSON.stringify(name)} is not a safe skill name`);
|
|
358
|
+
let realSkill;
|
|
359
|
+
try { realSkill = insideOf(realpathSync(src), realSoul, path, "the soul"); } catch (e) { return problem(unlistedReason(e, path)); }
|
|
360
|
+
// The description by capabilities show's rule (skillDocDescription): SKILL.md read up to SKILL_DOC_BUDGET; null
|
|
361
|
+
// when it cannot be read, is a symlink, is binary or is larger.
|
|
362
|
+
let doc = null;
|
|
363
|
+
try { doc = readSkillFile(src, realSkill, path, "SKILL.md", SKILL_DOC_BUDGET); } catch (e) { unlistedReason(e, `${path}/SKILL.md`); }
|
|
364
|
+
if (doc) row.description = skillDocDescription(doc.bytes, doc.size);
|
|
365
|
+
let paths;
|
|
366
|
+
try { paths = skillFilePaths(src, realSkill, path); } catch (e) { return problem(unlistedReason(e, path)); }
|
|
367
|
+
let { used, spent } = budget;
|
|
368
|
+
const files = [];
|
|
369
|
+
for (const rel of paths.slice(0, FILES_PER_SKILL)) {
|
|
370
|
+
const filePath = `${path}/${rel}`;
|
|
371
|
+
let read;
|
|
372
|
+
// TEXT_LIMIT + 4 bytes: one past the bytes decodeText examines, so it answers on the head as on the whole file.
|
|
373
|
+
try { read = rel === "SKILL.md" && doc ? doc : readSkillFile(src, realSkill, path, rel, spent ? 0 : TEXT_LIMIT + 4); }
|
|
374
|
+
catch (e) { return problem(unlistedReason(e, filePath)); }
|
|
375
|
+
const omitted = { path: filePath, bytes: read.size, text: null, binary: false, truncated: false, omitted: true };
|
|
376
|
+
if (spent) { files.push(omitted); continue; }
|
|
377
|
+
const decoded = decodeText(read.bytes);
|
|
378
|
+
const cost = decoded.text === null ? 0 : Buffer.byteLength(decoded.text, "utf8");
|
|
379
|
+
if (used + cost > SOUL_SKILLS_TEXT_BUDGET) { spent = true; files.push(omitted); continue; }
|
|
380
|
+
used += cost;
|
|
381
|
+
files.push({ path: filePath, bytes: read.size, ...decoded });
|
|
382
|
+
}
|
|
383
|
+
Object.assign(budget, { used, spent });
|
|
384
|
+
return { row: { ...row, files, filesTruncated: paths.length > FILES_PER_SKILL }, problem: null };
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
/** The soul's own skills as `inspect --soul --skills` reports them: → { skills, problems }. Exactly the skills a
|
|
388
|
+
* spawn copies (spawn's skillEntriesIn, run strict, so a skill it cannot examine is a problem, not a missing
|
|
389
|
+
* skill), sorted by name in codepoint order; `[]` without a `skills/` directory; null, with a problem, when they
|
|
390
|
+
* cannot be listed (a symlinked `skills/` included, which is never followed). Read-only. */
|
|
391
|
+
export function soulSkills(soulDir) {
|
|
392
|
+
const unreadable = (reason) => ({ skills: null, problems: [{ code: SKILLS_UNREADABLE, message: `skills: ${reason}` }] });
|
|
393
|
+
const tree = join(soulDir, "skills");
|
|
394
|
+
try {
|
|
395
|
+
let st;
|
|
396
|
+
try { st = lstatSync(tree); } catch (e) { if (e?.code === "ENOENT") return { skills: [], problems: [] }; throw e; }
|
|
397
|
+
if (st.isSymbolicLink()) return unreadable("the soul's skills/ is a symbolic link, which is not followed");
|
|
398
|
+
if (!st.isDirectory()) return unreadable("the soul's skills is not a directory");
|
|
399
|
+
const realSoul = realpathSync(soulDir);
|
|
400
|
+
insideOf(realpathSync(tree), realSoul, "skills/", "the soul");
|
|
401
|
+
const budget = { used: 0, spent: false };
|
|
402
|
+
const skills = [], problems = [];
|
|
403
|
+
for (const entry of skillEntriesIn(tree, { strict: true }).sort((a, b) => compareCodepoints(a.name, b.name))) {
|
|
404
|
+
const { row, problem } = soulSkillRow(soulDir, realSoul, entry, budget);
|
|
405
|
+
skills.push(row);
|
|
406
|
+
if (problem) problems.push(problem);
|
|
407
|
+
}
|
|
408
|
+
return { skills, problems };
|
|
409
|
+
} catch (e) { return unreadable(unlistedReason(e, "skills/")); }
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
/** The soul target with `skills` (feature soul-skills): the soul's own skills from the soul copy inspect
|
|
413
|
+
* materialised (soulSkills). Null when that copy failed (its copyError already says why) or the soul does not
|
|
414
|
+
* resolve; reading problems are `skillsProblems`. */
|
|
415
|
+
export async function withSkills(t) {
|
|
416
|
+
if (t.kind !== "soul") return t;
|
|
417
|
+
if (t.soul.copyError || !t.soul.soulDir || !t.prepared) return { ...t, skills: null };
|
|
418
|
+
const { skills, problems } = soulSkills(t.soul.soulDir);
|
|
419
|
+
return { ...t, skills, ...(problems.length ? { skillsProblems: problems } : {}) };
|
|
420
|
+
}
|
|
421
|
+
|
|
287
422
|
/** `oats inspect --json` on the workspace model. */
|
|
288
423
|
/** What the target's capabilities declare and this kernel ignores (an unknown hook event):
|
|
289
424
|
* [{ code, capability, path, message }]. A soul's from its resolution, where each manifest is read
|
|
@@ -322,7 +457,7 @@ export function inspectDocument(t, { kernel }) {
|
|
|
322
457
|
launchConfig: m.launch?.launchConfig ?? null, launchConfigDefault: m.launch?.launchConfigDefault === true, launched: !!m.launched, createdAt: m.createdAt || null,
|
|
323
458
|
resolution: m.workspace?.resolution ?? null, soulDir: t.soul.soulDir, instructions: { ...readTextCapped(join(t.home, "AGENTS.md")), sources: m.instructions || [] } } : null,
|
|
324
459
|
...(m ? { identity: servedIdentityOf(m) } : {}),
|
|
325
|
-
problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.composedInstructionsProblem ? [t.composedInstructionsProblem] : []), ...(t.discoveryError ? [t.discoveryError] : []),
|
|
460
|
+
problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.composedInstructionsProblem ? [t.composedInstructionsProblem] : []), ...(t.skillsProblems || []), ...(t.discoveryError ? [t.discoveryError] : []),
|
|
326
461
|
...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 })),
|
|
327
462
|
...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 }))],
|
|
328
463
|
warnings: targetWarnings(t),
|
|
@@ -365,9 +500,15 @@ function launchItems(t) {
|
|
|
365
500
|
/** `harness-trust` (#341, #886): whether the configuration file the claude or codex session this
|
|
366
501
|
* subject launches reads trusts the deployment: a passing item naming that file, or a warning that
|
|
367
502
|
* folder trust is not established there (a missing root entry does not prove a prompt). The file is
|
|
368
|
-
* the launch's own:
|
|
369
|
-
* launch configuration, for a home under the agents root
|
|
370
|
-
*
|
|
503
|
+
* the launch's own (#993): the one its launch configuration names (an instance's recorded launch
|
|
504
|
+
* env; a soul's selected launch configuration, for a home under the agents root), else the one the
|
|
505
|
+
* pane it would run in selects, as a command that only reads can know it (core.mjs
|
|
506
|
+
* previewLaunchEnvironment): never this process's own. Two answers are `unknown`, each with its
|
|
507
|
+
* sentence in `reason`. No pane's environment is established (no OATS tmux server runs): `file` is
|
|
508
|
+
* what this process would read, the reason says what it holds and names what was read instead.
|
|
509
|
+
* The pane's environment could not be read: `file` is null, and the reason says which name, read
|
|
510
|
+
* from where, and nothing about trust. Reads, never writes, the harness's configuration
|
|
511
|
+
* (lib/harness-trust.mjs). */
|
|
371
512
|
function folderTrustItems(t) {
|
|
372
513
|
const harness = t.home ? t.meta?.harness : t.launch?.effective?.harness;
|
|
373
514
|
if (harness !== "claude" && harness !== "codex") return [];
|
|
@@ -377,8 +518,16 @@ function folderTrustItems(t) {
|
|
|
377
518
|
const config = t.home ? null : (() => { try { return launchConfigsAt(t.deployment)[name]; } catch { return undefined; } })();
|
|
378
519
|
const yolo = t.home ? (t.meta?.yolo ?? t.meta?.launch?.yolo) : config?.yolo;
|
|
379
520
|
const configEnv = t.home ? t.meta?.launch?.env : config?.env;
|
|
380
|
-
const
|
|
381
|
-
|
|
521
|
+
const env = obj(configEnv) ? configEnv : {};
|
|
522
|
+
// A home's launch removes what its providers declare and its recorded payload leaves out (core.mjs
|
|
523
|
+
// removedLaunchEnv): a selector among them is not the pane's.
|
|
524
|
+
const recipe = t.home && obj(t.meta?.launch) ? t.meta.launch : null;
|
|
525
|
+
const removed = recipe ? removedLaunchEnv({ declared: homeDeclaredLaunchEnv(t.meta, recipe, Object.fromEntries((t.modules || []).filter((m) => m.manifest).map((m) => [m.name, m.manifest]))), hooksEnv: obj(recipe.hooks?.env) ? recipe.hooks.env : {}, configEnv: env }) : [];
|
|
526
|
+
const trust = launchFolderTrust({ harness, home: t.home ?? t.agentsRoot, meta, yolo, configEnv: env, launchConfig: name,
|
|
527
|
+
launch: previewLaunchEnvironment({ configEnv: env, configName: name, removed, ...(t.home ? { home: t.home, meta: t.meta } : { deployment: t.deployment }) }) });
|
|
528
|
+
// Not the pane's: what this process would read says nothing certain about the launch.
|
|
529
|
+
const unestablished = trust.note ? trust.warning ?? `${harness} folder trust is established in ${trust.file}; that file is this process's, not known to be the one a launch will read: ${trust.note}` : null;
|
|
530
|
+
return [item("launch", trust.unreadable || unestablished ? "unknown" : trust.warning ? "fail" : "pass", { required: false, producer: "harness folder trust", code: "harness-trust", reason: unestablished ?? trust.warning,
|
|
382
531
|
harness, file: trust.file, deployment: t.deployment })];
|
|
383
532
|
}
|
|
384
533
|
/** `launch-prompt` (a warning): this home's last start blocked at a prompt that equals no
|