@zq-silk/yui 0.15.7 → 0.15.8

package/dist/runtime/agentEndpointIdentity.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { detectRunningRelease } from "../release/runtimeRelease.js";
+import { isAgentAdapterId } from "../agent/adapterCatalog.js";
+/**
+ * The generation of the Endpoint code this process is actually executing.
+ *
+ * Resolved once, at module load, from the immutable release the running module
+ * belongs to — the same idiom the Controller, the handover candidate and the CLI
+ * Home fence already use. A release directory is content-addressed
+ * (`<version>-<packageDigest>`) and byte-verified on install, so its digest
+ * covers every shipped file rather than a hand-picked few, and cannot drift
+ * under a live process: publishing a new release writes a new directory instead
+ * of mutating this one.
+ *
+ * Resolving at load rather than on first use is the point. A digest computed
+ * lazily would read whatever is on disk when the first Session happens to pin,
+ * and could label already-loaded code A with the identity of a newer B.
+ *
+ * A development checkout has no immutable release, and mutable files have no
+ * honest generation: editing a module in place would keep claiming the previous
+ * bytes. So a checkout gets a digest of its loaded Endpoint modules, explicitly
+ * marked `checkout-`, which never compares equal to a release generation. It is
+ * a development identity and is not claimed to be reproducible from a release.
+ */
+const ENDPOINT_CHECKOUT_MODULES = Object.freeze([
+    "agentEndpoint.js",
+    "agentEndpointIdentity.js",
+    "structuredProviderHost.js",
+    "claude-process-owner",
+    "codexAppServerRuntime.js",
+    "acpSession.js",
+    "acpProtocol.js",
+    "acpSessionConfiguration.js",
+    "agentRunConfiguration.js",
+    "jsonLineChannel.js"
+]);
+function resolveEndpointGeneration() {
+    const running = detectRunningRelease(fileURLToPath(import.meta.url));
+    // The release digest already covers these modules' bytes, so an installed
+    // release needs no separate file list to be exact.
+    if (running !== null)
+        return running.manifest.packageDigest.slice(0, 32);
+    const hash = createHash("sha256");
+    for (const module of ENDPOINT_CHECKOUT_MODULES) {
+        // An unreadable module is a broken installation, not a reason to fall back
+        // to an identity that would silently match a different build.
+        hash.update(module).update("\0").update(readFileSync(new URL(module, import.meta.url))).update("\0");
+    }
+    return `checkout-${hash.digest("hex").slice(0, 23)}`;
+}
+const ENDPOINT_GENERATION = resolveEndpointGeneration();
+/**
+ * Built-in Endpoint identity under the existing ImplementationRef contract.
+ * Uses the adopted release/checkout identity; matching it does not by itself
+ * prove that the Provider can recover its native Session.
+ */
+export function builtinAgentEndpointImplementation(adapterId) {
+    // Every catalogued adapter has a managed Endpoint. Re-listing the adapter
+    // names here would let the two lists drift, so the catalog is the only source.
+    if (!isAgentAdapterId(adapterId)) {
+        throw new Error(`No managed Endpoint implementation for adapter: ${adapterId}.`);
+    }
+    return Object.freeze({
+        id: `yui.agent-endpoint.${adapterId}`,
+        generation: ENDPOINT_GENERATION
+    });
+}
+export function validateAgentEndpointImplementation(ref) {
+    if (ref === null || typeof ref !== "object"
+        || typeof ref.id !== "string" || !ref.id.trim() || ref.id.includes("\0")
+        || typeof ref.generation !== "string" || !ref.generation.trim() || ref.generation.includes("\0")) {
+        throw new Error("Session Endpoint implementation identity is invalid.");
+    }
+    return ref;
+}
+/** Missing old code is an explicit inability to resume, never a Provider fallback. */
+export function requireBuiltinAgentEndpointImplementation(adapterId, ref) {
+    validateAgentEndpointImplementation(ref);
+    const current = builtinAgentEndpointImplementation(adapterId);
+    if (ref.id !== current.id || ref.generation !== current.generation) {
+        throw new Error(`Session Endpoint ${ref.id}@${ref.generation} is unavailable; explicitly select a new Session.`);
+    }
+    return ref;
+}

package/dist/runtime/agentEndpointOwnership.js

