@adamchanadam/agent-handoff-kit 0.3.67 → 0.4.1
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/README.en.md +44 -180
- package/README.md +45 -187
- package/bin/agent-handoff-kit.mjs +149 -36
- package/bin/commands.mjs +134 -0
- package/bin/handoff-read.mjs +88 -0
- package/bin/installed-file-contract.mjs +79 -63
- package/bin/migration-baselines/official-origin-catalog.json +433 -1
- package/bin/official-origin-catalog.mjs +267 -257
- package/bin/progress/ICON-LICENSE.txt +21 -0
- package/bin/progress/agent-handoff-kit-logo2-256.png +0 -0
- package/bin/progress/assets.mjs +6 -0
- package/bin/progress/dashboard-hero.png +0 -0
- package/bin/progress/dashboard.mjs +134 -0
- package/bin/progress/icons.svg +36 -0
- package/bin/progress/index.html +31 -0
- package/bin/progress/launch.mjs +40 -0
- package/bin/progress/open.mjs +43 -0
- package/bin/progress/project-version.mjs +121 -0
- package/bin/progress/projection.mjs +144 -0
- package/bin/progress/renderer.js +152 -0
- package/bin/progress/server.mjs +78 -0
- package/bin/progress/styles.css +31 -0
- package/bin/upgrade-inventory.mjs +153 -273
- package/docs/commands.md +61 -0
- package/docs/progress.md +73 -0
- package/package.json +3 -1
- package/packs/closeout.md +71 -66
- package/runtime-core/AGENTS.core.md +112 -101
- package/runtime-core/PROJECT_INDEX.md +8 -1
- package/runtime-core/SESSION_HANDOFF.md +157 -147
- package/runtime-core/SESSION_LOG.md +2 -0
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
// Read-only transport for a handoff. Returned ranges are not proof that an AI
|
|
2
|
+
// received, understood, or is authorized to act on the document.
|
|
3
|
+
import { constants, closeSync, fstatSync, lstatSync, openSync, readFileSync, realpathSync } from "node:fs";
|
|
4
|
+
import { createHash } from "node:crypto";
|
|
5
|
+
import path from "node:path";
|
|
6
|
+
|
|
7
|
+
export function readHandoffChunk(selectedRoot, options = {}) {
|
|
8
|
+
const offset = unsignedInteger(options.offset ?? "0", "offset");
|
|
9
|
+
const maxChars = unsignedInteger(options.maxChars ?? "4000", "max-chars");
|
|
10
|
+
if (maxChars < 64 || maxChars > 8192) throw new Error("max-chars must be between 64 and 8192");
|
|
11
|
+
const expected = options.sha256;
|
|
12
|
+
if (expected !== undefined && !/^[a-f0-9]{64}$/.test(expected)) throw new Error("sha256 must be a lowercase SHA-256 digest");
|
|
13
|
+
if (offset > 0 && expected === undefined) throw new Error("continuation requires --sha256 from the first chunk");
|
|
14
|
+
|
|
15
|
+
// Root aliases are supported (for example /tmp on macOS). Expose both paths
|
|
16
|
+
// so the caller can verify the canonical root against the intended workspace.
|
|
17
|
+
// Links below that root are rejected, not followed into another workspace.
|
|
18
|
+
const requestedRoot = path.resolve(selectedRoot);
|
|
19
|
+
const root = realpathSync(requestedRoot);
|
|
20
|
+
assertSafeRoot(root);
|
|
21
|
+
const target = path.join(root, "dev", "SESSION_HANDOFF.md");
|
|
22
|
+
const before = lstatSync(target, { bigint: true });
|
|
23
|
+
if (!before.isFile() || before.isSymbolicLink()) throw new Error("handoff must be a regular file, not a link");
|
|
24
|
+
const descriptor = openSync(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
|
|
25
|
+
let bytes;
|
|
26
|
+
try {
|
|
27
|
+
const opened = fstatSync(descriptor, { bigint: true });
|
|
28
|
+
if (!sameIdentity(before, opened)) throw new Error("handoff changed before reading; restart at offset 0");
|
|
29
|
+
bytes = readFileSync(descriptor);
|
|
30
|
+
const after = fstatSync(descriptor, { bigint: true });
|
|
31
|
+
assertSafeRoot(root);
|
|
32
|
+
const current = lstatSync(target, { bigint: true });
|
|
33
|
+
if (!sameIdentity(before, after) || !sameIdentity(before, current) || BigInt(bytes.length) !== after.size) {
|
|
34
|
+
throw new Error("handoff changed while reading; restart at offset 0");
|
|
35
|
+
}
|
|
36
|
+
} finally {
|
|
37
|
+
closeSync(descriptor);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
const sha256 = createHash("sha256").update(bytes).digest("hex");
|
|
41
|
+
if (expected !== undefined && expected !== sha256) throw new Error("handoff snapshot changed; discard mixed coverage and restart at offset 0");
|
|
42
|
+
let decoded;
|
|
43
|
+
try { decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
|
|
44
|
+
catch { throw new Error("handoff is not valid UTF-8; no content returned"); }
|
|
45
|
+
const characters = Array.from(decoded);
|
|
46
|
+
const total = characters.length;
|
|
47
|
+
if (offset > total || (offset === total && total > 0)) throw new Error("offset must identify content within the handoff");
|
|
48
|
+
const end = Math.min(total, offset + maxChars);
|
|
49
|
+
return Object.freeze({
|
|
50
|
+
requestedRoot, root, file: "dev/SESSION_HANDOFF.md", sha256, offset, end, total,
|
|
51
|
+
nextOffset: end < total ? end : null,
|
|
52
|
+
text: characters.slice(offset, end).join("")
|
|
53
|
+
});
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export function formatHandoffChunk(chunk) {
|
|
57
|
+
const metadata = JSON.stringify({ requestedRoot: chunk.requestedRoot, root: chunk.root, file: chunk.file, sha256: chunk.sha256, offset: chunk.offset, end: chunk.end, total: chunk.total, unit: "Unicode code points", nextOffset: chunk.nextOffset });
|
|
58
|
+
return `AHK_HANDOFF_BEGIN ${metadata}\n${chunk.text}\nAHK_HANDOFF_END ${chunk.sha256} ${chunk.offset}:${chunk.end}/${chunk.total}\n`;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function unsignedInteger(value, name) {
|
|
62
|
+
const text = String(value);
|
|
63
|
+
if (!/^(0|[1-9][0-9]*)$/.test(text) || !Number.isSafeInteger(Number(text))) throw new Error(`${name} must be a non-negative safe integer`);
|
|
64
|
+
return Number(text);
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function inspect(target) {
|
|
68
|
+
try { return lstatSync(target); }
|
|
69
|
+
catch (error) { if (error.code === "ENOENT") return null; throw error; }
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function assertSafeRoot(root) {
|
|
73
|
+
if (!lstatSync(root).isDirectory()) throw new Error("root must be an existing directory");
|
|
74
|
+
const dev = inspect(path.join(root, "dev"));
|
|
75
|
+
if (!dev?.isDirectory() || dev.isSymbolicLink()) throw new Error("dev must be an existing directory inside root, not a link");
|
|
76
|
+
const migrations = inspect(path.join(root, "dev", "governance_migrations"));
|
|
77
|
+
if (migrations && (!migrations.isDirectory() || migrations.isSymbolicLink())) throw new Error("governance_migrations must not be a link or non-directory");
|
|
78
|
+
if (inspect(path.join(root, "dev", "governance_migrations", ".upgrade.lock"))) {
|
|
79
|
+
throw new Error("upgrade lock exists; do not read handoff; resume the authorized upgrade recovery first");
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
function sameIdentity(left, right) {
|
|
84
|
+
// Windows path metadata may report dev=0 while the open handle reports its
|
|
85
|
+
// volume ID. Compare a device ID only when both probes expose one.
|
|
86
|
+
const sameDevice = left.dev === 0n || right.dev === 0n || left.dev === right.dev;
|
|
87
|
+
return sameDevice && right.isFile() && !right.isSymbolicLink() && ["ino", "size", "mtimeNs", "ctimeNs"].every(key => left[key] === right[key]);
|
|
88
|
+
}
|
|
@@ -2,73 +2,89 @@
|
|
|
2
2
|
// installs and upgrades. Fresh-only files are declared separately so their
|
|
3
3
|
// path cannot silently become current lifecycle authority before that route is
|
|
4
4
|
// explicitly present.
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
contract("
|
|
26
|
-
contract("
|
|
27
|
-
contract("
|
|
28
|
-
contract("
|
|
29
|
-
contract("
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
)
|
|
35
|
-
|
|
5
|
+
|
|
6
|
+
import { commandFiles } from './commands.mjs';
|
|
7
|
+
|
|
8
|
+
// Source-to-delivery routing. Unknown new shipped modules must receive an owner.
|
|
9
|
+
// QA stages/evidence are defined by the existing assurance gate, not runtime doctor.
|
|
10
|
+
export const deliveredFeatureContracts = Object.freeze([
|
|
11
|
+
{id:'installer',sources:['package.json','bin/agent-handoff-kit.mjs','bin/installed-file-contract.mjs','bin/official-origin-catalog.mjs','bin/migration-baselines/','bin/upgrade-inventory.mjs','bin/user-rules-router.mjs']},
|
|
12
|
+
{id:'shortcuts',sources:['bin/commands.mjs'],hosts:['claude','gemini','codex','antigravity'],nativeAcceptanceHosts:['codex'],nativeInvocationEntries:['handoff-kit-progress']},
|
|
13
|
+
{id:'dashboard',sources:['bin/progress/']},
|
|
14
|
+
{id:'continuity',sources:['runtime-core/','bin/handoff-read.mjs','bin/prompt-mirror-core.mjs']},
|
|
15
|
+
{id:'task-packs',sources:['packs/']}
|
|
16
|
+
].map(x=>Object.freeze(x)));
|
|
17
|
+
|
|
18
|
+
export const INSTALLED_FILE_CONTRACT_SCHEMA = 1;
|
|
19
|
+
// Generated project entries share one content owner. Only these exact paths
|
|
20
|
+
// enter installer recovery; platform directories are never blanket-owned.
|
|
21
|
+
export const SHORTCUT_INSTALL_CONTRACT = 1;
|
|
22
|
+
export const requiredShortcutTargets = Object.freeze(commandFiles().map(({file})=>file));
|
|
23
|
+
|
|
24
|
+
export const installedFileContracts = Object.freeze([
|
|
25
|
+
contract("runtime-core/AGENTS.core.md", "AGENTS.md", "managed-core"),
|
|
26
|
+
contract("runtime-core/CLAUDE.md", "CLAUDE.md", "strict-bridge"),
|
|
27
|
+
contract("runtime-core/GEMINI.md", "GEMINI.md", "strict-bridge"),
|
|
28
|
+
contract("runtime-core/START_NEXT_SESSION_PROMPT.txt", "START_NEXT_SESSION_PROMPT.txt", "generated-state"),
|
|
29
|
+
contract("runtime-core/SESSION_HANDOFF.md", "dev/SESSION_HANDOFF.md", "stateful-handoff"),
|
|
30
|
+
contract("runtime-core/SESSION_LOG.md", "dev/SESSION_LOG.md", "stateful-log"),
|
|
31
|
+
contract("runtime-core/PROJECT_INDEX.md", "dev/PROJECT_INDEX.md", "stateful-index"),
|
|
32
|
+
contract("runtime-core/DOC_SYNC_REGISTRY.md", "dev/DOC_SYNC_REGISTRY.md", "stateful-registry"),
|
|
33
|
+
contract("runtime-core/RULE_PACKS.md", "dev/RULE_PACKS.md", "marked-routing-table"),
|
|
34
|
+
contract("runtime-core/PROJECT_DECISIONS.md", "dev/PROJECT_DECISIONS.md", "stateful-decisions"),
|
|
35
|
+
contract("packs/safety.md", "dev/rules/safety.md", "rule-pack"),
|
|
36
|
+
contract("packs/coding.md", "dev/rules/coding.md", "rule-pack"),
|
|
37
|
+
contract("packs/writing.md", "dev/rules/writing.md", "rule-pack"),
|
|
38
|
+
contract("packs/research.md", "dev/rules/research.md", "rule-pack"),
|
|
39
|
+
contract("packs/agent-governance.md", "dev/rules/agent-governance.md", "rule-pack"),
|
|
40
|
+
contract("packs/release.md", "dev/rules/release.md", "rule-pack"),
|
|
41
|
+
contract("packs/knowledge.md", "dev/rules/knowledge.md", "rule-pack"),
|
|
42
|
+
contract("packs/communication.md", "dev/rules/communication.md", "rule-pack"),
|
|
43
|
+
contract("packs/closeout.md", "dev/rules/closeout.md", "rule-pack"),
|
|
44
|
+
contract("packs/onboarding.md", "dev/rules/onboarding.md", "rule-pack"),
|
|
45
|
+
contract("packs/integrations.md", "dev/rules/integrations.md", "rule-pack")
|
|
46
|
+
]);
|
|
47
|
+
|
|
48
|
+
export const installedMappings = Object.freeze(
|
|
49
|
+
installedFileContracts.map(({ sourceRel, targetRel }) => Object.freeze([sourceRel, targetRel]))
|
|
50
|
+
);
|
|
51
|
+
|
|
36
52
|
// The router is installed on fresh roots, but is not evidence that an arbitrary
|
|
37
53
|
// mixed file is Kit-managed. Its upgrade treatment lives in a separate current
|
|
38
54
|
// transition contract below rather than broad path ownership.
|
|
39
|
-
export const freshInstallFileContracts = Object.freeze([
|
|
40
|
-
...installedFileContracts,
|
|
41
|
-
contract("runtime-core/USER_RULES.md", "dev/USER_RULES.md", "fresh-user-router")
|
|
42
|
-
]);
|
|
43
|
-
|
|
44
|
-
export const freshInstallMappings = Object.freeze(
|
|
45
|
-
freshInstallFileContracts.map(({ sourceRel, targetRel }) => Object.freeze([sourceRel, targetRel]))
|
|
46
|
-
);
|
|
47
|
-
|
|
55
|
+
export const freshInstallFileContracts = Object.freeze([
|
|
56
|
+
...installedFileContracts,
|
|
57
|
+
contract("runtime-core/USER_RULES.md", "dev/USER_RULES.md", "fresh-user-router")
|
|
58
|
+
]);
|
|
59
|
+
|
|
60
|
+
export const freshInstallMappings = Object.freeze(
|
|
61
|
+
freshInstallFileContracts.map(({ sourceRel, targetRel }) => Object.freeze([sourceRel, targetRel]))
|
|
62
|
+
);
|
|
63
|
+
|
|
48
64
|
// Formal user-rule state is part of an upgrade only when the existing AGENTS.md
|
|
49
65
|
// entry and router form one verifiable current formal state. This separate
|
|
50
66
|
// contract deliberately does not reclassify a path, title, or directory as Kit
|
|
51
67
|
// authority.
|
|
52
|
-
export const upgradeStateFileContracts = Object.freeze([
|
|
53
|
-
contract("runtime-core/USER_RULES.md", "dev/USER_RULES.md", "accepted-user-rules-router")
|
|
54
|
-
]);
|
|
55
|
-
|
|
56
|
-
export const upgradeStateMappings = Object.freeze(
|
|
57
|
-
upgradeStateFileContracts.map(({ sourceRel, targetRel }) => Object.freeze([sourceRel, targetRel]))
|
|
58
|
-
);
|
|
59
|
-
|
|
60
|
-
export const upgradeStateTargets = Object.freeze(
|
|
61
|
-
upgradeStateFileContracts.map(({ targetRel }) => targetRel)
|
|
62
|
-
);
|
|
63
|
-
|
|
64
|
-
export const requiredInstalledTargets = Object.freeze(
|
|
65
|
-
installedFileContracts.map(({ targetRel }) => targetRel)
|
|
66
|
-
);
|
|
67
|
-
|
|
68
|
-
export function installedFileContract(targetRel) {
|
|
69
|
-
return installedFileContracts.find((item) => item.targetRel === targetRel) ?? null;
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
function contract(sourceRel, targetRel, strategy) {
|
|
73
|
-
return Object.freeze({ sourceRel, targetRel, strategy });
|
|
74
|
-
}
|
|
68
|
+
export const upgradeStateFileContracts = Object.freeze([
|
|
69
|
+
contract("runtime-core/USER_RULES.md", "dev/USER_RULES.md", "accepted-user-rules-router")
|
|
70
|
+
]);
|
|
71
|
+
|
|
72
|
+
export const upgradeStateMappings = Object.freeze(
|
|
73
|
+
upgradeStateFileContracts.map(({ sourceRel, targetRel }) => Object.freeze([sourceRel, targetRel]))
|
|
74
|
+
);
|
|
75
|
+
|
|
76
|
+
export const upgradeStateTargets = Object.freeze(
|
|
77
|
+
upgradeStateFileContracts.map(({ targetRel }) => targetRel)
|
|
78
|
+
);
|
|
79
|
+
|
|
80
|
+
export const requiredInstalledTargets = Object.freeze(
|
|
81
|
+
installedFileContracts.map(({ targetRel }) => targetRel)
|
|
82
|
+
);
|
|
83
|
+
|
|
84
|
+
export function installedFileContract(targetRel) {
|
|
85
|
+
return installedFileContracts.find((item) => item.targetRel === targetRel) ?? null;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function contract(sourceRel, targetRel, strategy) {
|
|
89
|
+
return Object.freeze({ sourceRel, targetRel, strategy });
|
|
90
|
+
}
|