@zq-silk/yui 0.6.2 → 0.6.4

package/dist/executor/fileRoleLaunchPlanner.js

@@ -19,6 +19,8 @@ import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR, assertExactT
 import { readActiveReleasePointer } from "../release/runtimeRelease.js";
 import { parseTaskRuntimeIsolationDescriptor, taskRuntimeIsolationEnvironment } from "../runtime/taskRuntimeIsolation.js";
 import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
+import { builtinAgentDriverRegistry, builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
+import { managedRuntimeAdmission } from "../runtime/agentDriver.js";
 /** Builds managed native Agent launches from the authoritative Task records. */
 export class FileRoleLaunchPlanner {
     home;
@@ -304,14 +306,24 @@ export class FileRoleLaunchPlanner {
                 trustWorkspace: true
             })
             : undefined;
-        if (codexConfig?.notify.status === "configured") {
+        if (codexConfig?.notify.status === "configured"
+            && (owner.scope !== "task" || input.runId === undefined)) {
             throw new Error("Codex notify is already configured by "
-                + `${codexConfig.notify.source}; Yui requires exclusive ownership of the structured `
-                + "notify callback and refuses to replace or be replaced by native configuration.");
+                + `${codexConfig.notify.source}; this interactive Yui Session requires exclusive `
+                + "ownership of the structured notify callback and refuses to replace or be replaced "
+                + "by native configuration.");
         }
         const managedRun = owner.scope === "task" && input.runId !== undefined
             ? this.store.getAgentRun(owner.taskId, input.runId)
             : null;
+        const driver = builtinAgentDriverRegistry().require(builtinDriverIdForAdapter(configured.adapterId));
+        if (owner.scope === "task" && input.runId !== undefined) {
+            const admission = managedRuntimeAdmission(driver.capabilities);
+            if (!admission.admitted) {
+                throw new Error(`Agent Driver ${driver.id} cannot host managed Runs; missing capabilities: `
+                    + admission.missing.join(", "));
+            }
+        }
         const roleConfig = binding.config.adapterId === "claude"
             && owner.scope === "task"
             && input.runId !== undefined
@@ -352,9 +364,15 @@ export class FileRoleLaunchPlanner {
             this.#resourceRegistrar().registerSessionContext(sessionContext.managedContextFile, { home: resolve(this.home), taskId: owner.taskId, basis: "descriptor" });
         }
         let args = [...compiled.argv];
+        let command = configured.command;
         let session;
         if (binding.adapterId === "codex") {
-            args = addCodexSessionNotify(args, launchMode, this.#cliPath);
+            // Global/interactive Codex sessions still use notify for presentation.
+            // Managed Runs use the structured Driver Hook as their sole lifecycle
+            // authority, avoiding two terminal channels for the same Turn.
+            if (owner.scope !== "task" || input.runId === undefined) {
+                args = addCodexSessionNotify(args, launchMode, this.#cliPath);
+            }
             // A fresh Codex TUI has no provider event before its first prompt. Carry
             // the exact Run input as the provider's positional launch prompt so it is
             // submitted only after Codex completes startup; never race terminal bytes
@@ -374,6 +392,7 @@ export class FileRoleLaunchPlanner {
         }
         else if (launchMode === "new") {
             if (owner.scope === "task" && input.runId !== undefined) {
+                args.push("-p", "--output-format", "stream-json", "--input-format", "stream-json", "--verbose");
                 args.push("--plugin-dir", ensureManagedClaudeLifecyclePlugin(this.home, this.#cliPath));
             }
             const nativeSessionId = requireText(input.launchId === undefined
@@ -384,10 +403,25 @@ export class FileRoleLaunchPlanner {
         }
         else {
             if (owner.scope === "task" && input.runId !== undefined) {
+                args.push("-p", "--output-format", "stream-json", "--input-format", "stream-json", "--verbose");
                 args.push("--plugin-dir", ensureManagedClaudeLifecyclePlugin(this.home, this.#cliPath));
             }
             session = readySession(input.agentId, binding.adapterId, resumeNativeSessionId, effective);
         }
+        const managedClaudeRun = binding.adapterId === "claude"
+            && owner.scope === "task"
+            && input.runId !== undefined;
+        if (managedClaudeRun) {
+            command = process.execPath;
+            args = [
+                this.#cliPath,
+                "internal",
+                "managed-claude-run",
+                "--",
+                configured.command,
+                ...args
+            ];
+        }
         const runtimeDescriptor = owner.scope === "task"
             ? createExactTaskRuntimeDescriptor({
                 controlPlaneDigest: exactControlPlaneDigest(this.#controlPlane),
@@ -418,7 +452,7 @@ export class FileRoleLaunchPlanner {
             jobCallerKey = randomBytes(32).toString("hex");
         }
         const launch = {
-            command: configured.command,
+            command,
             args,
             env: {
                 ...launchEnvironment,
@@ -428,6 +462,7 @@ export class FileRoleLaunchPlanner {
                 YUI_ROLE: role.name,
                 YUI_AGENT_ID: configured.id,
                 YUI_ADAPTER_ID: configured.adapterId,
+                YUI_DRIVER_ID: driver.id,
                 YUI_WORKSPACE: effectiveWorkspace,
                 ...(jobCallerKey === undefined ? {} : { YUI_JOB_CALLER_KEY: jobCallerKey }),
                 ...(runtimeDescriptor === undefined
@@ -468,7 +503,7 @@ export class FileRoleLaunchPlanner {
             },
             launch: scopedLaunch,
             session,
-            ...(binding.adapterId === "codex" && input.runId !== undefined
+            ...((binding.adapterId === "codex" || managedClaudeRun) && input.runId !== undefined
                 ? { initialPromptRunId: input.runId }
                 : {})
         };
@@ -570,19 +605,24 @@ function ensureManagedClaudeLifecyclePlugin(home, cliPath) {
     const command = {
         type: "command",
         command: canonicalPath(process.execPath),
-        args: [canonicalPath(cliPath), "internal", "claude-hook"]
+        args: [canonicalPath(cliPath), "internal", "runtime-hook"]
     };
     writeTextFileAtomically(join(root, "hooks", "hooks.json"), `${JSON.stringify({
         hooks: {
-            // SessionStart proves the session exists (and, for source=startup,
-            // pre-input readiness); UserPromptSubmit is the exact provider-accepted
-            // fence; PostToolUse is a provider-native in-turn progress fact and
-            // StopFailure is the terminal failure fact. All route to the same
-            // Yui-owned entrypoint, which parses by hook_event_name.
+            // All native names terminate at the Driver edge; core sees only
+            // canonical RuntimeObservation values.
             SessionStart: [{ hooks: [command] }],
             UserPromptSubmit: [{ hooks: [command] }],
+            PreToolUse: [{ hooks: [command] }],
+            PermissionRequest: [{ hooks: [command] }],
+            MessageDisplay: [{ hooks: [command] }],
             PostToolUse: [{ hooks: [command] }],
-            StopFailure: [{ hooks: [command] }]
+            PostToolUseFailure: [{ hooks: [command] }],
+            SubagentStart: [{ hooks: [command] }],
+            SubagentStop: [{ hooks: [command] }],
+            Stop: [{ hooks: [command] }],
+            StopFailure: [{ hooks: [command] }],
+            SessionEnd: [{ hooks: [command] }]
         }
     }, null, 2)}\n`);
     return root;
@@ -669,10 +709,19 @@ function codexLifecycleHooksConfig(cliPath) {
         shellQuote(canonicalPath(process.execPath)),
         shellQuote(canonicalPath(cliPath)),
         "internal",
-        "codex-hook"
+        "runtime-hook"
     ].join(" ");
     const handler = `{hooks=[{type="command",command=${JSON.stringify(command)}}]}`;
-    return `hooks={SessionStart=[${handler}],UserPromptSubmit=[${handler}]}`;
+    return `hooks={`
+        + `SessionStart=[${handler}],`
+        + `UserPromptSubmit=[${handler}],`
+        + `PreToolUse=[${handler}],`
+        + `PermissionRequest=[${handler}],`
+        + `PostToolUse=[${handler}],`
+        + `SubagentStart=[${handler}],`
+        + `SubagentStop=[${handler}],`
+        + `Stop=[${handler}]`
+        + `}`;
 }
 function addCodexLifecycleHooks(args, mode, cliPath) {
     // Session flags are Yui-owned and exact to this launch. Hook trust bypass is

package/dist/executor/managedClaudeRunner.js

@@ -0,0 +1,121 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:os";
+const SIGKILL_GRACE_MS = 2_000;
+/** The documented Claude Code stream-json user-message envelope. */
+export function buildManagedClaudeInput(prompt) {
+    if (typeof prompt !== "string" || prompt.includes("\0")) {
+        throw new TypeError("Managed Claude prompt must be text without NUL bytes.");
+    }
+    return `${JSON.stringify({
+        type: "user",
+        message: {
+            role: "user",
+            content: [{ type: "text", text: prompt }]
+        }
+    })}\n`;
+}
+/**
+ * Runs one autonomous Claude turn without exposing the prompt in argv or
+ * depending on terminal readiness/key timing. stdout/stderr are connected
+ * before stdin is written, so a provider startup burst cannot deadlock the
+ * prompt pipe. EOF makes this a finite per-Run process; native continuity is
+ * carried by Claude's --session-id/--resume arguments.
+ */
+export async function runManagedClaudeProcess(input) {
+    const command = requireProcessToken(input.command, "Managed Claude command");
+    const args = input.args.map((value) => requireProcessToken(value, "Managed Claude argument"));
+    const child = spawn(command, args, {
+        ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
+        env: input.environment ?? process.env,
+        stdio: [
+            "pipe",
+            input.stdout === undefined ? "inherit" : "pipe",
+            input.stderr === undefined ? "inherit" : "pipe"
+        ],
+        // Linux-only package: isolate the Provider process tree so tmux/session
+        // cancellation cannot leave Claude tool descendants behind.
+        detached: true
+    });
+    if (child.stdin === null) {
+        child.kill();
+        throw new Error("Managed Claude stdin pipe is unavailable.");
+    }
+    if (input.stdout !== undefined)
+        child.stdout.pipe(input.stdout, { end: false });
+    if (input.stderr !== undefined)
+        child.stderr.pipe(input.stderr, { end: false });
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    const handlers = new Map();
+    let killTimer;
+    let terminationRequested = false;
+    let childSettled = false;
+    const signalProcessGroup = (signal) => {
+        if (child.pid === undefined || child.exitCode !== null || child.signalCode !== null)
+            return;
+        try {
+            process.kill(-child.pid, signal);
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                throw error;
+        }
+    };
+    const terminateProcessGroup = (signal) => {
+        if (terminationRequested)
+            return;
+        terminationRequested = true;
+        signalProcessGroup(signal);
+        killTimer = setTimeout(() => signalProcessGroup("SIGKILL"), SIGKILL_GRACE_MS);
+        killTimer.unref();
+    };
+    for (const signal of signals) {
+        const handler = () => terminateProcessGroup(signal);
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+    try {
+        const closed = new Promise((resolve, reject) => {
+            child.once("error", (error) => {
+                childSettled = true;
+                reject(error);
+            });
+            child.once("close", (code, signal) => {
+                childSettled = true;
+                resolve({ code, signal });
+            });
+        });
+        try {
+            await new Promise((resolve, reject) => {
+                child.stdin.once("error", reject);
+                child.stdin.end(buildManagedClaudeInput(input.prompt), "utf8", resolve);
+            });
+        }
+        catch (error) {
+            // A failed prompt pipe is not permission to orphan a Provider process or
+            // its tools. Terminate the whole group and wait for bounded convergence.
+            if (!childSettled) {
+                terminateProcessGroup("SIGTERM");
+                await closed.catch(() => undefined);
+            }
+            throw error;
+        }
+        const result = await closed;
+        return result.code ?? (result.signal === null ? 1 : signalExitCode(result.signal));
+    }
+    finally {
+        if (killTimer !== undefined)
+            clearTimeout(killTimer);
+        for (const [signal, handler] of handlers)
+            process.removeListener(signal, handler);
+    }
+}
+function requireProcessToken(value, label) {
+    if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
+        throw new TypeError(`${label} must be non-empty text without NUL bytes.`);
+    }
+    return value;
+}
+function signalExitCode(signal) {
+    const number = constants.signals[signal];
+    return number === undefined ? 1 : 128 + number;
+}

package/dist/observability/executionAudit.js

@@ -14,6 +14,7 @@ import { readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
 import { resolveTaskStoreBackendForHome } from "../storage/sqliteStore.js";
+import { runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
 import { classifyAgentRunFailure, classifyIntegrationAttempt, classifyReviewRound, classifyWakeReasons, countFaultClasses } from "./faultClassification.js";
 import { UNSUPPORTED } from "./runtimeIdentity.js";
 export function createProductionExecutionAuditPorts() {
@@ -289,9 +290,10 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
                         continue;
                     if (event.type === "runtime.role-session-reset")
                         resets += 1;
-                    else if (event.type === "runtime.provider-session-lifecycle")
+                    else if (runtimeObservationFromTaskEvent(event)?.kind.startsWith("session.")) {
                         lifecycleEvents += 1;
-                    else if (event.type === "runtime.claude-stop-failure")
+                    }
+                    else if (event.type === "runtime.turn-failed")
                         stopFailures += 1;
                 }
             }
@@ -420,8 +422,9 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
                     if (!inWindow(event.createdAt, options))
                         continue;
                     total += 1;
-                    if (event.type === "runtime.provider-turn-progress")
+                    if (runtimeObservationFromTaskEvent(event)?.kind === "activity.observed") {
                         progressEvents += 1;
+                    }
                     else if (event.type === "runtime.event-obsolete")
                         obsoleteEvents += 1;
                 }

package/dist/repository/taskWorkspacePreparer.js

@@ -8,7 +8,7 @@ import { attachReviewRoundWorkspace, recordReviewWorkspaceDisposition } from "..
 import { StorageConflictError } from "../storage/taskStore.js";
 import { bindTaskWorkspaceIdentity } from "../task/task.js";
 import { createCandidateGitSnapshot, createDirectTaskMainSnapshot, workItemExecutionGroupById, recordWorkItemWorkspaceDisposition } from "../workItem/workItem.js";
-import { createManagedWorkspace, managedWorkspaceKey, managedWorktreeName } from "../worktree/managedWorkspace.js";
+import { createManagedWorkspace, managedWorkspaceKey, managedWorktreeName, sameManagedWorkspaceIdentity } from "../worktree/managedWorkspace.js";
 import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
 import { NodeGitWorkspace, worktreeIdentity } from "./gitWorkspace.js";
 import { acquireProjectMaintenanceLocks } from "./projectMaintenanceLock.js";
@@ -2542,9 +2542,6 @@ function sameEffectiveWorkspace(effective, workspace) {
 function sameManagedWorkspace(left, right) {
     return isDeepStrictEqual(left, right);
 }
-function sameManagedWorkspaceIdentity(left, right) {
-    return isDeepStrictEqual({ owner: left.owner, root: left.root, entries: left.entries }, { owner: right.owner, root: right.root, entries: right.entries });
-}
 function isMissingPath(error) {
     return typeof error === "object" && error !== null && "code" in error
         && error.code === "ENOENT";

package/dist/run/providerRetryConfig.js

@@ -1,20 +1,25 @@
-const KNOWN_ADAPTERS = ["claude", "codex"];
+import { supportedAgentAdapterIds } from "../agent/adapterCatalog.js";
 function parseAdapters(value) {
     if (value === undefined)
         return [];
+    const supported = supportedAgentAdapterIds();
+    const supportedSet = new Set(supported);
     const adapters = [];
     for (const raw of value.split(",")) {
         const token = raw.trim().toLowerCase();
         if (token === "")
             continue;
         if (token === "all") {
-            for (const adapter of KNOWN_ADAPTERS) {
+            for (const adapter of supported) {
                 if (!adapters.includes(adapter))
                     adapters.push(adapter);
             }
             continue;
         }
-        if (!KNOWN_ADAPTERS.includes(token)) {
+        if (!/^[a-z0-9][a-z0-9._-]*$/u.test(token)) {
+            throw new Error(`Invalid Provider retry adapter: ${token}.`);
+        }
+        if (!supportedSet.has(token)) {
             throw new Error(`Unknown Provider retry adapter: ${token}.`);
         }
         if (!adapters.includes(token)) {

package/dist/runtime/agentDriver.js

@@ -0,0 +1,229 @@
+const SURFACES = ["managed-protocol", "interactive-cli"];
+const OPERATIONS = ["model", "tool", "subagent"];
+const WAIT_REASONS = ["user", "permission", "external"];
+const USAGE_MODES = [
+    "streaming-cumulative",
+    "event-snapshot",
+    "terminal-cumulative",
+    "unavailable"
+];
+const DELIVERY_MODES = [
+    "ordered-replayable",
+    "ordered-best-effort",
+    "best-effort",
+    "host-only"
+];
+export function validateAgentDriverCapabilities(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Agent Driver capabilities must be an object.");
+    }
+    const surfaces = uniqueMembers(input.surfaces, SURFACES, "Agent Driver surface");
+    if (surfaces.length === 0)
+        throw new Error("Agent Driver must expose at least one surface.");
+    const control = input.control;
+    if (control === null || typeof control !== "object" || Array.isArray(control)) {
+        throw new Error("Agent Driver control capabilities must be an object.");
+    }
+    for (const name of ["start", "resume", "sendTurn", "interrupt", "stop"]) {
+        if (typeof control[name] !== "boolean") {
+            throw new Error(`Agent Driver control capability ${name} must be boolean.`);
+        }
+    }
+    const observation = input.observation;
+    if (observation === null || typeof observation !== "object" || Array.isArray(observation)) {
+        throw new Error("Agent Driver observation capabilities must be an object.");
+    }
+    if (observation.sessionIdentity !== "exact" && observation.sessionIdentity !== "unavailable") {
+        throw new Error("Agent Driver session identity capability is invalid.");
+    }
+    if (observation.sessionBootstrap !== "preallocated"
+        && observation.sessionBootstrap !== "discovered") {
+        throw new Error("Agent Driver Session bootstrap capability is invalid.");
+    }
+    if (observation.preInputReadiness !== "exact"
+        && observation.preInputReadiness !== "unavailable") {
+        throw new Error("Agent Driver pre-input readiness capability is invalid.");
+    }
+    if (observation.promptAcceptance !== "exact" && observation.promptAcceptance !== "unavailable") {
+        throw new Error("Agent Driver prompt acceptance capability is invalid.");
+    }
+    if (!["exact", "partial", "unavailable"].includes(observation.turnLifecycle)) {
+        throw new Error("Agent Driver turn lifecycle capability is invalid.");
+    }
+    if (!USAGE_MODES.includes(observation.usage)) {
+        throw new Error("Agent Driver usage capability is invalid.");
+    }
+    if (!DELIVERY_MODES.includes(observation.delivery)) {
+        throw new Error("Agent Driver delivery capability is invalid.");
+    }
+    return Object.freeze({
+        surfaces: Object.freeze(surfaces),
+        control: Object.freeze({
+            start: control.start,
+            resume: control.resume,
+            sendTurn: control.sendTurn,
+            interrupt: control.interrupt,
+            stop: control.stop
+        }),
+        observation: Object.freeze({
+            sessionIdentity: observation.sessionIdentity,
+            sessionBootstrap: observation.sessionBootstrap,
+            preInputReadiness: observation.preInputReadiness,
+            promptAcceptance: observation.promptAcceptance,
+            turnLifecycle: observation.turnLifecycle,
+            operations: Object.freeze(uniqueMembers(observation.operations, OPERATIONS, "Agent Driver operation")),
+            waiting: Object.freeze(uniqueMembers(observation.waiting, WAIT_REASONS, "Agent Driver wait reason")),
+            usage: observation.usage,
+            delivery: observation.delivery
+        })
+    });
+}
+export function managedRuntimeAdmission(capabilities) {
+    const actual = validateAgentDriverCapabilities(capabilities);
+    const missing = [];
+    if (!actual.control.start)
+        missing.push("start");
+    if (!actual.control.resume)
+        missing.push("resume");
+    if (!actual.control.sendTurn)
+        missing.push("send-turn");
+    if (!actual.control.interrupt)
+        missing.push("interrupt");
+    if (!actual.control.stop)
+        missing.push("stop");
+    if (actual.observation.sessionIdentity !== "exact")
+        missing.push("exact-session-identity");
+    if (actual.observation.promptAcceptance !== "exact")
+        missing.push("exact-prompt-acceptance");
+    if (actual.observation.turnLifecycle !== "exact")
+        missing.push("exact-turn-lifecycle");
+    return missing.length === 0
+        ? Object.freeze({ admitted: true })
+        : Object.freeze({ admitted: false, missing: Object.freeze(missing) });
+}
+export class AgentDriverRegistry {
+    #drivers = new Map();
+    #driverIdsByAdapter = new Map();
+    register(input) {
+        const id = requireDriverId(input.id);
+        if (this.#drivers.has(id))
+            throw new Error(`Agent Driver is already registered: ${id}.`);
+        const adapterId = requireAdapterId(input.adapterId);
+        const existingDriverId = this.#driverIdsByAdapter.get(adapterId);
+        if (existingDriverId !== undefined) {
+            throw new Error(`Agent adapter ${adapterId} is already owned by Driver ${existingDriverId}.`);
+        }
+        if (input.protocolVersion !== 1) {
+            throw new Error(`Agent Driver protocol version is unsupported: ${String(input.protocolVersion)}.`);
+        }
+        if (input.runtime === null || typeof input.runtime !== "object") {
+            throw new Error("Agent Driver runtime must be an object.");
+        }
+        if (typeof input.runtime.nativeSessionId !== "function"
+            || typeof input.runtime.nativeTurnId !== "function"
+            || typeof input.runtime.mapHook !== "function"
+            || typeof input.runtime.classifyHook !== "function"
+            || (input.runtime.observer !== undefined
+                && (typeof input.runtime.observer.source !== "function"
+                    || typeof input.runtime.observer.sample !== "function"))) {
+            throw new Error("Agent Driver runtime observation functions are invalid.");
+        }
+        const driver = Object.freeze({
+            id,
+            label: requireText(input.label, "Agent Driver label"),
+            protocolVersion: 1,
+            adapterId,
+            capabilities: validateAgentDriverCapabilities(input.capabilities),
+            runtime: Object.freeze({
+                nativeSessionId: input.runtime.nativeSessionId,
+                nativeTurnId: input.runtime.nativeTurnId,
+                mapHook: input.runtime.mapHook,
+                classifyHook: input.runtime.classifyHook,
+                ...(input.runtime.observer === undefined
+                    ? {}
+                    : { observer: Object.freeze({
+                            source: input.runtime.observer.source,
+                            sample: input.runtime.observer.sample
+                        }) })
+            })
+        });
+        this.#drivers.set(id, driver);
+        this.#driverIdsByAdapter.set(adapterId, id);
+        return driver;
+    }
+    find(id) {
+        return this.#drivers.get(id) ?? null;
+    }
+    require(id) {
+        const driver = this.find(id);
+        if (driver === null)
+            throw new Error(`Agent Driver is not registered: ${id}.`);
+        return driver;
+    }
+    findByAdapterId(adapterId) {
+        const driverId = this.#driverIdsByAdapter.get(adapterId);
+        return driverId === undefined ? null : this.require(driverId);
+    }
+    requireByAdapterId(adapterId) {
+        const driver = this.findByAdapterId(adapterId);
+        if (driver === null) {
+            throw new Error(`Agent Driver is not registered for adapter: ${adapterId}.`);
+        }
+        return driver;
+    }
+    list() {
+        return [...this.#drivers.values()].sort((left, right) => left.id.localeCompare(right.id));
+    }
+}
+export function requireDriverId(value) {
+    const id = requireText(value, "Agent Driver id");
+    if (!/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/u.test(id)) {
+        throw new Error("Agent Driver id must be a lowercase namespaced identity.");
+    }
+    return id;
+}
+export function normalizeAgentDriverHookClassification(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Agent Driver Hook classification must be an object.");
+    }
+    if (input.startupSession !== undefined
+        && input.startupSession !== "preallocated"
+        && input.startupSession !== "discovered") {
+        throw new Error("Agent Driver Hook startup Session classification is invalid.");
+    }
+    if (input.terminal !== undefined && typeof input.terminal !== "boolean") {
+        throw new Error("Agent Driver Hook terminal classification is invalid.");
+    }
+    return Object.freeze({
+        ...(input.startupSession === undefined ? {} : { startupSession: input.startupSession }),
+        terminal: input.terminal ?? false
+    });
+}
+function uniqueMembers(input, supported, label) {
+    if (!Array.isArray(input))
+        throw new Error(`${label}s must be an array.`);
+    const result = [];
+    for (const value of input) {
+        if (!supported.includes(value))
+            throw new Error(`${label} is invalid: ${String(value)}.`);
+        if (!result.includes(value))
+            result.push(value);
+    }
+    return result;
+}
+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 > 1_024) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function requireAdapterId(value) {
+    const id = requireText(value, "Agent adapter id");
+    if (!/^[a-z0-9][a-z0-9._-]*$/u.test(id)) {
+        throw new Error("Agent adapter id must be a lowercase identity.");
+    }
+    return id;
+}

package/dist/runtime/agentDriverObservation.js

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import { createRuntimeObservation } from "./runtimeObservation.js";
+export function mapAgentDriverHook(input) {
+    requireMatchingDriver(input);
+    const mapped = input.driver.runtime.mapHook({
+        hookEventName: input.hookEventName,
+        payload: input.payload,
+        ...(input.occurrenceId === undefined ? {} : { occurrenceId: input.occurrenceId })
+    });
+    const source = mapped.kind === "turn.accepted"
+        ? input.driver.runtime.observer?.source({
+            hookEventName: input.hookEventName,
+            payload: input.payload,
+            ...(input.occurrenceId === undefined ? {} : { occurrenceId: input.occurrenceId })
+        }) ?? null
+        : null;
+    return observation(input, source === null ? mapped : {
+        ...mapped,
+        payload: Object.freeze({ ...mapped.payload, observerSource: source })
+    });
+}
+export function mapAgentDriverUsage(input, usage) {
+    requireMatchingDriver(input);
+    return observation(input, {
+        kind: "activity.observed",
+        payload: Object.freeze({ activity: "model", usage })
+    });
+}
+function observation(input, mapped) {
+    return createRuntimeObservation({
+        schemaVersion: 1,
+        eventId: hookEventId(input, mapped),
+        kind: mapped.kind,
+        authority: "provider-structured",
+        receivedAt: input.receivedAt,
+        ...(input.observedAt === undefined ? {} : { observedAt: input.observedAt }),
+        ...(input.sequence === undefined ? {} : { sequence: input.sequence }),
+        ...(input.ordinal === undefined ? {} : { ordinal: input.ordinal }),
+        fence: input.fence,
+        payload: mapped.payload
+    });
+}
+function requireMatchingDriver(input) {
+    if (input.fence.driverId !== input.driver.id) {
+        throw new Error("Agent Driver Hook fence does not match the selected Driver.");
+    }
+}
+function hookEventId(input, mapped) {
+    const digest = createHash("sha256").update(JSON.stringify([
+        input.driver.id,
+        input.hookEventName,
+        input.fence,
+        mapped.kind,
+        mapped.payload
+    ])).digest("hex");
+    return `runtime-observation-${digest}`;
+}