@@ -0,0 +1,239 @@
+import { InstanceHost } from "../kernel/instanceHost.js";
+import { builtinAgentEndpointImplementation, requireBuiltinAgentEndpointImplementation } from "./agentEndpointIdentity.js";
+import { createAgentEndpointFactory } from "./agentEndpoint.js";
+/**
+ * Process-local ownership of the Endpoint implementation this Agent Host is
+ * executing. Reuses the one Instance Host primitive; it is not a second
+ * registry, a capability directory or a durable reference table. The Controller
+ * owns its own Host in its own process and never holds an Endpoint client, so
+ * the reference facts for a Session live where the Session actually runs.
+ *
+ * Only the running code can be attached here. Selecting between generations is
+ * the launch decision recorded in the durable Session; this owner proves the
+ * chosen generation is really held and really released.
+ */
+export function createAgentEndpointOwner(factory = createAgentEndpointFactory()) {
+    const host = new InstanceHost();
+    const attached = new Map();
+    const live = new Map();
+    const implementationFor = (adapterId) => {
+        const current = builtinAgentEndpointImplementation(adapterId);
+        const existing = attached.get(current.id);
+        if (existing !== undefined)
+            return existing;
+        // The disposer owns the opener, not the clients: a Session's client is
+        // terminated by that Session's detach. Dropping the opener stops a leaked
+        // reference from starting new work on a generation that is already gone.
+        const ref = host.attach(current, factory, [
+            () => { live.delete(current.id); }
+        ]);
+        attached.set(current.id, ref);
+        live.set(current.id, new Set());
+        return ref;
+    };
+    /**
+     * Hand the reference back only when the Session asked to end *and* it has no
+     * client running *and* no handshake in flight. A client that never proves exit
+     * keeps this hold, so the drain below reports a real dependency instead of an
+     * empty list; so does an opener that has not answered yet, whose client may
+     * still be about to attach.
+     */
+    const settle = async (holders, holder) => {
+        if (holder.settled || !holder.releaseRequested)
+            return;
+        if (holder.current !== undefined || holder.opening > 0)
+            return;
+        holder.settled = true;
+        holders.delete(holder);
+        await holder.handle.release();
+    };
+    /**
+     * Pin the implementation for one Session. A pinned reference from the durable
+     * Session must name this exact code; a mismatch is an explicit inability to
+     * resume, never a silent start on a different generation.
+     */
+    const pin = (adapterId, pinned) => {
+        if (pinned !== undefined)
+            requireBuiltinAgentEndpointImplementation(adapterId, pinned);
+        const ref = implementationFor(adapterId);
+        const handle = host.acquire(ref);
+        const holders = live.get(ref.id);
+        // One entry per Session hold, reporting the client it currently has. A
+        // Session may reattach a replacement client for the same conversation; that
+        // succession is one hold, not two, so a drain never double-counts it.
+        const holder = { handle, opening: 0, releaseRequested: false, settled: false };
+        holders.add(holder);
+        const track = async (opened) => {
+            // Counted before the handshake is awaited, so a stop that lands while the
+            // client is still coming up sees this Session as a real holder.
+            holder.opening += 1;
+            let result;
+            try {
+                result = await opened;
+            }
+            catch (error) {
+                // A handshake that failed owes nothing: no client attached, so the hold
+                // ends on the real dependency rather than waiting for an exit that can
+                // never come.
+                holder.opening -= 1;
+                void settle(holders, holder).catch(() => undefined);
+                throw error;
+            }
+            holder.current = result.session;
+            holder.opening -= 1;
+            // Only a resolved exit proves the client stopped. An exit that never
+            // settles, or that fails, leaves this hold in place on purpose: the drain
+            // must be able to say what is still running.
+            void result.session.waitForExit().then(() => {
+                if (holder.current !== result.session)
+                    return;
+                holder.current = undefined;
+                void settle(holders, holder).catch(() => undefined);
+            }, () => { });
+            // A stop may already have been requested while this handshake was in
+            // flight. The client is real and attached, so it enters the same controlled
+            // exit tracking instead of being handed back as an untracked leak: ask it to
+            // exit and let its proven exit release the hold.
+            if (holder.releaseRequested)
+                result.session.detach();
+            return result;
+        };
+        const start = (call) => {
+            // An acquired handle keeps its captured opener even after the generation is
+            // disposed, so a released lease must refuse to start new work rather than
+            // run on code the Session has already given up.
+            if (holder.releaseRequested) {
+                return Promise.reject(new Error("Session Endpoint lease is released; it cannot start new work."));
+            }
+            return track(call(handle.value));
+        };
+        return Object.freeze({
+            implementation: handle.implementation,
+            open: (payload) => start((value) => value.open(payload)),
+            resume: (payload) => start((value) => value.resume(payload)),
+            release: async () => {
+                // Idempotent, and never blocking: a client that has not exited keeps the
+                // reference, and `stop` is what bounds and reports that wait. A hold that
+                // never opened a client (a failed start) owes nothing and settles here.
+                holder.releaseRequested = true;
+                await settle(holders, holder);
+            }
+        });
+    };
+    /** Actual reference and request records, never a status label. */
+    const inspectImplementation = (implementationId, waited) => {
+        const instances = host.inspect(implementationId);
+        const references = instances.reduce((total, instance) => total + instance.references, 0);
+        const holders = [...live.get(implementationId) ?? []];
+        const opening = holders.reduce((total, holder) => total + holder.opening, 0);
+        const sessions = holders.flatMap((holder) => {
+            const endpoint = holder.current;
+            // A hold between clients has nothing attached to report. Its hold is
+            // still counted in `references`, so it cannot be mistaken for quiescence.
+            if (endpoint === undefined)
+                return [];
+            const state = endpoint.inspect();
+            return [Object.freeze({
+                    nativeSessionId: endpoint.nativeSessionId,
+                    processInstanceId: endpoint.processInstanceId,
+                    attachment: state.attachment,
+                    cancellation: state.cancellation,
+                    resources: state.resources,
+                    releaseAwaitingExit: holder.releaseRequested,
+                    pending: Object.freeze(state.submissions
+                        .filter((submission) => submission.disposition.status === "pending"
+                        || submission.disposition.status === "unknown")
+                        .map((submission) => Object.freeze({
+                        attemptId: submission.attemptId,
+                        inputRef: submission.inputRef,
+                        status: submission.disposition.status
+                    })))
+                })];
+        });
+        return Object.freeze({
+            // Quiescent means nothing holds the implementation, no handshake is still
+            // in flight, and no owned client is still attached. Holds are dropped by
+            // proven exit, so an unreleased Session, an opening client or a client that
+            // never exited keeps this false.
+            quiescent: references === 0
+                && opening === 0
+                && sessions.every((session) => session.attachment === "exited" && session.pending.length === 0),
+            references,
+            opening,
+            waitedMs: waited.waitedMs,
+            timedOut: waited.timedOut,
+            sessions: Object.freeze(sessions)
+        });
+    };
+    const inspectWith = (adapterId, waited) => inspectImplementation(builtinAgentEndpointImplementation(adapterId).id, waited);
+    const inspect = (adapterId) => inspectWith(adapterId, { waitedMs: 0, timedOut: false });
+    /**
+     * Wait a bounded time for one already-detached drain, and report whether the
+     * bound ran out. The timer keeps the process alive for the window, or a caller
+     * with nothing else pending would exit before reporting what is still in use,
+     * and is cleared as soon as the drain settles so a released implementation
+     * never delays shutdown until the deadline.
+     */
+    const awaitDrained = async (drained, timeoutMs) => {
+        const startedAt = Date.now();
+        let timedOut = false;
+        if (timeoutMs > 0) {
+            let expire;
+            try {
+                timedOut = !await Promise.race([
+                    drained,
+                    new Promise((resolve) => { expire = setTimeout(() => resolve(false), timeoutMs); })
+                ]);
+            }
+            finally {
+                if (expire !== undefined)
+                    clearTimeout(expire);
+            }
+        }
+        else {
+            await Promise.resolve();
+        }
+        return Object.freeze({ waitedMs: Date.now() - startedAt, timedOut });
+    };
+    /**
+     * Ordinary stop: no new independent acquisition, while an already-acquired
+     * Session ends bounded. Resolves with the drain facts once every reference is
+     * released, or with what is still in use when the wait runs out.
+     */
+    const stop = async (adapterId, timeoutMs = 0) => {
+        const ref = attached.get(builtinAgentEndpointImplementation(adapterId).id);
+        if (ref === undefined) {
+            return Object.freeze({
+                quiescent: true, references: 0, opening: 0, waitedMs: 0, timedOut: false, sessions: []
+            });
+        }
+        // A disposer failure still ends acquisition; the drain facts below, not the
+        // settle reason, decide whether this is actually quiescent.
+        const drained = host.detach(ref).then(() => true, () => true);
+        return inspectWith(adapterId, await awaitDrained(drained, timeoutMs));
+    };
+    /**
+     * Final cleanup, bounded by construction. Every attached implementation is
+     * detached so nothing can acquire again, and the wait for their drains shares
+     * one deadline. `InstanceHost.close()` resolves only after every reference is
+     * handed back, which a client that never proves exit will never do; awaiting it
+     * here would block the Host's own shutdown after a bounded `stop` already
+     * reported that dependency, leaving the control socket unclosed.
+     *
+     * So this returns on the deadline and says what is still held, rather than
+     * releasing a reference it cannot prove or killing a client it does not own.
+     * The still-live implementations stay detached and undisposed on purpose: their
+     * facts remain readable, and the caller decides what to do about them.
+     */
+    const close = async (timeoutMs = 0) => {
+        const drains = [...attached.values()].map((ref) => Object.freeze({
+            implementationId: ref.id,
+            // Detaching cannot throw here: these refs are exactly what was attached,
+            // and detach is idempotent for an already-detached instance.
+            drained: host.detach(ref).then(() => true, () => true)
+        }));
+        const waited = await awaitDrained(Promise.all(drains.map((entry) => entry.drained)).then(() => true, () => true), timeoutMs);
+        return Object.freeze(drains.map((entry) => inspectImplementation(entry.implementationId, waited)));
+    };
+    return Object.freeze({ pin, stop, inspect, close });
+}

