@zq-silk/yui 0.6.16 → 0.7.0

package/dist/context/runContextPack.js

@@ -0,0 +1,322 @@
+import { RUN_BOOTSTRAP_MAX_DELTAS } from "./runContextContract.js";
+import { contextContentDigest, contextSnapshotRef, createContextSnapshot, validateContextSnapshot } from "./contextSnapshot.js";
+export const RUN_CONTEXT_PACK_SCHEMA_VERSION = 1;
+export const RUN_CONTEXT_PACK_MAX_REFS = 256;
+export const RUN_CONTEXT_PACK_MAX_BYTES = 8 * 1024 * 1024;
+export const RUN_CONTEXT_EXPAND_MAX_BYTES = 4 * 1024 * 1024;
+export function freezeRunContextSnapshot(store, run, now, frozenBy = "controller") {
+    const scope = run.reviewRoundId !== undefined
+        ? "stage"
+        : run.workItemId !== undefined
+            ? "workitem"
+            : "task";
+    const scopeRef = run.reviewRoundId ?? run.workItemId;
+    const materialized = collectAuthorizedContext(store, run);
+    const previous = store.listContextSnapshots(run.taskId)
+        .filter((candidate) => candidate.scope === scope && candidate.scopeRef === scopeRef)
+        .sort((left, right) => left.sequence - right.sequence)
+        .at(-1);
+    const snapshot = createContextSnapshot({
+        id: store.nextContextSnapshotId(run.taskId),
+        taskId: run.taskId,
+        scope,
+        ...(scopeRef === undefined ? {} : { scopeRef }),
+        sequence: (previous?.sequence ?? 0) + 1,
+        refs: materialized.map(({ ref }) => ref),
+        resources: materialized,
+        acceptRefs: run.workItemId === undefined ? [] : [`work-item:${run.workItemId}:acceptance`],
+        ...(previous === undefined ? {} : { parentRef: contextSnapshotRef(previous) }),
+        frozenAt: now,
+        frozenBy
+    });
+    store.saveContextSnapshot(snapshot);
+    return snapshot;
+}
+/** Bounded changed-ref hint between one frozen Snapshot and its exact parent. */
+export function contextSnapshotDeltaRefIds(store, snapshot) {
+    validateContextSnapshot(snapshot);
+    if (snapshot.parentRef === undefined)
+        return Object.freeze([]);
+    const parent = store.getContextSnapshot(snapshot.taskId, snapshot.parentRef.id);
+    if (parent === null
+        || parent.digest !== snapshot.parentRef.digest
+        || parent.sequence !== snapshot.parentRef.sequence) {
+        throw new Error(`Context Snapshot parent is missing or drifted: ${snapshot.parentRef.id}.`);
+    }
+    validateContextSnapshot(parent);
+    const previous = new Map(parent.refs.map((ref) => [ref.refId, ref]));
+    const changed = snapshot.refs.filter((ref) => {
+        const before = previous.get(ref.refId);
+        return before === undefined
+            || before.digest !== ref.digest
+            || before.revision !== ref.revision
+            || before.store !== ref.store
+            || before.layer !== ref.layer;
+    }).map(({ refId }) => refId);
+    return Object.freeze([...new Set(changed)].sort().slice(0, RUN_BOOTSTRAP_MAX_DELTAS));
+}
+export function buildRunContextPack(store, taskId, runId) {
+    const run = requireExactRun(store, taskId, runId);
+    const current = collectAuthorizedContext(store, run);
+    let pointers = current.map(({ ref }) => ref);
+    let snapshotRef;
+    if (run.assignment.contextSnapshotRef !== undefined) {
+        const expected = run.assignment.contextSnapshotRef;
+        const snapshot = store.getContextSnapshot(taskId, expected.id);
+        if (snapshot === null)
+            throw new Error(`Run Context Snapshot is missing: ${expected.id}.`);
+        validateContextSnapshot(snapshot);
+        if (snapshot.digest !== expected.digest || snapshot.taskId !== taskId) {
+            throw new Error(`Run Context Snapshot identity drifted: ${expected.id}.`);
+        }
+        pointers = snapshot.refs;
+        snapshotRef = contextSnapshotRef(snapshot);
+    }
+    if (pointers.length > RUN_CONTEXT_PACK_MAX_REFS) {
+        throw new Error(`Run Context exceeds ${RUN_CONTEXT_PACK_MAX_REFS} authorized refs.`);
+    }
+    const view = contextView(run);
+    const writableProjectIds = writableProjects(store, run, view);
+    const summaries = pointers.map((ref) => Object.freeze({
+        refId: ref.refId,
+        store: ref.store,
+        summary: ref.summary ?? `${ref.store} ${ref.refId}`,
+        digest: ref.digest
+    }));
+    const body = {
+        schemaVersion: RUN_CONTEXT_PACK_SCHEMA_VERSION,
+        identity: Object.freeze({
+            taskId,
+            runId,
+            roleName: run.roleName,
+            purpose: run.purpose,
+            agentId: run.effective.agentId,
+            adapterId: run.effective.adapterId,
+            workspace: run.effective.workspace.root
+        }),
+        ...(snapshotRef === undefined ? {} : { snapshot: snapshotRef }),
+        assignment: run.assignment,
+        authority: Object.freeze({ view, readableRefs: pointers, writableProjectIds }),
+        pointers,
+        summaries,
+        deltas: pointers.filter((ref) => run.assignment.deltaRefIds.includes(ref.refId)),
+        completion: Object.freeze({
+            allowedActions: completionActions(view),
+            exactRunRef: `${taskId}/${runId}`
+        })
+    };
+    const digest = contextContentDigest(body);
+    const preliminaryBytes = Buffer.byteLength(JSON.stringify({ ...body, digest }), "utf8");
+    if (preliminaryBytes > RUN_CONTEXT_PACK_MAX_BYTES) {
+        throw new Error(`Run Context Pack exceeds ${RUN_CONTEXT_PACK_MAX_BYTES} bytes.`);
+    }
+    const pack = Object.freeze({
+        ...body,
+        budget: Object.freeze({
+            maxRefs: RUN_CONTEXT_PACK_MAX_REFS,
+            returnedRefs: pointers.length,
+            maxBytes: RUN_CONTEXT_PACK_MAX_BYTES,
+            returnedBytes: preliminaryBytes,
+            truncated: false
+        }),
+        digest
+    });
+    return pack;
+}
+export function expandRunContextRef(store, taskId, runId, refId) {
+    const pack = buildRunContextPack(store, taskId, runId);
+    const authorized = pack.pointers.filter((ref) => ref.refId === refId);
+    if (authorized.length !== 1) {
+        throw new Error(`Run Context ref is not uniquely authorized: ${refId}.`);
+    }
+    const run = requireExactRun(store, taskId, runId);
+    const snapshotRef = run.assignment.contextSnapshotRef;
+    const materialized = snapshotRef === undefined
+        ? collectAuthorizedContext(store, run).find(({ ref }) => (contextRefIdentity(ref) === contextRefIdentity(authorized[0])))
+        : store.getContextSnapshot(taskId, snapshotRef.id)?.resources.find(({ ref }) => (contextRefIdentity(ref) === contextRefIdentity(authorized[0])));
+    if (materialized === undefined || materialized.ref.digest !== authorized[0].digest) {
+        throw new Error(`Run Context ref is unavailable or drifted: ${refId}.`);
+    }
+    const bytes = Buffer.byteLength(JSON.stringify(materialized.value), "utf8");
+    if (bytes > RUN_CONTEXT_EXPAND_MAX_BYTES) {
+        throw new Error(`Run Context expansion exceeds ${RUN_CONTEXT_EXPAND_MAX_BYTES} bytes.`);
+    }
+    return Object.freeze({
+        ref: materialized.ref,
+        value: materialized.value,
+        digest: contextContentDigest({ ref: materialized.ref, value: materialized.value })
+    });
+}
+/** Fail-closed delta cursor resolution for one immutable Run lineage. */
+export function buildRunContextDelta(store, taskId, runId, after) {
+    const pack = buildRunContextPack(store, taskId, runId);
+    if (after === pack.digest || after === pack.snapshot?.digest) {
+        return Object.freeze({ schemaVersion: 1, after, cursor: pack.digest, refs: [] });
+    }
+    const run = requireExactRun(store, taskId, runId);
+    const snapshotRef = run.assignment.contextSnapshotRef;
+    const snapshot = snapshotRef === undefined
+        ? null
+        : store.getContextSnapshot(taskId, snapshotRef.id);
+    const parentDigest = snapshot?.parentRef?.digest;
+    if (!((parentDigest !== undefined && after === parentDigest)
+        || (parentDigest === undefined && after === "none"))) {
+        throw new Error("Run Context delta cursor is outside the frozen Snapshot lineage.");
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        after,
+        cursor: pack.digest,
+        refs: pack.deltas
+    });
+}
+function requireExactRun(store, taskId, runId) {
+    const run = store.getAgentRun(taskId, runId);
+    if (run === null || run.taskId !== taskId || run.id !== runId) {
+        throw new Error(`Agent Run not found: ${taskId}/${runId}.`);
+    }
+    return run;
+}
+function collectAuthorizedContext(store, run) {
+    const task = store.getTask(run.taskId);
+    if (task === null)
+        throw new Error(`Task not found: ${run.taskId}.`);
+    const view = contextView(run);
+    const result = [materialize("L2", "task", task.id, task)];
+    const brief = store.getTaskBrief(task.id);
+    if (brief !== null && view === "leader") {
+        result.push(materialize("L2", "task-brief", task.id, brief));
+    }
+    const role = store.getRole(task.id, run.roleName);
+    if (role === null)
+        throw new Error(`Run Role not found: ${task.id}/${run.roleName}.`);
+    result.push(materialize("L1", "role-profile", role.name, {
+        name: role.name,
+        defaultAccess: role.defaultAccess,
+        description: role.description,
+        responsibilities: role.responsibilities ?? [],
+        constraints: role.constraints ?? [],
+        expectedOutput: role.expectedOutput,
+        skills: role.skills ?? [],
+        launchRevision: role.launchRevision
+    }));
+    if ("workspace" in run && run.workspace !== undefined) {
+        result.push(materialize("L3", "managed-workspace", `${run.taskId}/${run.roleName}`, run.workspace));
+    }
+    if (run.workItemId !== undefined) {
+        const item = store.getWorkItem(task.id, run.workItemId);
+        if (item === null)
+            throw new Error(`Run WorkItem not found: ${run.workItemId}.`);
+        result.push(materialize("L3", "work-item", item.id, item));
+        if (view === "worker") {
+            for (const dependencyId of item.dependsOn) {
+                const dependency = store.getWorkItem(task.id, dependencyId);
+                if (dependency === null || dependency.status !== "completed") {
+                    throw new Error(`Run WorkItem dependency is not accepted: ${dependencyId}.`);
+                }
+                result.push(materialize("L3", "accepted-work-item", dependency.id, dependency));
+            }
+        }
+    }
+    if (run.reviewRoundId !== undefined) {
+        const round = store.getReviewRound(task.id, run.reviewRoundId);
+        if (round === null)
+            throw new Error(`Run ReviewRound not found: ${run.reviewRoundId}.`);
+        result.push(materialize("L3", "review-round", round.id, round));
+        for (const finding of store.listReviewFindings(task.id).filter((candidate) => (candidate.firstReviewRoundId === round.id
+            || candidate.lastReviewRoundId === round.id
+            || candidate.repair?.workItemId === round.workItemId))) {
+            result.push(materialize("L3", "review-finding", finding.id, finding));
+        }
+    }
+    for (const binding of task.projectBindings) {
+        const project = store.getProject(binding.projectId);
+        if (project === null)
+            throw new Error(`Run Project not found: ${binding.projectId}.`);
+        const { knowledge, ...projectPolicy } = project;
+        result.push(materialize("L1", "project-policy", project.id, projectPolicy));
+        for (const entry of knowledge.filter(({ status }) => status === "active")) {
+            result.push(materialize("L1", "project-knowledge", `${project.id}:${entry.id}`, { projectId: project.id, ...entry }));
+        }
+    }
+    if (view === "leader") {
+        for (const item of store.listWorkItems(task.id)) {
+            result.push(materialize("L3", "work-item", item.id, item));
+        }
+        for (const decision of store.listDecisions(task.id)) {
+            result.push(materialize("L2", "task-decision", decision.id, decision));
+        }
+        for (const milestone of store.listMilestones(task.id).slice(-16)) {
+            result.push(materialize("L2", "task-milestone", milestone.id, milestone));
+        }
+        for (const round of store.listReviewRounds(task.id).slice(-16)) {
+            result.push(materialize("L3", "review-round", round.id, round));
+        }
+        for (const finding of store.listReviewFindings(task.id)) {
+            result.push(materialize("L3", "review-finding", finding.id, finding));
+        }
+        for (const agentRun of store.listAgentRuns(task.id).slice(-24)) {
+            result.push(materialize("L4", "agent-run", agentRun.id, agentRun));
+        }
+        for (const message of store.listMessages(task.id).slice(-16)) {
+            result.push(materialize("L4", "task-message", message.id, message));
+        }
+        for (const request of store.listOpenInputRequests([task.id])) {
+            result.push(materialize("L4", "input-request", request.id, request));
+        }
+    }
+    const unique = new Map(result.map((entry) => [contextRefIdentity(entry.ref), entry]));
+    return [...unique.values()].sort((left, right) => (contextRefIdentity(left.ref).localeCompare(contextRefIdentity(right.ref))));
+}
+function materialize(layer, store, refId, value) {
+    const digest = contextContentDigest(value);
+    const record = value;
+    const revision = String(record.revision ?? record.updatedAt ?? record.createdAt ?? digest);
+    const title = typeof record.title === "string"
+        ? record.title
+        : typeof record.summary === "string"
+            ? record.summary
+            : `${store} ${refId}`;
+    return Object.freeze({
+        ref: Object.freeze({
+            layer,
+            store,
+            refId,
+            revision,
+            digest,
+            summary: title.slice(0, 400)
+        }),
+        value
+    });
+}
+function contextRefIdentity(ref) {
+    return `${ref.store}\0${ref.refId}\0${ref.revision}`;
+}
+function contextView(run) {
+    if (run.purpose === "review")
+        return "reviewer";
+    if (run.roleName === "leader")
+        return "leader";
+    if (run.roleName === "operator")
+        return "operator";
+    return "worker";
+}
+function writableProjects(store, run, view) {
+    if (view === "leader")
+        return Object.freeze(store.getTask(run.taskId)?.projectBindings.map(({ projectId }) => projectId) ?? []);
+    if (view === "reviewer") {
+        return Object.freeze(run.workspace?.entries.filter(({ access }) => access === "write").map(({ projectId }) => projectId) ?? []);
+    }
+    if (run.workItemId === undefined)
+        return Object.freeze([]);
+    return Object.freeze(store.getWorkItem(run.taskId, run.workItemId)?.writeProjectIds ?? []);
+}
+function completionActions(view) {
+    if (view === "leader")
+        return Object.freeze(["yield", "complete-task", "request-input"]);
+    if (view === "reviewer")
+        return Object.freeze(["checkpoint", "yield-review"]);
+    if (view === "operator")
+        return Object.freeze(["answer-input", "recover"]);
+    return Object.freeze(["checkpoint", "yield"]);
+}

