@calliopelabs/cli 3.1.0 → 3.2.1

package/dist/spawning/validation.js

@@ -0,0 +1,95 @@
+import { smartPolicyWithin } from '../routing/smart.js';
+import { canonicalJson, digest } from '../approvals/index.js';
+import { analyzePlan, array, shape, id, hex, uuid, integer, pathName, fail } from '../orchestration/validation.js';
+import { validateChildGrant } from '../execution/child-grants.js';
+export const MAX_SPAWN_BYTES = 65536, MAX_SPAWN_PROPOSALS = 256;
+export function validateSpawnInput(value) {
+    shape(value, ['version', 'parentId', 'agents', 'tasks']);
+    if (value.version !== 1)
+        fail('Unsupported child proposal version.');
+    id(value.parentId);
+    array(value.agents, 16, 1);
+    array(value.tasks, 64, 1);
+    if (Buffer.byteLength(canonicalJson(value)) > MAX_SPAWN_BYTES)
+        fail('Child proposal exceeds 64 KiB.');
+    return value;
+}
+/** Existing agents, tasks, scopes and limits remain byte-for-byte unchanged. */
+export function extendPlan(base, input) {
+    validateSpawnInput(input);
+    if (!base.agents.some(a => a.id === input.parentId))
+        fail('Child proposal names an unknown parent.');
+    const addedAgents = new Set(input.agents.map(agent => agent?.id));
+    if (input.tasks.some(task => !task || !addedAgents.has(task.agentId)))
+        fail('New tasks must belong to the proposed child hierarchy.');
+    const next = analyzePlan({ ...base, agents: [...base.agents, ...input.agents], tasks: [...base.tasks, ...input.tasks] }).plan;
+    for (const child of input.agents) {
+        const parent = next.agents.find(a => a.id === child.parentId), allowed = parent?.childRouting ?? parent?.routing;
+        if (allowed && (!child.routing || !smartPolicyWithin(child.routing, allowed) || child.childRouting && !smartPolicyWithin(child.childRouting, allowed) || !allowed.pool.some(target => (child.preference.provider === 'auto' || target.provider === child.preference.provider) && (!child.preference.model || !target.model || target.model === child.preference.model))))
+            fail('Child routing exceeds its parent approved delegation pool; inherit or narrow the policy.');
+    }
+    for (const child of input.agents) {
+        let current = next.agents.find(a => a.id === child.id), found = false;
+        for (let n = 0; current?.parentId && n < next.agents.length; n++) {
+            if (current.parentId === input.parentId) {
+                found = true;
+                break;
+            }
+            current = next.agents.find(a => a.id === current.parentId);
+        }
+        if (!found)
+            fail('Every proposed agent must descend from the named parent.');
+    }
+    return next;
+}
+export function proposalId(hash) {
+    if (!hex(hash))
+        fail('Invalid proposal hash.');
+    const raw = hash.slice(0, 12) + '4' + hash.slice(13, 16) + (8 + (parseInt(hash[16], 16) % 4)).toString(16) + hash.slice(17, 32);
+    return `${raw.slice(0, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}-${raw.slice(16, 20)}-${raw.slice(20)}`;
+}
+export function proposalGrant(proposal, header) {
+    return validateChildGrant({ version: 1, id: proposalId(proposal.hash), proposalHash: proposal.hash, previousGraphHash: proposal.graphHash, planHash: proposal.planHash, runManifestHash: proposal.runManifestHash, approvalRevision: proposal.approvalRevision, parentId: proposal.parentId,
+        accounts: proposal.agents.map(agent => ({ id: agent.id, parentId: agent.parentId, tokenBudget: agent.tokenBudget, costBudgetNanos: Math.floor(agent.costBudgetUsd * 1e9), deadline: Date.parse(header.createdAt) + agent.timeBudgetMs, allowedTools: agent.allowedTools, allowedPaths: agent.allowedPaths })) });
+}
+export function validateSpawnProposal(value, manifest, header, base) {
+    shape(value, ['version', 'parentId', 'agents', 'tasks', 'runId', 'runManifestHash', 'approvalRevision', 'graphHash', 'planHash', 'source', 'hash']);
+    if (value.runId !== manifest.id || value.runManifestHash !== manifest.hash || value.approvalRevision !== header.approvalRevision || !hex(value.graphHash) || !hex(value.planHash) || !hex(value.hash))
+        fail('Child proposal belongs to another run, approval or graph.');
+    shape(value.source, ['path', 'sha256'], ['kind', 'eventId']);
+    pathName(value.source.path);
+    if (value.source.kind !== undefined || value.source.eventId !== undefined) {
+        if (value.source.kind !== 'supervision' || !uuid(value.source.eventId) || value.source.path !== `supervision/${value.source.eventId}.json`)
+            fail('Invalid controller proposal source.');
+    }
+    if (!hex(value.source.sha256))
+        fail('Child proposal source needs its byte hash.');
+    const { hash, ...body } = value;
+    if (hash !== digest(canonicalJson(body)))
+        fail('Child proposal hash is invalid.');
+    const proposal = value, input = { version: proposal.version, parentId: proposal.parentId, agents: proposal.agents, tasks: proposal.tasks }, next = extendPlan(base, input);
+    if (analyzePlan(base).hash !== proposal.graphHash || analyzePlan(next).hash !== proposal.planHash)
+        fail('Child proposal graph revision changed.');
+    if (Buffer.byteLength(canonicalJson(value)) > MAX_SPAWN_BYTES)
+        fail('Child proposal exceeds 64 KiB.');
+    proposalGrant(proposal, header);
+    return proposal;
+}
+export function makeSpawnProposal(manifest, header, base, input, source) {
+    const next = extendPlan(base, input), body = { ...structuredClone(input), runId: manifest.id, runManifestHash: manifest.hash, approvalRevision: header.approvalRevision, graphHash: analyzePlan(base).hash, planHash: analyzePlan(next).hash, source };
+    return validateSpawnProposal({ ...body, hash: digest(canonicalJson(body)) }, manifest, header, base);
+}
+export function validateSpawnAdmission(value, manifest, header, base) {
+    shape(value, ['version', 'proposal', 'grant']);
+    if (value.version !== 1)
+        fail('Unsupported spawn admission.');
+    const proposal = validateSpawnProposal(value.proposal, manifest, header, base);
+    shape(value.grant, ['grant', 'eventId', 'eventHash', 'at']);
+    if (!uuid(value.grant.eventId) || !hex(value.grant.eventHash))
+        fail('Spawn admission requires its budget event.');
+    integer(value.grant.at, Date.parse(header.createdAt), header.deadline);
+    if (canonicalJson(validateChildGrant(value.grant.grant)) !== canonicalJson(proposalGrant(proposal, header)))
+        fail('Child authority differs from the approved graph.');
+    return value;
+}
+//# sourceMappingURL=validation.js.map