package/dist/runtime/agentError.js

@@ -69,8 +69,6 @@ export function providerDeliveryFailureFacts(failure) {
         ...(failure.errorName === undefined ? {} : { errorName: failure.errorName }),
         ...(failure.causeName === undefined ? {} : { causeName: failure.causeName }),
         ...(failure.hostState === undefined ? {} : { hostState: failure.hostState }),
-        ...(failure.expectedRuntimeGenerationId === undefined ? {} : { expectedRuntimeGenerationId: failure.expectedRuntimeGenerationId }),
-        ...(failure.observedRuntimeGenerationId === undefined ? {} : { observedRuntimeGenerationId: failure.observedRuntimeGenerationId }),
         ...(failure.attemptId === undefined ? {} : { attemptId: failure.attemptId })
     };
 }
@@ -111,7 +109,7 @@ function errorMessageText(error) {
     return String(error ?? "unknown error");
 }
 /**
- * Renders a delivery failure as one readable line for a Turn summary. The
+ * Renders a delivery failure as one readable line for a AgentRun summary. The
  * complete record stays available on `runtime.agent-error`; this is the
  * bounded projection, never a replacement for the original cause.
  */
@@ -126,12 +124,6 @@ export function formatProviderDeliveryFailure(failure) {
         fields.push(`error=${failure.errorName}`);
     if (failure.causeName !== undefined)
         fields.push(`cause=${failure.causeName}`);
-    if (failure.expectedRuntimeGenerationId !== undefined) {
-        fields.push(`expectedGeneration=${failure.expectedRuntimeGenerationId}`);
-    }
-    if (failure.observedRuntimeGenerationId !== undefined) {
-        fields.push(`observedGeneration=${failure.observedRuntimeGenerationId}`);
-    }
     if (failure.attemptId !== undefined)
         fields.push(`attemptId=${failure.attemptId}`);
     if (failure.registrationDisposition !== undefined) {
@@ -225,7 +217,7 @@ function rawPayloadText(value) {
     try {
         const seen = new WeakSet();
         const serialized = JSON.stringify(value, (key, member) => {
-            // Turn input is the Agent's prompt: Task context, quoted files, whatever
+            // AgentRun input is the Agent's prompt: Task context, quoted files, whatever
             // the Role was told. It is not a failure fact, and it reaches the same
             // durable, publicly-readable record as the rest of this payload. A
             // transport client that echoes its own request into the thrown error