@zq-silk/yui 0.6.2 → 0.6.3

package/dist/runtime/runtimeObservation.js

@@ -0,0 +1,297 @@
+import { requireDriverId } from "./agentDriver.js";
+export const RUNTIME_OBSERVATION_TASK_EVENT = "runtime.observation";
+const KINDS = [
+    "host.observed",
+    "session.started",
+    "session.ready",
+    "session.ended",
+    "session.failed",
+    "turn.accepted",
+    "turn.waiting",
+    "turn.completed",
+    "turn.failed",
+    "turn.cancelled",
+    "operation.started",
+    "operation.completed",
+    "operation.failed",
+    "activity.observed",
+    "observer.health"
+];
+const AUTHORITIES = [
+    "controller",
+    "transport",
+    "provider-structured",
+    "driver-inferred",
+    "host",
+    "diagnostic"
+];
+const RUN_SCOPED = new Set([
+    "turn.accepted",
+    "turn.waiting",
+    "turn.completed",
+    "turn.failed",
+    "turn.cancelled",
+    "operation.started",
+    "operation.completed",
+    "operation.failed",
+    "activity.observed",
+    "observer.health"
+]);
+const PROVIDER_STATE = new Set([
+    "session.started",
+    "session.ready",
+    "session.ended",
+    "session.failed",
+    "turn.accepted",
+    "turn.waiting",
+    "turn.completed",
+    "turn.failed",
+    "turn.cancelled",
+    "operation.started",
+    "operation.completed",
+    "operation.failed"
+]);
+export function createRuntimeObservation(input) {
+    if (input.schemaVersion !== 1)
+        throw new Error("Runtime observation schemaVersion must be 1.");
+    if (!KINDS.includes(input.kind))
+        throw new Error("Runtime observation kind is invalid.");
+    if (!AUTHORITIES.includes(input.authority))
+        throw new Error("Runtime observation authority is invalid.");
+    if (input.kind === "host.observed" && input.authority !== "host" && input.authority !== "controller") {
+        throw new Error("host.observed requires host or controller authority.");
+    }
+    if (PROVIDER_STATE.has(input.kind)
+        && input.authority !== "provider-structured"
+        && input.authority !== "controller") {
+        throw new Error(`${input.kind} requires provider-structured or controller authority.`);
+    }
+    const fence = normalizeFence(input.fence);
+    if (RUN_SCOPED.has(input.kind) && fence.runId === undefined) {
+        throw new Error(`${input.kind} requires runId.`);
+    }
+    if (RUN_SCOPED.has(input.kind) && fence.nativeSessionId === undefined) {
+        throw new Error(`${input.kind} requires nativeSessionId.`);
+    }
+    if (RUN_SCOPED.has(input.kind) && fence.nativeTurnId === undefined) {
+        throw new Error(`${input.kind} requires nativeTurnId.`);
+    }
+    const payload = normalizePayload(input.kind, input.payload);
+    const sequence = input.sequence;
+    if (sequence !== undefined && (!Number.isSafeInteger(sequence) || sequence < 0)) {
+        throw new Error("Runtime observation sequence must be a non-negative safe integer.");
+    }
+    const ordinal = input.ordinal;
+    if (ordinal !== undefined && (!Number.isSafeInteger(ordinal) || ordinal < 0)) {
+        throw new Error("Runtime observation ordinal must be a non-negative safe integer.");
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        eventId: requireIdentity(input.eventId, "Runtime observation event id"),
+        kind: input.kind,
+        authority: input.authority,
+        receivedAt: requireTimestamp(input.receivedAt, "Runtime observation receivedAt"),
+        ...(input.observedAt === undefined
+            ? {}
+            : { observedAt: requireTimestamp(input.observedAt, "Runtime observation observedAt") }),
+        ...(sequence === undefined ? {} : { sequence }),
+        ...(ordinal === undefined ? {} : { ordinal }),
+        fence,
+        payload
+    });
+}
+export function runtimeObservationFenceMatches(expected, actual) {
+    for (const field of [
+        "taskId",
+        "roleName",
+        "runId",
+        "agentId",
+        "driverId",
+        "launchId",
+        "sessionGenerationId",
+        "nativeSessionId",
+        "nativeTurnId",
+        "receiptId"
+    ]) {
+        if (expected[field] !== actual[field])
+            return false;
+    }
+    return true;
+}
+/** Compact TaskEvent payload used for durable state-boundary observations. */
+export function runtimeObservationTaskEventPayload(input) {
+    const observation = createRuntimeObservation(input);
+    return Object.freeze({
+        eventId: observation.eventId,
+        roleName: observation.fence.roleName,
+        agentId: observation.fence.agentId,
+        driverId: observation.fence.driverId,
+        launchId: observation.fence.launchId,
+        ...(observation.fence.taskId === undefined ? {} : { taskId: observation.fence.taskId }),
+        ...(observation.fence.runId === undefined ? {} : { runId: observation.fence.runId }),
+        ...(observation.fence.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: observation.fence.nativeSessionId }),
+        kind: observation.kind,
+        receivedAt: observation.receivedAt,
+        observation: JSON.stringify(observation)
+    });
+}
+export function runtimeObservationFromTaskEvent(event) {
+    if (event.type !== RUNTIME_OBSERVATION_TASK_EVENT)
+        return null;
+    try {
+        const parsed = JSON.parse(event.payload.observation ?? "");
+        return createRuntimeObservation(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeFence(input) {
+    return Object.freeze({
+        ...(input.taskId === undefined ? {} : { taskId: requireIdentity(input.taskId, "Task id") }),
+        roleName: requireIdentity(input.roleName, "Role name"),
+        ...(input.runId === undefined ? {} : { runId: requireIdentity(input.runId, "Run id") }),
+        agentId: requireIdentity(input.agentId, "Agent id"),
+        driverId: requireDriverId(input.driverId),
+        launchId: requireIdentity(input.launchId, "Launch id"),
+        sessionGenerationId: requireIdentity(input.sessionGenerationId, "Session generation id"),
+        ...(input.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: requireIdentity(input.nativeSessionId, "Native Session id") }),
+        ...(input.nativeTurnId === undefined
+            ? {}
+            : { nativeTurnId: requireIdentity(input.nativeTurnId, "Native Turn id") }),
+        ...(input.receiptId === undefined
+            ? {}
+            : { receiptId: requireIdentity(input.receiptId, "Receipt id") })
+    });
+}
+function normalizePayload(kind, input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Runtime observation payload must be an object.");
+    }
+    if (kind === "host.observed" && typeof input.alive !== "boolean") {
+        throw new Error("host.observed requires payload.alive.");
+    }
+    if (kind === "turn.waiting"
+        && input.reason !== "user"
+        && input.reason !== "permission"
+        && input.reason !== "external") {
+        throw new Error("turn.waiting requires a supported reason.");
+    }
+    if (kind === "turn.waiting")
+        requireIdentity(input.waitId, "Runtime wait id");
+    if (kind.startsWith("operation.")) {
+        requireIdentity(input.operationId, "Runtime operation id");
+        if (input.operation !== "model" && input.operation !== "tool" && input.operation !== "subagent") {
+            throw new Error("Runtime operation kind is invalid.");
+        }
+    }
+    if (kind === "activity.observed") {
+        if (!["model", "tool", "subagent", "provider", "resource"].includes(input.activity ?? "")) {
+            throw new Error("activity.observed requires an activity kind.");
+        }
+        if (input.usage !== undefined)
+            validateUsage(input.usage);
+    }
+    if (kind === "observer.health") {
+        requireIdentity(input.sourceId, "Runtime observer source id");
+        if (!['healthy', 'degraded', 'unavailable'].includes(input.observerStatus ?? "")) {
+            throw new Error("observer.health requires a supported status.");
+        }
+    }
+    const observerSource = input.observerSource === undefined
+        ? undefined
+        : normalizeObserverSource(input.observerSource);
+    if (kind === "turn.failed" && input.failure === undefined) {
+        throw new Error("turn.failed requires normalized failure evidence.");
+    }
+    const failure = input.failure === undefined
+        ? undefined
+        : normalizeFailure(input.failure);
+    return Object.freeze({
+        ...(input.alive === undefined ? {} : { alive: input.alive }),
+        ...(input.reason === undefined ? {} : { reason: input.reason }),
+        ...(input.waitId === undefined ? {} : { waitId: requireIdentity(input.waitId, "Runtime wait id") }),
+        ...(input.operationId === undefined
+            ? {}
+            : { operationId: requireIdentity(input.operationId, "Runtime operation id") }),
+        ...(input.operation === undefined ? {} : { operation: input.operation }),
+        ...(input.activity === undefined ? {} : { activity: input.activity }),
+        ...(input.activityId === undefined
+            ? {}
+            : { activityId: requireIdentity(input.activityId, "Runtime activity id") }),
+        ...(input.usage === undefined ? {} : { usage: Object.freeze({ ...input.usage }) }),
+        ...(observerSource === undefined ? {} : { observerSource }),
+        ...(input.sourceId === undefined
+            ? {}
+            : { sourceId: requireIdentity(input.sourceId, "Runtime observer source id") }),
+        ...(input.observerStatus === undefined ? {} : { observerStatus: input.observerStatus }),
+        ...(input.observerDetail === undefined
+            ? {}
+            : { observerDetail: requireText(input.observerDetail, "Runtime observer detail") }),
+        ...(failure === undefined ? {} : { failure }),
+        ...(input.summary === undefined ? {} : { summary: requireText(input.summary, "Runtime summary") })
+    });
+}
+function normalizeObserverSource(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Runtime observer source must be an object.");
+    }
+    if (input.schemaVersion !== 1 || input.transport !== "append-only-jsonl") {
+        throw new Error("Runtime observer source is invalid.");
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        sourceId: requireIdentity(input.sourceId, "Runtime observer source id"),
+        transport: "append-only-jsonl",
+        locator: requireText(input.locator, "Runtime observer locator")
+    });
+}
+function normalizeFailure(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Runtime failure evidence must be an object.");
+    }
+    return Object.freeze({
+        code: requireText(input.code, "Runtime failure code"),
+        ...(input.details === undefined
+            ? {}
+            : { details: requireText(input.details, "Runtime failure details") }),
+        ...(input.lastOutput === undefined
+            ? {}
+            : { lastOutput: requireText(input.lastOutput, "Runtime failure last output") })
+    });
+}
+function validateUsage(input) {
+    for (const [name, value] of Object.entries(input)) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new Error(`Runtime usage ${name} must be a non-negative safe integer.`);
+        }
+    }
+    if (input.inputTokens === undefined || input.outputTokens === undefined) {
+        throw new Error("Runtime usage requires inputTokens and outputTokens.");
+    }
+}
+function requireTimestamp(value, label) {
+    const timestamp = requireText(value, label);
+    if (!Number.isFinite(Date.parse(timestamp)))
+        throw new Error(`${label} is invalid.`);
+    return timestamp;
+}
+function requireIdentity(value, label) {
+    const identity = requireText(value, label);
+    if (identity.includes("/../") || identity === "__proto__")
+        throw new Error(`${label} is invalid.`);
+    return identity;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${label} is invalid.`);
+    const normalized = value.trim();
+    if (normalized.length === 0 || normalized.length > 32 * 1024) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}

package/dist/runtime/runtimeProjection.js

@@ -0,0 +1,277 @@
+import { createRuntimeObservation, runtimeObservationFenceMatches, runtimeObservationFromTaskEvent } from "./runtimeObservation.js";
+export function createRuntimeProjection(fence, createdAt) {
+    const timestamp = requireTimestamp(createdAt);
+    return Object.freeze({
+        fence: Object.freeze({ ...fence }),
+        host: "unknown",
+        session: "unknown",
+        turn: "none",
+        operations: Object.freeze({}),
+        activity: Object.freeze({ kind: "none" }),
+        observer: Object.freeze({ status: "unknown" }),
+        stateSince: timestamp,
+        workflow: Object.freeze({
+            lastSemanticProgressAt: timestamp,
+            completed: false,
+            blocked: false
+        })
+    });
+}
+export function projectRuntimeTaskEvents(fence, createdAt, events) {
+    const observations = events
+        .map(runtimeObservationFromTaskEvent)
+        .filter((event) => (event !== null && runtimeObservationFenceMatches(fence, event.fence)))
+        .sort((left, right) => (left.receivedAt.localeCompare(right.receivedAt)
+        || (left.sequence ?? -1) - (right.sequence ?? -1)
+        || (left.ordinal ?? -1) - (right.ordinal ?? -1)
+        || left.eventId.localeCompare(right.eventId)));
+    return observations.reduce(projectRuntimeObservation, createRuntimeProjection(fence, createdAt));
+}
+export function projectRuntimeObservation(current, raw) {
+    const event = createRuntimeObservation(raw);
+    if (!runtimeObservationFenceMatches(current.fence, event.fence)) {
+        throw new Error("Runtime observation fence does not match the projection.");
+    }
+    const at = event.receivedAt;
+    switch (event.kind) {
+        case "host.observed":
+            return next(current, {
+                host: event.payload.alive ? "alive" : "exited",
+                stateSince: at
+            });
+        case "session.started":
+            return next(current, { session: "started", stateSince: at });
+        case "session.ready":
+            return next(current, { session: "ready", stateSince: at });
+        case "session.ended":
+            return next(current, {
+                session: "ended",
+                turn: terminalTurn(current.turn),
+                operations: Object.freeze({}),
+                stateSince: at
+            });
+        case "session.failed":
+            return next(current, {
+                session: "failed",
+                turn: current.turn === "none" ? "failed" : terminalTurn(current.turn, "failed"),
+                operations: Object.freeze({}),
+                stateSince: at
+            });
+        case "turn.accepted":
+            return withActivity(next(current, {
+                session: "active",
+                turn: "accepted",
+                waitingReason: undefined,
+                waitId: undefined,
+                stateSince: at
+            }), "provider", at);
+        case "turn.waiting":
+            return next(current, {
+                session: "waiting",
+                turn: "waiting",
+                waitingReason: event.payload.reason,
+                waitId: event.payload.waitId,
+                stateSince: at
+            });
+        case "turn.completed":
+            return withActivity(next(current, {
+                session: "ready",
+                turn: "completed",
+                waitingReason: undefined,
+                waitId: undefined,
+                operations: Object.freeze({}),
+                stateSince: at
+            }), "provider", at);
+        case "turn.failed":
+            return withActivity(next(current, {
+                session: "ready",
+                turn: "failed",
+                waitingReason: undefined,
+                waitId: undefined,
+                operations: Object.freeze({}),
+                stateSince: at
+            }), "provider", at);
+        case "turn.cancelled":
+            return withActivity(next(current, {
+                session: "ready",
+                turn: "cancelled",
+                waitingReason: undefined,
+                waitId: undefined,
+                operations: Object.freeze({}),
+                stateSince: at
+            }), "provider", at);
+        case "operation.started": {
+            const operationId = event.payload.operationId;
+            const operation = event.payload.operation;
+            return withActivity(next(current, {
+                session: "active",
+                turn: current.turn === "waiting" ? "accepted" : current.turn,
+                waitingReason: undefined,
+                waitId: undefined,
+                operations: Object.freeze({
+                    ...current.operations,
+                    [operationId]: Object.freeze({ kind: operation, startedAt: at })
+                }),
+                stateSince: at
+            }), operation, at);
+        }
+        case "operation.completed":
+        case "operation.failed": {
+            const operations = { ...current.operations };
+            delete operations[event.payload.operationId];
+            return withActivity(next(current, {
+                session: "active",
+                turn: current.turn === "waiting" ? "accepted" : current.turn,
+                waitingReason: undefined,
+                waitId: undefined,
+                operations: Object.freeze(operations),
+                stateSince: at
+            }), event.payload.operation, at);
+        }
+        case "activity.observed": {
+            const usage = event.payload.usage;
+            if (usage !== undefined && !usageAdvanced(current.usage, usage)) {
+                return next(current, { usage: Object.freeze({ ...usage }) });
+            }
+            return withActivity(next(current, {
+                ...(usage === undefined ? {} : { usage: Object.freeze({ ...usage }) }),
+                session: current.turn === "waiting" ? "active" : current.session,
+                turn: current.turn === "waiting" ? "accepted" : current.turn,
+                waitingReason: undefined,
+                waitId: undefined
+            }), event.payload.activity, at);
+        }
+        case "observer.health":
+            return next(current, {
+                observer: Object.freeze({
+                    status: event.payload.observerStatus,
+                    sourceId: event.payload.sourceId,
+                    ...(event.payload.observerDetail === undefined
+                        ? {}
+                        : { detail: event.payload.observerDetail })
+                })
+            });
+        default:
+            return current;
+    }
+}
+export function recordRuntimeSemanticProgress(current, progressAt) {
+    const at = requireTimestamp(progressAt);
+    if (Date.parse(at) <= Date.parse(current.workflow.lastSemanticProgressAt))
+        return current;
+    return next(current, {
+        workflow: Object.freeze({ ...current.workflow, lastSemanticProgressAt: at })
+    });
+}
+export function completeRuntimeWorkflow(current, completedAt) {
+    const at = requireTimestamp(completedAt);
+    return next(current, {
+        workflow: Object.freeze({
+            lastSemanticProgressAt: maxTimestamp(current.workflow.lastSemanticProgressAt, at),
+            completed: true,
+            blocked: false
+        })
+    });
+}
+export function runtimeDisplayStatus(current) {
+    if (current.session === "failed")
+        return "broken";
+    if (current.host === "exited" || current.session === "ended")
+        return "stopped";
+    const operation = dominantOperation(current.operations);
+    if (operation !== null)
+        return `${operation}-active`;
+    if (current.turn === "waiting")
+        return `waiting-${current.waitingReason ?? "external"}`;
+    if (current.session === "ready" || current.turn === "completed"
+        || current.turn === "failed" || current.turn === "cancelled")
+        return "ready";
+    if (current.turn === "accepted" || current.session === "active") {
+        return current.activity.kind === "model" ? "model-active" : "active-quiet";
+    }
+    if (current.session === "started")
+        return "awaiting-provider-acceptance";
+    if (current.host === "alive")
+        return "runtime-unobservable";
+    return "starting";
+}
+export function evaluateRuntimeAttention(current, now, policy) {
+    const display = runtimeDisplayStatus(current);
+    const runtimeIdleMs = current.lastRuntimeActivityAt === undefined
+        ? Number.POSITIVE_INFINITY
+        : now.getTime() - Date.parse(current.lastRuntimeActivityAt);
+    const semanticIdleMs = now.getTime() - Date.parse(current.workflow.lastSemanticProgressAt);
+    const runtime = display === "broken"
+        ? "broken"
+        : display === "stopped"
+            ? "stopped"
+            : display === "runtime-unobservable"
+                ? "unobservable"
+                : display.startsWith("waiting-")
+                    ? "waiting"
+                    : runtimeIdleMs <= policy.runtimeSilenceMs
+                        ? "healthy"
+                        : Object.keys(current.operations).length > 0
+                            ? "active-operation-quiet"
+                            : "quiet";
+    return Object.freeze({
+        runtime,
+        workflow: current.workflow.completed
+            ? "completed"
+            : semanticIdleMs > policy.semanticSilenceMs
+                ? "not-progressing"
+                : "progressing"
+    });
+}
+function withActivity(current, kind, at) {
+    return next(current, {
+        activity: Object.freeze({ kind, observedAt: at }),
+        lastRuntimeActivityAt: maxTimestamp(current.lastRuntimeActivityAt, at)
+    });
+}
+function next(current, patch) {
+    const copy = { ...current, ...patch };
+    if (patch.waitingReason === undefined && Object.hasOwn(patch, "waitingReason")) {
+        delete copy.waitingReason;
+    }
+    if (patch.waitId === undefined && Object.hasOwn(patch, "waitId"))
+        delete copy.waitId;
+    return Object.freeze(copy);
+}
+function usageAdvanced(previous, current) {
+    // A first cumulative snapshot may contain history from a resumed native
+    // Session. It establishes the generation baseline but cannot prove that
+    // tokens were consumed during the current observation window.
+    if (previous === undefined)
+        return false;
+    return usageTotal(current) > usageTotal(previous);
+}
+function usageTotal(usage) {
+    // cachedInputTokens and reasoningTokens are breakdowns of the normalized
+    // input/output totals, not additional usage.
+    return usage.inputTokens + usage.outputTokens;
+}
+function dominantOperation(operations) {
+    const kinds = Object.values(operations).map(({ kind }) => kind);
+    if (kinds.includes("subagent"))
+        return "subagent";
+    if (kinds.includes("tool"))
+        return "tool";
+    if (kinds.includes("model"))
+        return "model";
+    return null;
+}
+function terminalTurn(current, fallback = "cancelled") {
+    return current === "completed" || current === "failed" || current === "cancelled"
+        ? current
+        : fallback;
+}
+function maxTimestamp(left, right) {
+    return left === undefined || Date.parse(right) > Date.parse(left) ? right : left;
+}
+function requireTimestamp(value) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+        throw new Error("Runtime projection timestamp is invalid.");
+    }
+    return value;
+}