@awebai/oats 0.43.2 → 0.44.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.
Files changed (34) hide show
  1. package/bin/oats.mjs +119 -37
  2. package/docs/capabilities.md +37 -1
  3. package/docs/configuration.md +65 -0
  4. package/docs/desktop-cli-api.md +149 -4
  5. package/docs/execution-targets.md +75 -0
  6. package/docs/implementation.md +14 -1
  7. package/docs/knowledge.md +2 -1
  8. package/docs/oats-local.schema.json +19 -1
  9. package/docs/oats-workspace.schema.json +1 -1
  10. package/docs/release-notes/v0.43.3.md +22 -0
  11. package/docs/release-notes/v0.44.0.md +161 -0
  12. package/docs/schedules.md +27 -9
  13. package/docs/souls-and-instances.md +7 -0
  14. package/lib/core.mjs +254 -88
  15. package/lib/instance-events.mjs +1 -1
  16. package/lib/instance-inspect.mjs +39 -6
  17. package/lib/launch-prompt-fixtures/README.md +49 -0
  18. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +35 -0
  19. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +35 -0
  20. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +35 -0
  21. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +35 -0
  22. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +77 -0
  23. package/lib/launch-prompt-fixtures.mjs +114 -0
  24. package/lib/launch-prompt-policy.mjs +73 -0
  25. package/lib/launch-prompt-transport.mjs +102 -0
  26. package/lib/launch-prompts.mjs +216 -0
  27. package/lib/operator-coverage.mjs +134 -0
  28. package/lib/remote.mjs +15 -9
  29. package/lib/schedule.mjs +57 -10
  30. package/lib/teams-verbs.mjs +3 -3
  31. package/lib/triggers.mjs +2 -2
  32. package/lib/workspace.mjs +20 -2
  33. package/package.json +1 -1
  34. package/skills/oats-getting-started/SKILL.md +15 -0
@@ -14,7 +14,7 @@ import { spawnSync } from "node:child_process";
14
14
  import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
15
15
  import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
16
16
  import { fileURLToPath } from "node:url";
17
- import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
17
+ import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
18
18
  import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, soulCopyDigests } from "./instance-resolution.mjs";
19
19
  import { declaredSettings } from "./capability-contract.mjs";
20
20
  import { kernelCompatibility } from "./resolve.mjs";