package/dist/context/sessionBootstrapManifest.js

@@ -0,0 +1,81 @@
+import { createHash } from "node:crypto";
+import { chmodSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { exactControlPlaneCommandPrefix, exactControlPlaneDigest, serializeExactDescriptor } from "../runtime/exactControlPlane.js";
+import { writeTextFileAtomically } from "../storage/durableFile.js";
+import { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
+export { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
+export function materializeSessionBootstrap(input) {
+    const home = resolve(input.yuiHome);
+    const controlDigest = exactControlPlaneDigest(input.controlPlane);
+    const descriptorPath = resolve(join(home, "runtime", "control-plane", `${controlDigest}.json`));
+    writeImmutableText(descriptorPath, `${serializeExactDescriptor(input.controlPlane)}\n`);
+    const sessionCliContent = [
+        "#!/bin/sh",
+        `exec ${exactControlPlaneCommandPrefix(input.controlPlane)} \"$@\"`,
+        ""
+    ].join("\n");
+    const sessionCliDigest = digest(sessionCliContent);
+    const sessionCliPath = resolve(join(home, "runtime", "session-cli", `yui-${sessionCliDigest}.sh`));
+    writeImmutableText(sessionCliPath, sessionCliContent);
+    chmodSync(sessionCliPath, 0o700);
+    const roleProfile = {
+        roleName: input.role.name,
+        roleKind: input.roleKind,
+        defaultAccess: input.role.defaultAccess,
+        description: input.role.description,
+        responsibilities: input.role.responsibilities ?? [],
+        constraints: input.role.constraints ?? [],
+        expectedOutput: input.role.expectedOutput,
+        systemPrompt: input.role.systemPrompt
+    };
+    const profileContent = `${JSON.stringify(roleProfile, null, 2)}\n`;
+    const profileDigest = digest(profileContent);
+    const roleProfilePath = resolve(join(home, "runtime", "role-profiles", `${profileDigest}.json`));
+    writeImmutableText(roleProfilePath, profileContent);
+    const body = {
+        schemaVersion: SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION,
+        protocol: SESSION_CONTEXT_PROTOCOL,
+        owner: input.owner,
+        effectiveRevision: input.role.launchRevision,
+        roleKind: input.roleKind,
+        compatibilityDigest: sessionManifestCompatibilityDigest(input.role.name, input.roleKind, input.role),
+        controlPlane: {
+            descriptorPath,
+            sessionCliPath,
+            digest: controlDigest
+        },
+        skills: input.skills.map((skill) => Object.freeze({
+            id: skill.id,
+            path: skill.path,
+            digest: digest(skill.content)
+        })),
+        roleProfileRef: { digest: profileDigest, path: roleProfilePath },
+        contextProtocol: input.owner.scope === "global"
+            ? {
+                loadCommand: `\"${sessionCliPath}\" role context \"$YUI_ROLE\" --json`
+            }
+            : {
+                loadCommand: `\"${sessionCliPath}\" task run context \"$YUI_TASK_ID/<run-id>\" --json`,
+                expandCommand: `\"${sessionCliPath}\" task run context expand \"$YUI_TASK_ID/<run-id>\" <ref-id> --mode full --json`
+            }
+    };
+    const manifest = Object.freeze({ ...body, digest: digest(body) });
+    const manifestPath = resolve(join(home, "runtime", "session-manifests", `${manifest.digest}.json`));
+    writeImmutableText(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return Object.freeze({
+        manifest,
+        manifestPath,
+        sessionCliPath,
+        roleProfilePath,
+        descriptorPath
+    });
+}
+function writeImmutableText(path, content) {
+    writeTextFileAtomically(path, content);
+    chmodSync(path, 0o600);
+}
+function digest(value) {
+    const bytes = typeof value === "string" ? value : JSON.stringify(value);
+    return createHash("sha256").update(bytes).digest("hex");
+}

package/dist/context/sessionProtocolIdentity.js

@@ -0,0 +1,23 @@
+import { createHash } from "node:crypto";
+export const SESSION_CONTEXT_PROTOCOL = "yui-managed-context/v1";
+export const SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION = 1;
+/** Pure compatibility identity: safe for storage/domain code with no control-plane I/O edge. */
+export function sessionManifestCompatibilityDigest(roleName, roleKind, profile) {
+    return createHash("sha256").update(JSON.stringify({
+        protocol: SESSION_CONTEXT_PROTOCOL,
+        roleName,
+        roleKind,
+        profile: {
+            description: profile.description,
+            responsibilities: profile.responsibilities ?? [],
+            constraints: profile.constraints ?? [],
+            expectedOutput: profile.expectedOutput,
+            systemPrompt: profile.systemPrompt,
+            skillIds: [
+                "yui-runtime",
+                ...(roleKind === "global" ? [] : [`yui-${roleKind}`]),
+                ...(profile.skills ?? [])
+            ]
+        }
+    })).digest("hex");
+}

package/dist/controller/agentRuntimeObserver.js

@@ -60,7 +60,11 @@ export class AgentRuntimeObserver {
             // identity or the canonical sequence assigned to a source.
             const sequence = sequenceBase + index;
             if (existingState === undefined && freshSession && state.usage === undefined) {
-                const zero = Object.freeze({ inputTokens: 0, outputTokens: 0 });
+                const zero = Object.freeze({
+                    semantics: "cumulative-session",
+                    inputTokens: 0,
+                    outputTokens: 0
+                });
                 this.inbox.enqueueObservation(createRuntimeObservation({
                     schemaVersion: 2,
                     eventId: observationId("baseline", fence, source.sourceId, "zero"),
@@ -266,6 +270,7 @@ function observationId(kind, fence, sourceId, value) {
 }
 function sameUsage(left, right) {
     return left !== undefined
+        && left.semantics === right.semantics
         && left.inputTokens === right.inputTokens
         && left.outputTokens === right.outputTokens
         && left.cachedInputTokens === right.cachedInputTokens

package/dist/controller/controller.js

@@ -1432,13 +1432,14 @@ export class FileTaskController {
                     }]
                 : []),
             // Issue 04 durable in-place retry timer: arm the Controller wake at the
-            // earliest `nextAttemptAt` so a due retry re-pushes on its original
-            // Session. The projection is durable, so a restart resumes the lineage.
+            // earliest dispatch/deadline wake. Scheduled retries re-push on their
+            // original Session; in-flight retries only wake at the episode deadline.
+            // The projection is durable, so a restart resumes the lineage.
             ...(typeof this.store.listPendingProviderRetries === "function"
                 ? this.store.listPendingProviderRetries()
                 : []).map((retry) => ({
                 key: `role:${encodeURIComponent(retry.taskId)}/${encodeURIComponent(retry.roleName)}`,
-                at: Date.parse(retry.nextAttemptAt)
+                at: Date.parse(retry.dueAt)
             }))
         ];
         const nearest = nearestDeadlineBatch(deadlines);