package/dist/spawning/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/spawning/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAC,aAAa,EAAC,MAAM,EAAC,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAC,WAAW,EAAC,KAAK,EAAC,KAAK,EAAC,EAAE,EAAC,GAAG,EAAC,IAAI,EAAC,OAAO,EAAC,QAAQ,EAAC,IAAI,EAAC,MAAM,gCAAgC,CAAC;AAGzG,OAAO,EAAC,kBAAkB,EAAC,MAAM,8BAA8B,CAAC;AAIhE,MAAM,CAAC,MAAM,eAAe,GAAC,KAAK,EAAC,mBAAmB,GAAC,GAAG,CAAC;AAC3D,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,KAAK,CAAC,KAAK,EAAC,CAAC,SAAS,EAAC,UAAU,EAAC,QAAQ,EAAC,OAAO,CAAC,CAAC,CAAC;IAAA,IAAG,KAAK,CAAC,OAAO,KAAG,CAAC;QAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;IAAA,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAAA,KAAK,CAAC,KAAK,CAAC,MAAM,EAAC,EAAE,EAAC,CAAC,CAAC,CAAC;IAAA,KAAK,CAAC,KAAK,CAAC,KAAK,EAAC,EAAE,EAAC,CAAC,CAAC,CAAC;IAC1L,IAAG,MAAM,CAAC,UAAU,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,GAAC,eAAe;QAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IAAA,OAAO,KAA8B,CAAC;AAC1I,CAAC;AACD,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,IAAgB,EAAC,KAAgB;IAC1D,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAAA,IAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA,EAAE,CAAA,CAAC,CAAC,EAAE,KAAG,KAAK,CAAC,QAAQ,CAAC;QAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;IACzH,MAAM,WAAW,GAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAA,EAAE,CAAA,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IAC9D,IAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAA,EAAE,CAAA,CAAC,IAAI,IAAE,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IAChI,MAAM,IAAI,GAAC,WAAW,CAAC,EAAC,GAAG,IAAI,EAAC,MAAM,EAAC,CAAC,GAAG,IAAI,CAAC,MAAM,EAAC,GAAG,KAAK,CAAC,MAAM,CAAC,EAAC,KAAK,EAAC,CAAC,GAAG,IAAI,CAAC,KAAK,EAAC,GAAG,KAAK,CAAC,KAAK,CAAC,EAAC,CAAC,CAAC,IAAI,CAAC;IACpH,KAAI,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAC,CAAC;QAC/B,MAAM,MAAM,GAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA,EAAE,CAAA,CAAC,CAAC,EAAE,KAAG,KAAK,CAAC,QAAQ,CAAC,EAAC,OAAO,GAAC,MAAM,EAAE,YAAY,IAAE,MAAM,EAAE,OAAO,CAAC;QACtG,IAAG,OAAO,IAAE,CAAC,CAAC,KAAK,CAAC,OAAO,IAAE,CAAC,iBAAiB,CAAC,KAAK,CAAC,OAAO,EAAC,OAAO,CAAC,IAAE,KAAK,CAAC,YAAY,IAAE,CAAC,iBAAiB,CAAC,KAAK,CAAC,YAAY,EAAC,OAAO,CAAC,IAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAA,EAAE,CAAA,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,KAAG,MAAM,IAAE,MAAM,CAAC,QAAQ,KAAG,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,IAAE,CAAC,MAAM,CAAC,KAAK,IAAE,MAAM,CAAC,KAAK,KAAG,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;YAAC,IAAI,CAAC,0FAA0F,CAAC,CAAC;IAC/a,CAAC;IACD,KAAI,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAC,CAAC;QAAA,IAAI,OAAO,GAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA,EAAE,CAAA,CAAC,CAAC,EAAE,KAAG,KAAK,CAAC,EAAE,CAAC,EAAC,KAAK,GAAC,KAAK,CAAC;QAAA,KAAI,IAAI,CAAC,GAAC,CAAC,EAAC,OAAO,EAAE,QAAQ,IAAE,CAAC,GAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAC,CAAC,EAAE,EAAC,CAAC;YAAA,IAAG,OAAO,CAAC,QAAQ,KAAG,KAAK,CAAC,QAAQ,EAAC,CAAC;gBAAA,KAAK,GAAC,IAAI,CAAC;gBAAA,MAAM;YAAA,CAAC;YAAA,OAAO,GAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA,EAAE,CAAA,CAAC,CAAC,EAAE,KAAG,OAAQ,CAAC,QAAQ,CAAC,CAAC;QAAA,CAAC;QAAA,IAAG,CAAC,KAAK;YAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;IAAA,CAAC;IAClV,OAAO,IAAI,CAAC;AACd,CAAC;AACD,MAAM,UAAU,UAAU,CAAC,IAAW;IACpC,IAAG,CAAC,GAAG,CAAC,IAAI,CAAC;QAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;IAAA,MAAM,GAAG,GAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAC,EAAE,CAAC,GAAC,GAAG,GAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAC,EAAE,CAAC,GAAC,CAAC,CAAC,GAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAE,EAAC,EAAE,CAAC,GAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAC,EAAE,CAAC,CAAC;IAAA,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAC,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,EAAC,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,EAAC,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,EAAC,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;AACrQ,CAAC;AACD,MAAM,UAAU,aAAa,CAAC,QAAsB,EAAC,MAAsB;IACzE,OAAO,kBAAkB,CAAC,EAAC,OAAO,EAAC,CAAC,EAAC,EAAE,EAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAC,YAAY,EAAC,QAAQ,CAAC,IAAI,EAAC,iBAAiB,EAAC,QAAQ,CAAC,SAAS,EAAC,QAAQ,EAAC,QAAQ,CAAC,QAAQ,EAAC,eAAe,EAAC,QAAQ,CAAC,eAAe,EAAC,gBAAgB,EAAC,QAAQ,CAAC,gBAAgB,EAAC,QAAQ,EAAC,QAAQ,CAAC,QAAQ;QACzQ,QAAQ,EAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAA,EAAE,CAAA,CAAC,EAAC,EAAE,EAAC,KAAK,CAAC,EAAE,EAAC,QAAQ,EAAC,KAAK,CAAC,QAAQ,EAAC,WAAW,EAAC,KAAK,CAAC,WAAW,EAAC,eAAe,EAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,aAAa,GAAC,GAAG,CAAC,EAAC,QAAQ,EAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,GAAC,KAAK,CAAC,YAAY,EAAC,YAAY,EAAC,KAAK,CAAC,YAAY,EAAC,YAAY,EAAC,KAAK,CAAC,YAAY,EAAC,CAAC,CAAC,EAAC,CAAC,CAAC;AAC9R,CAAC;AACD,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAC,QAAoB,EAAC,MAAsB,EAAC,IAAgB;IAC9G,KAAK,CAAC,KAAK,EAAC,CAAC,SAAS,EAAC,UAAU,EAAC,QAAQ,EAAC,OAAO,EAAC,OAAO,EAAC,iBAAiB,EAAC,kBAAkB,EAAC,WAAW,EAAC,UAAU,EAAC,QAAQ,EAAC,MAAM,CAAC,CAAC,CAAC;IACzI,IAAG,KAAK,CAAC,KAAK,KAAG,QAAQ,CAAC,EAAE,IAAE,KAAK,CAAC,eAAe,KAAG,QAAQ,CAAC,IAAI,IAAE,KAAK,CAAC,gBAAgB,KAAG,MAAM,CAAC,gBAAgB,IAAE,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAE,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;QAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;IACvP,KAAK,CAAC,KAAK,CAAC,MAAM,EAAC,CAAC,MAAM,EAAC,QAAQ,CAAC,EAAC,CAAC,MAAM,EAAC,SAAS,CAAC,CAAC,CAAC;IAAA,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACrF,IAAG,KAAK,CAAC,MAAM,CAAC,IAAI,KAAG,SAAS,IAAE,KAAK,CAAC,MAAM,CAAC,OAAO,KAAG,SAAS,EAAC,CAAC;QAAA,IAAG,KAAK,CAAC,MAAM,CAAC,IAAI,KAAG,aAAa,IAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,IAAE,KAAK,CAAC,MAAM,CAAC,IAAI,KAAG,eAAe,KAAK,CAAC,MAAM,CAAC,OAAO,OAAO;YAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;IAAA,CAAC;IAAA,IAAG,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;QAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;IACnU,MAAM,EAAC,IAAI,EAAC,GAAG,IAAI,EAAC,GAAC,KAAK,CAAC;IAAA,IAAG,IAAI,KAAG,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;IACzG,MAAM,QAAQ,GAAC,KAAiC,EAAC,KAAK,GAAC,EAAC,OAAO,EAAC,QAAQ,CAAC,OAAO,EAAC,QAAQ,EAAC,QAAQ,CAAC,QAAQ,EAAC,MAAM,EAAC,QAAQ,CAAC,MAAM,EAAC,KAAK,EAAC,QAAQ,CAAC,KAAK,EAAC,EAAC,IAAI,GAAC,UAAU,CAAC,IAAI,EAAC,KAAK,CAAC,CAAC;IACrL,IAAG,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,KAAG,QAAQ,CAAC,SAAS,IAAE,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,KAAG,QAAQ,CAAC,QAAQ;QAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IAC1I,IAAG,MAAM,CAAC,UAAU,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,GAAC,eAAe;QAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IAAA,aAAa,CAAC,QAAQ,EAAC,MAAM,CAAC,CAAC;IAAA,OAAO,QAAQ,CAAC;AACnJ,CAAC;AACD,MAAM,UAAU,iBAAiB,CAAC,QAAoB,EAAC,MAAsB,EAAC,IAAgB,EAAC,KAAgB,EAAC,MAA8B;IAC5I,MAAM,IAAI,GAAC,UAAU,CAAC,IAAI,EAAC,KAAK,CAAC,EAAC,IAAI,GAAC,EAAC,GAAG,eAAe,CAAC,KAAK,CAAC,EAAC,KAAK,EAAC,QAAQ,CAAC,EAAE,EAAC,eAAe,EAAC,QAAQ,CAAC,IAAI,EAAC,gBAAgB,EAAC,MAAM,CAAC,gBAAgB,EAAC,SAAS,EAAC,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,EAAC,QAAQ,EAAC,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,EAAC,MAAM,EAAC,CAAC;IACpO,OAAO,qBAAqB,CAAC,EAAC,GAAG,IAAI,EAAC,IAAI,EAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,EAAC,EAAC,QAAQ,EAAC,MAAM,EAAC,IAAI,CAAC,CAAC;AAChG,CAAC;AACD,MAAM,UAAU,sBAAsB,CAAC,KAAa,EAAC,QAAoB,EAAC,MAAsB,EAAC,IAAgB;IAC/G,KAAK,CAAC,KAAK,EAAC,CAAC,SAAS,EAAC,UAAU,EAAC,OAAO,CAAC,CAAC,CAAC;IAAA,IAAG,KAAK,CAAC,OAAO,KAAG,CAAC;QAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAAA,MAAM,QAAQ,GAAC,qBAAqB,CAAC,KAAK,CAAC,QAAQ,EAAC,QAAQ,EAAC,MAAM,EAAC,IAAI,CAAC,CAAC;IAChL,KAAK,CAAC,KAAK,CAAC,KAAK,EAAC,CAAC,OAAO,EAAC,SAAS,EAAC,WAAW,EAAC,IAAI,CAAC,CAAC,CAAC;IAAA,IAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,IAAE,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC;QAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;IAAA,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,EAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,EAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3O,IAAG,aAAa,CAAC,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAG,aAAa,CAAC,aAAa,CAAC,QAAQ,EAAC,MAAM,CAAC,CAAC;QAAC,IAAI,CAAC,kDAAkD,CAAC,CAAC;IAAA,OAAO,KAAkC,CAAC;AAC7M,CAAC"}