@@ -22,6 +22,8 @@ import { discoveredTeamKeys, isRemovedTeamKeys, isTeamRefusal, recordedTeams, re
22
22
  import { launchLayers, launchReport } from "./launch-preference.mjs";
23
23
  import { loadLocal } from "./workspace.mjs";
24
24
  import { ensureModuleTree } from "./operator-dispatch.mjs";
25
+ import { operatorCoverage, operatorProblems } from "./operator-coverage.mjs";
26
+ import { readLockIfPresent } from "./packages.mjs";
25
27
  /** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
26
28
  const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
27
29
  import { parseStrictJson } from "./canonical-json.mjs";
@@ -133,6 +135,8 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
133
135
  kind: "instance", home: realHome, meta, deployment, agentsRoot, teams: live.teams, defaultTeam: live.defaultTeam ?? null, teamsSource: live.source, launch, launchCurrent, session: newSessionDefaults(deployment),
134
136
  recordedDefaultTeam: recordedTeams(meta).defaultTeam, teamModel: model, teamKey,
135
137
  subject: { kind: "instance", instance: meta.instance, home, soul: meta.agent },
138
+ // The soul as its hooks and dispatched commands get it (OATS_AGENT, OATS_SOUL_ID): not reported.
139
+ soulIdentity: { agent: meta.agent, id: stableSoulId({ home: realHome, soulDir, agentName: meta.agent }) },
136
140
  soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems],
137
141
  ...(obj(ws.soul?.package) && typeof ws.soul.package.id === "string" ? { package: { id: ws.soul.package.id, soul: ws.soul.name ?? meta.agent, version: ws.soul.package.version ?? null, commit: ws.soul.package.commit ?? ws.soul.commit ?? null, integrity: ws.soul.package.digest ?? null } } : {}) },
138
142
  workspace: { key: ws.key ?? null, name: typeof ws.name === "string" ? ws.name : discovery?.workspace?.name ?? null, deployment, commit: ws.commit ?? null, standalone: ws.standalone === true },
@@ -189,6 +193,8 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
189
193
  return {
190
194
  kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, defaultTeam, teamsSource: "live", teamModel: model, teamKey, launch, session: newSessionDefaults(deployment),
191
195
  subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null },
196
+ // The soul as a spawn of it records it and hands its hooks (OATS_AGENT, OATS_SOUL_ID): not reported.
197
+ soulIdentity: { agent: agentDirOf(soulEntry), id: preparedSoulIdOf(soulEntry) },
192
198
  soul: { name: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null, external: soulEntry.external === true, path: soulEntry.path ?? null,
193
199
  soulDir, definition: soulEntry.definition ?? null, problems: [], ...(soulCopyError ? { copyError: soulCopyError } : {}),
194
200
  ...(typeof soulEntry.package === "string" ? { package: { id: soulEntry.package, soul: soulEntry.name, version: soulEntry.version ?? null, commit: soulEntry.commit ?? null, integrity: soulEntry.digest ?? null } } : {}) },
@@ -327,6 +333,20 @@ function folderTrustItems(t) {
327
333
  const { warning } = launchFolderTrust({ harness, home: t.home ?? t.agentsRoot, meta, yolo });
328
334
  return warning ? [item("launch", "fail", { required: false, producer: "harness folder trust", code: "harness-trust", reason: warning, harness, deployment: t.deployment })] : [];
329
335
  }
336
+ /** Operator coverage (#671; warnings, never required): whether a soul this workspace offers composes
337
+ * oats.setup (lib/operator-coverage.mjs), for the workspace and for the subject's own teams, over the
338
+ * discovery this read already made. `operator-coverage-unknown` when that discovery is missing. */
339
+ async function operatorItems(t, { remoteOptions } = {}) {
340
+ let local = t.prepared?.local ?? null, lock = t.lock ?? null;
341
+ if (!local) { try { local = loadLocal(t.deployment).local; } catch { local = null; } }
342
+ if (!t.lock) { try { lock = readLockIfPresent(t.deployment); } catch { lock = null; } }
343
+ const coverage = t.discovery ? await operatorCoverage({ discovery: t.discovery, local, lock, teams: (t.teams || []).map((r) => r?.label), remoteOptions })
344
+ : { known: false, reason: t.discoveryError ? `the workspace could not be read: ${t.discoveryError.message}` : "the workspace was not read" };
345
+ const unknownRemedy = "make the workspace and its members readable from here (`oats workspace status` names the unreadable source), then read readiness again";
346
+ return operatorProblems(coverage, { workspace: t.workspace?.name ?? null, unknownRemedy }).map(({ code, label, message, remedy, excluded }) =>
347
+ item(label ? `team ${label}` : "operator", code === "operator-coverage-unknown" ? "unknown" : "fail",
348
+ { required: false, producer: "operator coverage", code, reason: message, remedy, ...(label ? { label } : {}), ...(excluded?.length ? { evidence: { excluded } } : {}) }));
349
+ }
330
350
  function roll(items) {
331
351
  const req = items.filter((i) => i.required !== false);
332
352
  if (!items.length) return "not-applicable";
@@ -334,14 +354,24 @@ function roll(items) {
334
354
  if (req.some((i) => i.status === "unknown")) return "unknown";
335
355
  return req.length ? "pass" : "not-applicable";
336
356
  }
337
- const item = (subject, status, { required = true, reason = null, producer = "kernel", evidence = null, remedy = null, ...rest } = {}) => ({ subject, status, required, reason, producer, evidence, remedy, ...rest });
357
+ /** A readiness item's free text is at most ITEM_TEXT characters (#725): the Desktop refuses a WHOLE answer
358
+ * whose item reason, remedy or problem message is over 1024 (packages/desktop/renderer/readiness-contract.mjs),
359
+ * and some producers carry remote text (a discovery error). Producers that bound their own text keep it. A
360
+ * provider's own answer (`result`) is relayed verbatim, never clipped here. */
361
+ export const ITEM_TEXT = 1000;
362
+ const bounded = (text) => (typeof text === "string" && text.length > ITEM_TEXT ? `${text.slice(0, ITEM_TEXT - 1)}…` : text);
363
+ const item = (subject, status, { required = true, reason = null, producer = "kernel", evidence = null, remedy = null, ...rest } = {}) =>
364
+ ({ subject, status, required, reason: bounded(reason), producer, evidence, remedy: bounded(remedy), ...rest,
365
+ ...(Array.isArray(rest.problems) ? { problems: rest.problems.map((p) => (obj(p) && typeof p.message === "string" ? { ...p, message: bounded(p.message) } : p)) } : {}) });
338
366
 
339
- /** The team/workspace facts a provider receives, as hooks get them (teamEnv). */
367
+ /** The team/workspace facts a provider receives, as hooks get them (teamEnv), and the soul's name and
368
+ * stable id as its hooks and dispatched commands get them. Every ambient OATS_* is removed first. */
340
369
  function providerEnv(t, capability, settings) {
341
370
  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^(OATS_|OAS_|PI_)/.test(k)));
342
371
  Object.assign(env, teamEnv({ workspace: { key: t.workspace.key, name: t.workspace.name, deployment: t.deployment }, teams: t.teams, defaultTeam: t.defaultTeam, teamsSource: t.teamsSource }));
343
372
  return Object.assign(env, { OATS_CAPABILITY: capability, OATS_SETTINGS: JSON.stringify(settings), OATS_SETTINGS_ORIGINS: JSON.stringify(t.payloadOrigins?.[capability] ?? {}), OATS_CLI_BIN: CLI_BIN, OATS_WORKSPACE: t.deployment,
344
- ...(t.home ? { OATS_INSTANCE: t.meta.instance, OATS_INSTANCE_HOME: t.home } : {}), OATS_AGENT: t.soul.name, ...(t.soul.soulDir ? { OATS_SOUL: t.soul.soulDir } : {}) });
373
+ ...(t.home ? { OATS_INSTANCE: t.meta.instance, OATS_INSTANCE_HOME: t.home } : {}), OATS_AGENT: t.soulIdentity?.agent || t.soul.name, ...(t.soulIdentity?.id ? { OATS_SOUL_ID: t.soulIdentity.id } : {}),
374
+ ...(t.soul.soulDir ? { OATS_SOUL: t.soul.soulDir } : {}) });
345
375
  }
346
376
  /** An executable inside a module directory: both sides realpath'd (a symlink out of
347
377
  * the module is an escape, as for the kernel's manifestPath), a regular file. */
@@ -395,7 +425,10 @@ export function runProviderCheck(t, mod, dir, { timeoutMs = 30000 } = {}) {
395
425
  if (doc.ok === false) {
396
426
  const e = doc.error;
397
427
  if (!obj(e) || typeof e.code !== "string" || (e.message !== undefined && typeof e.message !== "string")) return invalid();
398
- return unavailable(e.code, e.message ?? `${mod.name} refused the check`);
428
+ // The code becomes the kernel's problems[].code, which the Desktop takes up to 128 characters (#725):
429
+ // a longer or unprintable one is the provider's failure to answer, not a code.
430
+ const code = e.code.length <= 128 && !/[\x00-\x1f\x7f]/.test(e.code) ? e.code : "provider-unavailable";
431
+ return unavailable(code, e.message ?? `${mod.name} refused the check`);
399
432
  }
400
433
  const res = doc.result;
401
434
  if (doc.ok !== true || !obj(res) || Object.keys(res).some((k) => !["status", "problems", "warnings"].includes(k))
@@ -472,7 +505,7 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
472
505
  evidence: { command: req.command }, remedy: found ? null : req.install, ...cap(mod.name) }));
473
506
  }
474
507
  }
475
- configured.push(...teamItems(t), ...launchItems(t), ...folderTrustItems(t));
508
+ configured.push(...teamItems(t), ...launchItems(t), ...folderTrustItems(t), ...await operatorItems(t, { remoteOptions }));
476
509
  // member — the soul's member repository is a confirmed member of the workspace
477
510
  // (oats-membership.yaml backlink observed over the remotes); a package soul's is its
478
511
  // package instead (packageSoulItem).