package/dist/storage.d.ts

@@ -3,6 +3,8 @@
  *
  * Manages ~/.calliope-cli/ directory structure for sessions, todos, and history.
  */
+import { type ConversationState, type ConversationSnapshot, type RecoveryStatus } from './sessions/index.js';
+import type { Message } from './types.js';
 import { IterationLedger } from './iteration-ledger.js';
 import type { IterationLedgerSnapshot } from './iteration-ledger.js';
 export declare function createSessionId(): string;
@@ -15,6 +17,16 @@ export interface Session {
     messageCount: number;
     provider: string;
     model: string;
+    lineage?: {
+        version: 1;
+        toolStateHash: string;
+        kind: 'manual' | 'safety' | 'import';
+        name?: string;
+        sessionId: string;
+        revision: string;
+        stateHash: string;
+        at: string;
+    };
 }
 export interface ChatMessage {
     id: string;
@@ -67,6 +79,21 @@ export declare function initStorage(): void;
  * Create or resume a session for the current project
  */
 export declare function getOrCreateSession(projectPath: string): Session;
+/** A new terminal owns a unique session, including on the same day/project. */
+export declare function createSession(projectPath: string, options?: {
+    activate?: boolean;
+    prefix?: 'session' | 'acp';
+    lineage?: Session['lineage'];
+}): Session;
+/** Strict recovery APIs pin the ID; they never fall back to the shared pointer. */
+export declare function readSessionConversation(sessionId: string): ConversationState;
+export declare function saveSessionConversation(sessionId: string, messages: Message[], options: {
+    expectedRevision: string | null;
+    status: RecoveryStatus;
+    signal?: AbortSignal;
+}): ConversationSnapshot;
+/** Listing metadata may lag a committed snapshot after a crash; it is never authoritative. */
+export declare function updateSessionSummary(sessionId: string, snapshot: ConversationSnapshot): void;
 /**
  * Get current session info
  */
@@ -82,7 +109,7 @@ export declare function deleteSession(sessionId: string): boolean;
 /**
  * Add a message to the current session's chat history
  */
-export declare function addChatMessage(message: Omit<ChatMessage, 'id' | 'timestamp'>): void;
+export declare function addChatMessage(message: Omit<ChatMessage, 'id' | 'timestamp'>, sessionId?: string): void;
 /**
  * Get chat history for current session
  */
@@ -95,6 +122,7 @@ export declare function getSessionDirById(sessionId: string): string | null;
  * Switch the active session pointer to a saved session by ID.
  */
 export declare function setCurrentSessionById(sessionId: string): Session | null;
+/** Legacy convenience API; new clients use explicit IDs and revisions above. */
 export declare function saveMessageHistory(messages: unknown[]): void;
 /**
  * Load saved LLM messages from a session.

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/storage.js

@@ -6,6 +6,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { randomUUID } from 'node:crypto';
+import { activeSessionId, readPrivateSessionFile, readConversation, writeConversation, SessionRecoveryError } from './sessions/index.js';
 import { IterationLedger } from './iteration-ledger.js';
 // ============================================================================
 // Date Utilities
@@ -20,7 +22,7 @@ function getTodayString(date = new Date()) {
     return `${year}-${month}-${day}`;
 }
 export function createSessionId() {
-    return `session_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    return `session_${Date.now()}_${randomUUID()}`;
 }
 // ============================================================================
 // Paths
@@ -40,8 +42,17 @@ export const paths = {
     history: path.join(CALLIOPE_DIR, 'history'),
     commandHistory: path.join(CALLIOPE_DIR, 'history', 'commands.txt'),
 };
+function activeSessionDir() {
+    const id = activeSessionId();
+    if (!id)
+        return paths.currentSession;
+    const dir = getSessionDirById(id);
+    if (!dir)
+        throw new SessionRecoveryError('invalid', 'this run has no saved session for session-scoped tools.');
+    return dir;
+}
 function getSessionFilePath(fileName, sessionId) {
-    const sessionDir = sessionId ? getSessionDirById(sessionId) : paths.currentSession;
+    const sessionDir = sessionId ? getSessionDirById(sessionId) : activeSessionDir();
     return sessionDir ? path.join(sessionDir, fileName) : null;
 }
 // ============================================================================
@@ -63,7 +74,7 @@ export function initStorage() {
     ];
     for (const dir of dirs) {
         if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
         }
     }
     // Initialize global todos if not exists (line-based format)
@@ -100,9 +111,9 @@ function writeJSON(filePath, data) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    const tmp = `${filePath}.${randomUUID()}.tmp`;
     try {
-        fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+        fs.writeFileSync(tmp, JSON.stringify(data, null, 2), { flag: 'wx', mode: 0o600 });
         fs.renameSync(tmp, filePath);
     }
     catch (err) {
@@ -328,6 +339,53 @@ export function getOrCreateSession(projectPath) {
     updateCurrentSymlink(sessionDir);
     return session;
 }
+/** A new terminal owns a unique session, including on the same day/project. */
+export function createSession(projectPath, options = {}) {
+    initStorage();
+    const now = new Date().toISOString();
+    const session = { id: createSessionId().replace(/^session_/, `${options.prefix ?? 'session'}_`), projectPath: path.resolve(projectPath),
+        projectName: path.basename(projectPath) || 'unnamed', createdAt: now, lastAccessedAt: now,
+        messageCount: 0, provider: '', model: '', ...(options.lineage ? { lineage: options.lineage } : {}) };
+    const dir = path.join(paths.sessions, `${getTodayString()}_${session.projectName}_${randomUUID()}`);
+    fs.mkdirSync(dir, { mode: 0o700 });
+    fs.mkdirSync(path.join(dir, 'plans'), { mode: 0o700 });
+    writeJSON(path.join(dir, 'session.json'), session);
+    fs.writeFileSync(path.join(dir, 'chat.log'), '', { mode: 0o600 });
+    fs.writeFileSync(path.join(dir, 'todos.txt'), '', { mode: 0o600 });
+    if (options.activate !== false)
+        updateCurrentSymlink(dir);
+    return session;
+}
+/** Strict recovery APIs pin the ID; they never fall back to the shared pointer. */
+export function readSessionConversation(sessionId) {
+    const dir = getSessionDirById(sessionId);
+    if (!dir)
+        throw new SessionRecoveryError('invalid', 'session not found; use /sessions to select an existing session.');
+    return readConversation(dir, sessionId);
+}
+export function saveSessionConversation(sessionId, messages, options) {
+    const dir = getSessionDirById(sessionId);
+    if (!dir)
+        throw new SessionRecoveryError('invalid', 'session not found; start /new before continuing.');
+    const snapshot = writeConversation(dir, sessionId, messages, { ...options, cap: Math.min(getMaxPersistedMessages(), 10000) });
+    updateSessionSummary(sessionId, snapshot);
+    return snapshot;
+}
+/** Listing metadata may lag a committed snapshot after a crash; it is never authoritative. */
+export function updateSessionSummary(sessionId, snapshot) {
+    const dir = getSessionDirById(sessionId);
+    if (!dir || snapshot.sessionId !== sessionId)
+        return;
+    const session = readSessionFromDir(dir);
+    if (session) {
+        session.messageCount = snapshot.messages.length;
+        session.lastAccessedAt = snapshot.updatedAt;
+        try {
+            writeJSON(path.join(dir, 'session.json'), session);
+        }
+        catch { /* Snapshot is durable. */ }
+    }
+}
 /**
  * Update the 'current' symlink to point to active session
  */
@@ -344,7 +402,23 @@ function updateCurrentSymlink(sessionDir) {
 }
 function readSessionFromDir(sessionDir) {
     const sessionFile = path.join(sessionDir, 'session.json');
-    return readJSON(sessionFile, null);
+    let value;
+    try {
+        value = JSON.parse(readPrivateSessionFile(sessionFile, 65536) ?? 'null');
+    }
+    catch {
+        return null;
+    }
+    const lineage = value?.lineage;
+    if (lineage !== undefined && (!lineage || typeof lineage !== 'object' || Array.isArray(lineage) || lineage.version !== 1 ||
+        !['manual', 'safety', 'import'].includes(lineage.kind) || typeof lineage.sessionId !== 'string' ||
+        !/^[a-zA-Z0-9_-]{1,200}$/.test(lineage.sessionId) || typeof lineage.revision !== 'string' || !/^[a-f0-9-]{36}$/.test(lineage.revision) ||
+        typeof lineage.stateHash !== 'string' || !/^[a-f0-9]{64}$/.test(lineage.stateHash) || typeof lineage.toolStateHash !== 'string' || !/^[a-f0-9]{64}$/.test(lineage.toolStateHash) ||
+        !Number.isFinite(Date.parse(lineage.at)) || lineage.name !== undefined && (typeof lineage.name !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(lineage.name))))
+        return null;
+    return value && typeof value.id === 'string' && typeof value.projectPath === 'string' && !/[\x00-\x1f\x7f]/.test(value.projectPath) && path.isAbsolute(value.projectPath)
+        && typeof value.projectName === 'string' && Number.isFinite(Date.parse(value.createdAt))
+        && Number.isFinite(Date.parse(value.lastAccessedAt)) ? value : null;
 }
 function touchSession(sessionDir, session) {
     session.lastAccessedAt = new Date().toISOString();
@@ -355,6 +429,9 @@ function touchSession(sessionDir, session) {
  * Get current session info
  */
 export function getCurrentSession() {
+    const id = activeSessionId();
+    if (id)
+        return getSessionById(id);
     try {
         if (fs.existsSync(paths.currentSession)) {
             return readSessionFromDir(paths.currentSession);
@@ -376,7 +453,7 @@ export function listSessions(limit = 10) {
         for (const entry of entries) {
             if (entry.isDirectory() && entry.name !== 'current') {
                 const sessionFile = path.join(paths.sessions, entry.name, 'session.json');
-                const session = readJSON(sessionFile, null);
+                const session = readSessionFromDir(path.dirname(sessionFile));
                 if (session) {
                     sessions.push(session);
                 }
@@ -413,11 +490,14 @@ export function deleteSession(sessionId) {
 /**
  * Add a message to the current session's chat history
  */
-export function addChatMessage(message) {
-    const session = getCurrentSession();
+export function addChatMessage(message, sessionId) {
+    const session = sessionId ? getSessionById(sessionId) : getCurrentSession();
     if (!session)
         return;
-    const historyFile = path.join(paths.currentSession, 'chat.log');
+    const dir = getSessionDirById(session.id);
+    if (!dir)
+        return;
+    const historyFile = path.join(dir, 'chat.log');
     const newMessage = {
         id: `msg_${Date.now()}_${Math.random().toString(36).slice(2)}`,
         timestamp: new Date().toISOString(),
@@ -426,7 +506,7 @@ export function addChatMessage(message) {
     // Append to chat log (line-based format)
     appendChatMessage(historyFile, newMessage);
     // Update session message count
-    const sessionFile = path.join(paths.currentSession, 'session.json');
+    const sessionFile = path.join(dir, 'session.json');
     session.messageCount += 1;
     session.lastAccessedAt = new Date().toISOString();
     writeJSON(sessionFile, session);
@@ -435,7 +515,7 @@ export function addChatMessage(message) {
  * Get chat history for current session
  */
 export function getChatHistory(limit, sessionId) {
-    const sessionDir = sessionId ? getSessionDirById(sessionId) : paths.currentSession;
+    const sessionDir = sessionId ? getSessionDirById(sessionId) : activeSessionDir();
     if (!sessionDir)
         return [];
     const history = readChatHistory(path.join(sessionDir, 'chat.log'));
@@ -457,7 +537,7 @@ export function getSessionDirById(sessionId) {
         for (const entry of entries) {
             if (entry.isDirectory() && entry.name !== 'current') {
                 const sessionFile = path.join(paths.sessions, entry.name, 'session.json');
-                const session = readJSON(sessionFile, null);
+                const session = readSessionFromDir(path.dirname(sessionFile));
                 if (session && session.id === sessionId) {
                     return path.join(paths.sessions, entry.name);
                 }
@@ -504,24 +584,16 @@ function getMaxPersistedMessages() {
     }
     return DEFAULT_MAX_PERSISTED_MESSAGES;
 }
+/** Legacy convenience API; new clients use explicit IDs and revisions above. */
 export function saveMessageHistory(messages) {
     const session = getCurrentSession();
     if (!session)
         return;
     try {
-        const cap = getMaxPersistedMessages();
-        const toPersist = messages.length > cap ? messages.slice(-cap) : messages;
-        const messagesFile = path.join(paths.currentSession, 'messages.json');
-        writeJSON(messagesFile, toPersist);
-        // Update session metadata
-        const sessionFile = path.join(paths.currentSession, 'session.json');
-        session.messageCount = toPersist.length;
-        session.lastAccessedAt = new Date().toISOString();
-        writeJSON(sessionFile, session);
-    }
-    catch {
-        // Silently fail - don't break the agent loop
+        const previous = readSessionConversation(session.id);
+        saveSessionConversation(session.id, messages, { expectedRevision: previous.revision, status: 'completed' });
     }
+    catch { /* Kept for legacy callers. Interactive recovery uses the throwing API. */ }
 }
 /**
  * Load saved LLM messages from a session.
@@ -537,15 +609,15 @@ export function loadMessageHistory(sessionId) {
             messagesFile = path.join(sessionDir, 'messages.json');
         }
         else {
-            messagesFile = path.join(paths.currentSession, 'messages.json');
+            messagesFile = path.join(activeSessionDir(), 'messages.json');
         }
         if (!fs.existsSync(messagesFile))
             return null;
-        const content = fs.readFileSync(messagesFile, 'utf-8');
-        const messages = JSON.parse(content);
-        if (Array.isArray(messages)) {
-            return messages;
-        }
+        const dir = fs.realpathSync(path.dirname(messagesFile));
+        const session = readSessionFromDir(dir);
+        if (!session)
+            return null;
+        return readConversation(dir, session.id).messages;
     }
     catch {
         // Ignore parse errors
@@ -674,7 +746,7 @@ export function searchChatHistory(query) {
  * Get todos for current session
  */
 export function getSessionTodos() {
-    const todosFile = path.join(paths.currentSession, 'todos.txt');
+    const todosFile = path.join(activeSessionDir(), 'todos.txt');
     return readTodos(todosFile);
 }
 /**
@@ -703,7 +775,7 @@ export function addTodo(content, options = {}) {
         writeTodos(globalTodosFile, todos);
     }
     else {
-        const todosFile = path.join(paths.currentSession, 'todos.txt');
+        const todosFile = path.join(activeSessionDir(), 'todos.txt');
         const todos = readTodos(todosFile);
         todos.push(todo);
         writeTodos(todosFile, todos);
@@ -716,7 +788,7 @@ export function addTodo(content, options = {}) {
 export function updateTodo(id, updates, global = false) {
     const filePath = global
         ? paths.globalTodos.replace('.json', '.txt')
-        : path.join(paths.currentSession, 'todos.txt');
+        : path.join(activeSessionDir(), 'todos.txt');
     const todos = readTodos(filePath);
     const index = todos.findIndex(t => t.id === id);
     if (index === -1)
@@ -735,7 +807,7 @@ export function updateTodo(id, updates, global = false) {
 export function deleteTodo(id, global = false) {
     const filePath = global
         ? paths.globalTodos.replace('.json', '.txt')
-        : path.join(paths.currentSession, 'todos.txt');
+        : path.join(activeSessionDir(), 'todos.txt');
     const todos = readTodos(filePath);
     const index = todos.findIndex(t => t.id === id);
     if (index === -1)
@@ -751,7 +823,7 @@ export function deleteTodo(id, global = false) {
  * Get plans for current session
  */
 export function getPlans() {
-    const plansDir = path.join(paths.currentSession, 'plans');
+    const plansDir = path.join(activeSessionDir(), 'plans');
     if (!fs.existsSync(plansDir))
         return [];
     const plans = [];
@@ -769,7 +841,7 @@ export function getPlans() {
  * Save a plan
  */
 export function savePlan(plan) {
-    const plansDir = path.join(paths.currentSession, 'plans');
+    const plansDir = path.join(activeSessionDir(), 'plans');
     if (!fs.existsSync(plansDir)) {
         fs.mkdirSync(plansDir, { recursive: true });
     }
@@ -780,14 +852,14 @@ export function savePlan(plan) {
  * Get active plan
  */
 export function getActivePlan() {
-    const activeFile = path.join(paths.currentSession, 'plans', 'active.json');
+    const activeFile = path.join(activeSessionDir(), 'plans', 'active.json');
     return readJSON(activeFile, null);
 }
 /**
  * Set active plan
  */
 export function setActivePlan(plan) {
-    const activeFile = path.join(paths.currentSession, 'plans', 'active.json');
+    const activeFile = path.join(activeSessionDir(), 'plans', 'active.json');
     if (plan) {
         writeJSON(activeFile, plan);
     }
@@ -999,7 +1071,7 @@ export function deleteTemplate(name) {
  * Get active TODO file path
  */
 function getActiveTodoFilePath() {
-    return path.join(paths.currentSession, 'active-todo.json');
+    return path.join(activeSessionDir(), 'active-todo.json');
 }
 /**
  * Set the active TODO