@@ -0,0 +1,49 @@
1
+ # Development-channel launch fixture qualification
2
+
3
+ `launch-prompt-fixtures.mjs` qualifies the actual selected Claude executable by
4
+ reading its SHA256, without executing it. The qualified executable identity is
5
+ checked again before terminal actions. A harness name or reported version is
6
+ insufficient.
7
+
8
+ The accepted Claude 2.1.289 fixture is specific to darwin-arm64, binary SHA256
9
+ `03d66745e3bb69ec727d66023696f3820bc0a00a8a5ba725eb6706d0c67cbe69`, and
10
+ 110 columns by 35 rows. Captures preserve visible bytes, including the final
11
+ newline. The private transport pins only the newly launched owned window to this
12
+ geometry, and restores its previous geometry and sizing policy on every closure.
13
+
14
+ The fixture directory contains only the channel prompt, its blank transition,
15
+ the two known normal banners, and their hashes/provenance. It contains no harness binary,
16
+ extracted proprietary modules, configuration, or credentials.
17
+
18
+ The sole supported prompt requires the exact single selected argument
19
+ `--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`.
20
+ Approved-channel flags, multiple channels, and contradictory arguments do not
21
+ qualify. Explicit per-home `awebDevelopmentChannel: true` consent is required;
22
+ the default is off. The controller can send only one fixed Enter per launch.
23
+ There is no navigation or generic answer-sequence API.
24
+
25
+ Folder trust and all other prompts are unexpected: the controller records a
26
+ blocked outcome and sends no key. Captured folder-trust screens live only in
27
+ `test/fixtures/launch-prompts/` as negative test evidence.
28
+
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,
32
+ and `~/…/` followed by nonempty whole-component suffixes within the user home.
33
+ Every complete line must fit 110 columns. Only conservative ASCII path components
34
+ without traversal or empty segments qualify. These variants can only terminate
35
+ observation; none can authorize a key or assert harness/channel readiness.
36
+
37
+ Synthetic controller fixtures exercise state-machine behavior; they are not
38
+ production rendering evidence.
39
+
40
+ The installed-plugin capture (`frame-08-installed-after-channel-200ms.txt`)
41
+ qualifies aweb-channel 1.7.11 with Opus 5.5 / API Usage Billing / auto mode /
42
+ medium effort. Its manifest records the capture owner's provenance: native
43
+ plugin installation in isolated config/cache, dummy credentials, denied runtime
44
+ network and real-home access, seeded onboarding/trust/feature flag, one Enter,
45
+ stable bytes at 200ms/1s/3s, and verified private-server cleanup. The prompt and
46
+ blank transition were byte-identical to the earlier captures. No configuration,
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.
@@ -0,0 +1,35 @@
1
+
2
+ ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
3
+ WARNING: Loading development channels
4
+
5
+ --dangerously-load-development-channels is for local channel development only. Do not use this option to
6
+ run channels you have downloaded off the internet.
7
+
8
+ Please use --channels to run a list of approved channels.
9
+
10
+ Channels: plugin:aweb-channel@awebai-marketplace
11
+
12
+ ❯ 1. I am using this for local development
13
+ 2. Exit
14
+
15
+ Enter to confirm · Esc to cancel
16
+
17
+
18
+
19
+
20
+
21
+
22
+
23
+
24
+
25
+
26
+
27
+
28
+
29
+
30
+
31
+
32
+
33
+
34
+
35
+
@@ -0,0 +1,35 @@
1
+ ▐▛███▛█ Claude Code v2.1.289
2
+ ▝▜██████▀ Opus 5.5 · API Usage Billing
3
+ ▝▝ ▝▝ ~/…/instances/oats-kernel-expert-wake-lifecycle/work/708-fixtures/private-run/target
4
+
5
+ ▎ Channels (experimental) messages from plugin:aweb-channel@awebai-marketplace inject directly in this session
6
+ ▎ · restart without --dangerously-load-development-channels to stop
7
+ ▎ plugin:aweb-channel@awebai-marketplace · plugin not installed
8
+
9
+ ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
10
+ ❯ 
11
+ ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
12
+ ⏵⏵ auto mode on (shift+tab to cycle) · ← for agents ◐ medium · /effort
13
+
14
+
15
+
16
+
17
+
18
+
19
+
20
+
21
+
22
+
23
+
24
+
25
+
26
+
27
+
28
+
29
+
30
+
31
+
32
+
33
+
34
+
35
+
@@ -0,0 +1,35 @@
1
+ ▐▛███▛█ Claude Code v2.1.289
2
+ ▝▜██████▀ Opus 5.5 · API Usage Billing
3
+ ▝▝ ▝▝ ~/…/instances/oats-kernel-expert-wake-lifecycle/work/708-fixtures/installed-run/target
4
+
5
+ ▎ Channels (experimental) messages from plugin:aweb-channel@awebai-marketplace inject directly in this session
6
+ ▎ · restart without --dangerously-load-development-channels to stop
7
+
8
+ ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
9
+ ❯ 
10
+ ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
11
+ ⏵⏵ auto mode on (shift+tab to cycle) · ← for agents ◐ medium · /effort
12
+
13
+
14
+
15
+
16
+
17
+
18
+
19
+
20
+
21
+
22
+
23
+
24
+
25
+
26
+
27
+
28
+
29
+
30
+
31
+
32
+
33
+
34
+
35
+
@@ -0,0 +1,77 @@
1
+ {
2
+ "harness": "claude",
3
+ "version": "2.1.289",
4
+ "platform": "darwin-arm64",
5
+ "binarySha256": "03d66745e3bb69ec727d66023696f3820bc0a00a8a5ba725eb6706d0c67cbe69",
6
+ "geometry": {
7
+ "width": 110,
8
+ "height": 35
9
+ },
10
+ "frames": {
11
+ "frame-05-channel-seeded.txt": {
12
+ "sha256": "8a6dacbf45eab69ddf641cfcb292a5bb5c9eecb45690d0920e35834e24b30036",
13
+ "bytes": 763
14
+ },
15
+ "frame-06-first-after-channel.txt": {
16
+ "sha256": "5a5331bc2f941678f6c169fca0ad1ce0d133abc6b0946564311870e03b89b03a",
17
+ "bytes": 35
18
+ },
19
+ "frame-07-after-channel-200ms.txt": {
20
+ "sha256": "1b30359fcb9181d02faf10ed0780812079222cf6c54b60ed468ce037c1ff37e7",
21
+ "bytes": 1274
22
+ },
23
+ "frame-08-installed-after-channel-200ms.txt": {
24
+ "bytes": 1210,
25
+ "sha256": "f27d73189f2b1ba23899d99ba1596545f29d1d2494cb94b12ab314cf42426bef"
26
+ }
27
+ },
28
+ "installedCapture": {
29
+ "pluginVersion": "1.7.11",
30
+ "pluginDistSha256": "dc313b57f1aa952ea45685f6108187b7943a30a7b840a250d15efad0ff9c8e92",
31
+ "marketplaceCommit": "153033b9a8035617043a3450004399959c2ad9c6",
32
+ "network": "denied",
33
+ "credentials": "dummy only; real home read/write denied",
34
+ "seededInputs": [
35
+ "completed onboarding",
36
+ "trusted exact throwaway directory",
37
+ "dummy API key approval",
38
+ "cachedGrowthBookFeatures.tengu_harbor=true"
39
+ ],
40
+ "keys": [
41
+ "Enter"
42
+ ],
43
+ "serverAbsent": true,
44
+ "completionDisposition": "accepted bounded completion-only frame with existing finite canonical-home cwd family; no input authority or account/channel readiness",
45
+ "acceptanceMessage": "c1ba2c2d-d4c4-4673-8e13-12d65be0243d",
46
+ "captureOwner": "oats-kernel-expert-wake-lifecycle",
47
+ "installation": "native plugin CLI in isolated config and npm cache; no deployment settings or identity copied",
48
+ "observations": {
49
+ "before.txt": {
50
+ "bytes": 763,
51
+ "sha256": "8a6dacbf45eab69ddf641cfcb292a5bb5c9eecb45690d0920e35834e24b30036"
52
+ },
53
+ "selected.txt": {
54
+ "bytes": 763,
55
+ "sha256": "8a6dacbf45eab69ddf641cfcb292a5bb5c9eecb45690d0920e35834e24b30036"
56
+ },
57
+ "after-immediate.txt": {
58
+ "bytes": 35,
59
+ "sha256": "5a5331bc2f941678f6c169fca0ad1ce0d133abc6b0946564311870e03b89b03a"
60
+ },
61
+ "after-200ms.txt": {
62
+ "bytes": 1210,
63
+ "sha256": "f27d73189f2b1ba23899d99ba1596545f29d1d2494cb94b12ab314cf42426bef"
64
+ },
65
+ "after-1s.txt": {
66
+ "bytes": 1210,
67
+ "sha256": "f27d73189f2b1ba23899d99ba1596545f29d1d2494cb94b12ab314cf42426bef"
68
+ },
69
+ "after-3s.txt": {
70
+ "bytes": 1210,
71
+ "sha256": "f27d73189f2b1ba23899d99ba1596545f29d1d2494cb94b12ab314cf42426bef"
72
+ }
73
+ },
74
+ "banner": "Opus 5.5 / API Usage Billing / auto mode / medium effort",
75
+ "limits": "No task, real account, connection or native-receive success tested; other model/billing/effort/permission variants unqualified."
76
+ }
77
+ }
@@ -0,0 +1,114 @@
1
+ import { constants, openSync, closeSync, readSync, fstatSync, lstatSync, realpathSync, readFileSync } from "node:fs";
2
+ import { createHash } from "node:crypto";
3
+ import { homedir } from "node:os";
4
+
5
+ const ROOT = new URL("./launch-prompt-fixtures/claude-2.1.289-darwin-arm64/", import.meta.url);
6
+ const MANIFEST = JSON.parse(readFileSync(new URL("manifest.json", ROOT), "utf8"));
7
+ const PLUGIN = "plugin:aweb-channel@awebai-marketplace";
8
+ const DEVELOPMENT = "--dangerously-load-development-channels";
9
+
10
+ function executableDigest(path) {
11
+ let fd;
12
+ try {
13
+ const resolved = realpathSync(path);
14
+ fd = openSync(resolved, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
15
+ const before = fstatSync(fd);
16
+ if (!before.isFile() || !(before.mode & 0o111)) return null;
17
+ const hash = createHash("sha256"), buffer = Buffer.alloc(1024 * 1024);
18
+ let offset = 0;
19
+ // Bound to the original file size; a growing file cannot make qualification
20
+ // run indefinitely. Reject any change observed while reading it.
21
+ while (offset < before.size) {
22
+ const count = readSync(fd, buffer, 0, Math.min(buffer.length, before.size - offset), offset);
23
+ if (!count) return null;
24
+ hash.update(buffer.subarray(0, count));
25
+ offset += count;
26
+ }
27
+ const after = fstatSync(fd);
28
+ const current = lstatSync(resolved);
29
+ if (!current.isFile() || current.dev !== before.dev || current.ino !== before.ino || current.size !== before.size || current.mtimeMs !== before.mtimeMs || current.ctimeMs !== before.ctimeMs) return null;
30
+ if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || realpathSync(path) !== resolved) return null;
31
+ return { digest: hash.digest("hex"), validate() {
32
+ try {
33
+ const current = lstatSync(resolved);
34
+ return current.isFile() && realpathSync(path) === resolved
35
+ && ["dev", "ino", "size", "mode", "mtimeMs", "ctimeMs"].every(key => current[key] === before[key]);
36
+ } catch { return false; }
37
+ } };
38
+ } catch { return null; }
39
+ finally { if (fd !== undefined) closeSync(fd); }
40
+ }
41
+
42
+ function channelEligible(argv) {
43
+ if (!Array.isArray(argv) || argv.some(a => typeof a !== "string")) return false;
44
+ const channelFlags = argv.filter(a => a === DEVELOPMENT || a.startsWith(DEVELOPMENT + "=") || a === "--channels" || a.startsWith("--channels="));
45
+ if (channelFlags.length !== 1 || channelFlags[0] !== DEVELOPMENT) return false;
46
+ const at = argv.indexOf(DEVELOPMENT);
47
+ if (argv[at + 1] !== PLUGIN) return false;
48
+ // Variadic channel arguments must end before another flag or end of argv.
49
+ if (at + 2 < argv.length && !argv[at + 2].startsWith("--")) return false;
50
+ return argv.filter(a => a.startsWith("plugin:")).length === 1;
51
+ }
52
+
53
+ function captured(name) {
54
+ const text = readFileSync(new URL(name, ROOT), "utf8");
55
+ const expected = MANIFEST.frames[name];
56
+ if (!expected || Buffer.byteLength(text) !== expected.bytes || createHash("sha256").update(text).digest("hex") !== expected.sha256) throw new Error("fixture integrity");
57
+ return text;
58
+ }
59
+
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.
62
+ // Nothing produced here can match a prompt or authorize an input action.
63
+ function completedFrames(home) {
64
+ if (typeof home !== "string" || !/^\/[A-Za-z0-9_./-]+$/.test(home)) return [];
65
+ const components = home.slice(1).split("/");
66
+ if (components.some(part => !part || part === "." || part === "..")) return [];
67
+ const paths = new Set([home]);
68
+ const userHome = homedir();
69
+ if (home === userHome) paths.add("~");
70
+ else if (home.startsWith(userHome + "/")) {
71
+ paths.add("~" + home.slice(userHome.length));
72
+ const relative = home.slice(userHome.length + 1).split("/");
73
+ for (let index = 0; index < relative.length; index++) paths.add("~/…/" + relative.slice(index).join("/"));
74
+ }
75
+ const banners = ["frame-07-after-channel-200ms.txt", "frame-08-installed-after-channel-200ms.txt"];
76
+ const prefix = " ▝▝ ▝▝ ";
77
+ return banners.flatMap(name => [...paths].filter(path => prefix.length + path.length <= MANIFEST.geometry.width).map(path => {
78
+ const variant = captured(name).split("\n");
79
+ variant[2] = prefix + path;
80
+ return variant.join("\n");
81
+ }));
82
+ }
83
+
84
+ /** Read-only qualification: no version command or harness invocation. argv is
85
+ * the actual selected harness argv (excluding its executable). A reported
86
+ * version, name, or environment alone is never sufficient to enable a matcher.
87
+ * The channel frame is path-independent. Completion uses a finite accepted
88
+ * directory-display family that cannot authorize keys.
89
+ */
90
+ export function qualifyLaunchPromptFixtures({ home, harness, executablePath, argv = [], platform = process.platform, arch = process.arch }) {
91
+ const name = typeof harness === "string" ? harness : harness?.name;
92
+ const pin = `${platform}-${arch}`;
93
+ const result = { harness: { name, platform: pin, developmentChannelEligible: false }, fixtures: [] };
94
+ if (name !== "claude" || pin !== MANIFEST.platform) return result;
95
+ const executable = executableDigest(executablePath);
96
+ if (executable?.digest !== MANIFEST.binarySha256) return result;
97
+ result.validateExecutable = executable.validate;
98
+ result.harness.version = MANIFEST.version;
99
+ result.geometry = { ...MANIFEST.geometry };
100
+ result.harness.developmentChannelEligible = channelEligible(argv);
101
+ const base = { home, harness: name, version: MANIFEST.version, platform: pin };
102
+ const frame = (text, kind, after, rest = {}) => ({ text, kind, after, ...MANIFEST.geometry, ...rest });
103
+ try {
104
+ if (result.harness.developmentChannelEligible) {
105
+ result.fixtures.push({ ...base, id: "claude-2.1.289-darwin-arm64-development-channel", frames: [
106
+ frame(captured("frame-05-channel-seeded.txt"), "prompt", [], { class: "awebDevelopmentChannel" }),
107
+ ...[[], ["awebDevelopmentChannel"]].flatMap(after => completedFrames(home).map(text => frame(text, "completed", after))),
108
+ ] });
109
+ }
110
+ } catch {
111
+ result.fixtures = [];
112
+ }
113
+ return result;
114
+ }
@@ -0,0 +1,73 @@
1
+ /** Host-local launch consent. Never merge this policy with recipes or provider settings. */
2
+ import { lstatSync, realpathSync, statSync } from "node:fs";
3
+ import { basename, dirname, isAbsolute, join, resolve } from "node:path";
4
+ import { oatsError } from "./errors.mjs";
5
+
6
+ const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
7
+ const pointer = (value) => value.replace(/~/g, "~0").replace(/\//g, "~1");
8
+ const root = "/launchPromptAnswers";
9
+
10
+ /** Validate, rather than silently normalize, an exact home. Missing suffixes are
11
+ * allowed for preview; dangling symlinks and inaccessible ancestors fail closed. */
12
+ export function canonicalLaunchPromptHome(home) {
13
+ if (typeof home !== "string" || !isAbsolute(home) || home.includes("\0") || /[*?\[\]{}]/u.test(home) || resolve(home) !== home) {
14
+ throw new Error("use an absolute canonical instance-home path without wildcards, dot segments or a trailing separator");
15
+ }
16
+ let ancestor = home;
17
+ const suffix = [];
18
+ while (true) {
19
+ try {
20
+ lstatSync(ancestor);
21
+ break;
22
+ } catch (error) {
23
+ if (error.code !== "ENOENT") throw error;
24
+ const parent = dirname(ancestor);
25
+ if (parent === ancestor) throw error;
26
+ suffix.unshift(basename(ancestor));
27
+ ancestor = parent;
28
+ }
29
+ }
30
+ if (!statSync(ancestor).isDirectory()) throw new Error("the instance home and its existing ancestor must be directories");
31
+ const canonical = join(realpathSync(ancestor), ...suffix);
32
+ if (canonical !== home) throw new Error(`use the canonical instance-home path ${JSON.stringify(canonical)} instead of a symlink alias`);
33
+ return canonical;
34
+ }
35
+
36
+ /** Complete policy validation, also usable without loading a workspace. */
37
+ export function launchPromptPolicyProblems(policy) {
38
+ const problems = [];
39
+ const issue = (path, message, reason) => problems.push({ path, message, ...(reason ? { reason } : {}) });
40
+ if (!object(policy)) return [{ path: root, message: "must be an object" }];
41
+ for (const key of Object.keys(policy)) if (key !== "homes") issue(`${root}/${pointer(key)}`, "unknown property");
42
+ if (!Object.hasOwn(policy, "homes")) return problems;
43
+ if (!object(policy.homes)) { issue(`${root}/homes`, "must be an object"); return problems; }
44
+ for (const [home, consent] of Object.entries(policy.homes)) {
45
+ const path = `${root}/homes/${pointer(home)}`;
46
+ try { canonicalLaunchPromptHome(home); } catch (error) { issue(path, error.message, "noncanonical-home"); }
47
+ if (!object(consent)) { issue(path, "must be an object"); continue; }
48
+ for (const [key, value] of Object.entries(consent)) {
49
+ if (key === "workspaceTrust") issue(`${path}/${key}`, "workspaceTrust is not supported: remove this key and handle folder trust with the harness; folder-trust automation is tracked separately in oats#712. awebDevelopmentChannel authorizes only the aweb development-channel confirmation", "unsupported-launch-prompt");
50
+ else if (key !== "awebDevelopmentChannel") issue(`${path}/${pointer(key)}`, "unknown property");
51
+ else if (typeof value !== "boolean") issue(`${path}/${key}`, "must be a boolean");
52
+ }
53
+ }
54
+ return problems;
55
+ }
56
+
57
+ /** Exact-home consent + config JSON-pointer provenance for previews/controllers.
58
+ * Call again after home creation; the controller must separately retain and
59
+ * recheck directory identity before each input. No captured policy is authority. */
60
+ export function effectiveLaunchPromptPolicy(local, home, source) {
61
+ const disabled = { awebDevelopmentChannel: false, consentSource: null };
62
+ if (!object(local) || !Object.hasOwn(local, "launchPromptAnswers")) return disabled;
63
+ const problems = launchPromptPolicyProblems(local.launchPromptAnswers);
64
+ if (problems.length) throw oatsError("E_WORKSPACE_SCHEMA", `invalid launchPromptAnswers: ${problems.map((p) => `${p.path}: ${p.message}`).join("; ")}`, { problems });
65
+ try { canonicalLaunchPromptHome(home); } catch { return disabled; }
66
+ const homes = local.launchPromptAnswers.homes;
67
+ if (!homes || !Object.hasOwn(homes, home)) return disabled;
68
+ const consent = homes[home];
69
+ return {
70
+ awebDevelopmentChannel: consent.awebDevelopmentChannel === true,
71
+ consentSource: typeof source === "string" && source.length ? `${source}#${root}/homes/${pointer(home)}` : null,
72
+ };
73
+ }