@tea-agent/loop-agent 0.9.0 → 0.10.0-alpha.0

package/dist/worker/loop-agent/loop-agent-client.js

@@ -1,11 +1,55 @@
 import { spawn } from "node:child_process";
-import { appendFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { computeBinarySha256, computePackageFingerprint, findPackageRoot, isJavaScriptScript, readPackageName, readPackageVersion, resolveBinPaths, resolveCmdShim, } from "../../shared/package-metadata.js";
 import { parseCommandJson } from "./parse-json.js";
 export const DEFAULT_WORKER_COMMAND_TIMEOUT_MS = 120_000;
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 15_000;
+export const LOOP_AGENT_PACKAGE_NAME = "@tea-agent/loop-agent";
 const MAX_BUFFERED_OUTPUT_BYTES = 64 * 1024;
+/**
+ * Bind evidence supplied by an orchestration layer to the identity exposed by
+ * the client that will actually launch commands. When the client exposes an
+ * identity, it is authoritative; observational fields such as reportedVersion
+ * must come from the real preflight probe rather than caller-supplied evidence.
+ */
+export function resolveControllerIdentity(client, provided) {
+    const actual = client?.getIdentity?.();
+    if (actual && provided && !controllerIdentitiesMatch(actual, provided)) {
+        throw new Error("controller identity: provided evidence does not match the command client's pinned identity");
+    }
+    return actual ?? provided;
+}
+export function controllerIdentitiesMatch(left, right) {
+    return Boolean(left && right && identityAnchor(left) === identityAnchor(right));
+}
+/** Pure in-memory expectation gate. It performs no command or filesystem write. */
+export function controllerIdentityExpectationFailure(identity, expectation) {
+    if (!expectation)
+        return undefined;
+    if (!identity) {
+        return {
+            code: "identity-unavailable",
+            message: "controller identity expectation was set but no pinned identity is available",
+        };
+    }
+    if (expectation.expectedVersion
+        && identity.packageVersion !== expectation.expectedVersion) {
+        return {
+            code: "expected-version-mismatch",
+            message: `expected controller version ${expectation.expectedVersion}, got package version ${identity.packageVersion}`,
+        };
+    }
+    if (expectation.expectedFingerprint
+        && identity.packageFingerprint.value !== expectation.expectedFingerprint) {
+        return {
+            code: "identity-fingerprint-mismatch",
+            message: `expected controller fingerprint ${expectation.expectedFingerprint}, got ${identity.packageFingerprint.value}`,
+        };
+    }
+    return undefined;
+}
 export class LoopAgentClient {
     loopAgentBin;
     baseArgs;
@@ -13,6 +57,10 @@ export class LoopAgentClient {
     defaultTimeoutMs;
     heartbeatIntervalMs;
     env;
+    resolutionInputs;
+    identityRequired;
+    _identity;
+    _identityResolved = false;
     constructor(options) {
         this.loopAgentBin = options.loopAgentBin;
         this.baseArgs = options.baseArgs ?? [];
@@ -22,14 +70,136 @@ export class LoopAgentClient {
         this.heartbeatIntervalMs =
             options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
         this.env = options.env;
+        this.resolutionInputs = options.resolutionInputs;
+        this.identityRequired = options.resolveIdentity === true;
+        if (this.identityRequired)
+            this.resolveIdentity();
+    }
+    /**
+     * Resolve and freeze the controller identity.
+     */
+    resolveIdentity() {
+        if (this._identityResolved) {
+            if (!this._identity) {
+                throw new Error("controller identity: required identity resolution did not produce an identity");
+            }
+            return this._identity;
+        }
+        const resolvedAt = new Date().toISOString();
+        const resolved = resolveBinPaths(this.loopAgentBin, resolvedAt, this.resolutionInputs);
+        // Detect npm Windows .cmd shim and resolve to the actual JS script
+        let actualEntry = resolved.realEntry;
+        const isWin = this.resolutionInputs?.platform === "win32" || process.platform === "win32";
+        if (isWin) {
+            const lower = actualEntry.toLowerCase();
+            if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
+                const resolvedScript = resolveCmdShim(actualEntry);
+                if (resolvedScript) {
+                    actualEntry = resolvedScript;
+                }
+                else {
+                    throw new Error(`controller identity: cannot resolve npm .cmd shim: ${resolved.entry}`);
+                }
+            }
+        }
+        // Detect "running from source" pattern: loopAgentBin is a Node
+        // executable and baseArgs points to a script. In this case,
+        // actualEntry must be the script, not the Node binary.
+        const sourceScript = findSourceScript(this.baseArgs, this.resolutionInputs?.cwd ?? process.cwd());
+        if (sourceScript) {
+            actualEntry = sourceScript.path;
+        }
+        // Validate the entry file is readable
+        try {
+            const s = statSync(actualEntry);
+            if (!s.isFile())
+                throw new Error(`not a file: ${actualEntry}`);
+        }
+        catch {
+            throw new Error(`controller identity: bin entry is not readable: ${actualEntry}`);
+        }
+        const packageRoot = findPackageRoot(path.dirname(actualEntry));
+        if (!packageRoot) {
+            throw new Error(`controller identity: cannot locate package root for ${actualEntry}`);
+        }
+        const packageName = readPackageName(packageRoot);
+        if (!packageName) {
+            throw new Error(`controller identity: package.json at ${packageRoot} is missing a "name" field`);
+        }
+        if (packageName !== LOOP_AGENT_PACKAGE_NAME) {
+            throw new Error(`controller identity: unexpected package name ${JSON.stringify(packageName)} at ${packageRoot}; expected ${JSON.stringify(LOOP_AGENT_PACKAGE_NAME)}`);
+        }
+        const pkgVersion = readPackageVersion(packageRoot);
+        if (!pkgVersion) {
+            throw new Error(`controller identity: package.json at ${packageRoot} is missing a "version" field`);
+        }
+        const binarySha256 = computeBinarySha256(actualEntry);
+        if (!binarySha256) {
+            throw new Error(`controller identity: cannot read binary for hashing: ${actualEntry}`);
+        }
+        // Determine launch command and argsPrefix
+        let launchCommand;
+        let launchArgsPrefix;
+        if (sourceScript) {
+            launchCommand = resolveNodeBinary(this.loopAgentBin, resolvedAt, this.resolutionInputs);
+            launchArgsPrefix = [...this.baseArgs];
+            launchArgsPrefix[sourceScript.index] = sourceScript.path;
+        }
+        else if (isJavaScriptScript(actualEntry)) {
+            launchCommand = frozenNodeExecutable();
+            launchArgsPrefix = [actualEntry, ...this.baseArgs];
+        }
+        else {
+            launchCommand = actualEntry;
+            launchArgsPrefix = [...this.baseArgs];
+        }
+        const identity = {
+            schemaVersion: 1,
+            packageName,
+            binName: path.basename(actualEntry),
+            requested: this.loopAgentBin,
+            entry: resolved.entry,
+            realEntry: actualEntry,
+            launch: { command: launchCommand, argsPrefix: launchArgsPrefix },
+            binarySha256,
+            packageRoot,
+            packageVersion: pkgVersion,
+            packageFingerprint: computePackageFingerprint(packageRoot),
+            resolvedAt,
+        };
+        this._identity = identity;
+        this._identityResolved = true;
+        return identity;
+    }
+    getIdentity() {
+        return this._identity;
+    }
+    observeReportedVersion(reportedVersion) {
+        if (!this._identity) {
+            throw new Error("controller identity: cannot record a reported version without a pinned identity");
+        }
+        if (reportedVersion !== this._identity.packageVersion) {
+            throw new Error(`controller identity: reported version ${reportedVersion} does not match package version ${this._identity.packageVersion}`);
+        }
+        this._identity = { ...this._identity, reportedVersion };
+        return this._identity;
     }
     async run(args, options) {
+        if (this._identity) {
+            assertControllerIdentityUnchangedBeforeSpawn(this._identity);
+            const launch = this._identity.launch;
+            const fullArgs = [...launch.argsPrefix, ...args];
+            return this.runCommand(launch.command, fullArgs, args, options, () => assertControllerIdentityUnchangedBeforeSpawn(this._identity));
+        }
+        if (this.identityRequired || this._identityResolved) {
+            throw new Error("controller identity: pinned launch is unavailable");
+        }
         return this.runCommand(this.loopAgentBin, [...this.baseArgs, ...args], args, options);
     }
     async runExternal(command, args, options) {
         return this.runCommand(command, args, args, options);
     }
-    async runCommand(command, commandArgs, resultArgs, options) {
+    async runCommand(command, commandArgs, resultArgs, options, beforeSpawn) {
         const startedAt = Date.now();
         const artifactDir = path.join(this.artifactRoot, sanitizeName(options.artifactName));
         await mkdir(artifactDir, { recursive: true });
@@ -42,14 +212,13 @@ export class LoopAgentClient {
             cwd: options.cwd,
             timeoutMs: options.timeoutMs ?? this.defaultTimeoutMs,
             env: { ...process.env, ...this.env, ...options.env },
-            stdoutPath,
-            stderrPath,
-            resultPath,
+            stdoutPath, stderrPath, resultPath,
             heartbeatIntervalMs: this.heartbeatIntervalMs,
             onSpawn: options.onSpawn,
             onStdout: options.onStdout,
             onStderr: options.onStderr,
             onHeartbeat: options.onHeartbeat,
+            beforeSpawn,
         });
         const result = {
             ok: exitCode === 0 && !timedOut,
@@ -58,19 +227,10 @@ export class LoopAgentClient {
             cwd: options.cwd,
             durationMs: Date.now() - startedAt,
             exitCode,
-            stdout,
-            stdoutBytes,
-            stdoutTruncated,
-            stderr,
-            stderrBytes,
-            stderrTruncated,
+            stdout, stdoutBytes, stdoutTruncated,
+            stderr, stderrBytes, stderrTruncated,
             timedOut,
-            artifacts: {
-                dir: artifactDir,
-                stdoutPath,
-                stderrPath,
-                resultPath,
-            },
+            artifacts: { dir: artifactDir, stdoutPath, stderrPath, resultPath },
         };
         if (options.expectJson) {
             const jsonSource = stdoutTruncated
@@ -89,10 +249,104 @@ export class LoopAgentClient {
         return result;
     }
 }
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function assertControllerIdentityUnchangedBeforeSpawn(identity) {
+    const currentPackageRoot = findPackageRoot(path.dirname(identity.realEntry));
+    if (currentPackageRoot !== identity.packageRoot) {
+        throw controllerIdentityDriftError(`package root changed from ${JSON.stringify(identity.packageRoot)} to ${JSON.stringify(currentPackageRoot)}`);
+    }
+    const currentPackageName = readPackageName(identity.packageRoot);
+    if (currentPackageName !== identity.packageName) {
+        throw controllerIdentityDriftError(`package name changed from ${JSON.stringify(identity.packageName)} to ${JSON.stringify(currentPackageName)}`);
+    }
+    const currentPackageVersion = readPackageVersion(identity.packageRoot);
+    if (currentPackageVersion !== identity.packageVersion) {
+        throw controllerIdentityDriftError(`package version changed from ${JSON.stringify(identity.packageVersion)} to ${JSON.stringify(currentPackageVersion)}`);
+    }
+    const currentBinarySha256 = computeBinarySha256(identity.realEntry);
+    if (currentBinarySha256 !== identity.binarySha256) {
+        throw controllerIdentityDriftError(`entry binary sha256 changed from ${identity.binarySha256} to ${currentBinarySha256 ?? "unreadable"}`);
+    }
+    let currentPackageFingerprint;
+    try {
+        currentPackageFingerprint = computePackageFingerprint(identity.packageRoot);
+    }
+    catch (error) {
+        throw controllerIdentityDriftError(`package fingerprint cannot be recomputed: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+    if (currentPackageFingerprint.algorithm !== identity.packageFingerprint.algorithm
+        || currentPackageFingerprint.scopeVersion !== identity.packageFingerprint.scopeVersion
+        || JSON.stringify(currentPackageFingerprint.scope)
+            !== JSON.stringify(identity.packageFingerprint.scope)
+        || currentPackageFingerprint.value !== identity.packageFingerprint.value
+        || currentPackageFingerprint.fileCount !== identity.packageFingerprint.fileCount) {
+        throw controllerIdentityDriftError(`package fingerprint changed from ${identity.packageFingerprint.value} to ${currentPackageFingerprint.value}`);
+    }
+}
+function controllerIdentityDriftError(message, cause) {
+    return new Error(`controller identity changed before spawn: ${message}`, {
+        cause,
+    });
+}
+/**
+ * Detect whether loopAgentBin is a Node-like executable and baseArgs
+ * contains a script file. Returns the absolute script path, or undefined.
+ */
+function findSourceScript(baseArgs, cwd) {
+    if (baseArgs.length === 0)
+        return undefined;
+    // Look for the last .ts/.js/.mjs/.cjs file in baseArgs
+    let scriptIdx = -1;
+    for (let i = baseArgs.length - 1; i >= 0; i--) {
+        const ext = path.extname(baseArgs[i]).toLowerCase();
+        if (ext === ".ts" || ext === ".js" || ext === ".mjs" || ext === ".cjs") {
+            scriptIdx = i;
+            break;
+        }
+    }
+    if (scriptIdx < 0)
+        return undefined;
+    const scriptPath = path.resolve(cwd, baseArgs[scriptIdx]);
+    try {
+        const s = statSync(scriptPath);
+        if (s.isFile())
+            return { index: scriptIdx, path: realpathSync(scriptPath) };
+    }
+    catch {
+        // script not found
+    }
+    return undefined;
+}
+/**
+ * Resolve the Node binary to an absolute path.
+ */
+function resolveNodeBinary(loopAgentBin, resolvedAt, inputs) {
+    if (path.isAbsolute(loopAgentBin))
+        return realpathSync(loopAgentBin);
+    const resolved = resolveBinPaths(loopAgentBin, resolvedAt, inputs);
+    return resolved.realEntry;
+}
+function frozenNodeExecutable() {
+    try {
+        return realpathSync(process.execPath);
+    }
+    catch {
+        return process.execPath;
+    }
+}
 function spawnCommand(input) {
     return new Promise((resolve, reject) => {
         const startedAtMs = Date.now();
         const startedAt = new Date(startedAtMs).toISOString();
+        try {
+            input.beforeSpawn?.();
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
         const child = spawn(input.command, input.args, {
             cwd: input.cwd,
             env: input.env,
@@ -103,136 +357,85 @@ function spawnCommand(input) {
             writeFileSync(input.stdoutPath, "", "utf-8");
             writeFileSync(input.stderrPath, "", "utf-8");
         }
-        catch {
-            // best-effort: degrade to in-memory buffer only
-        }
-        invokeSpawnCallback(input.onSpawn, {
-            pid: child.pid,
-            startedAt,
-            artifactRefs: {
-                stdoutPath: input.stdoutPath,
-                stderrPath: input.stderrPath,
-                resultPath: input.resultPath,
-            },
-        });
+        catch { /* best-effort */ }
+        invokeSpawnCallback(input.onSpawn, { pid: child.pid, startedAt, artifactRefs: { stdoutPath: input.stdoutPath, stderrPath: input.stderrPath, resultPath: input.resultPath } });
         let stdout = createBoundedOutput();
         let stderr = createBoundedOutput();
         let timedOut = false;
-        const timeout = setTimeout(() => {
-            timedOut = true;
-            child.kill("SIGTERM");
-        }, input.timeoutMs);
+        const timeout = setTimeout(() => { timedOut = true; child.kill("SIGTERM"); }, input.timeoutMs);
         let heartbeatTimer;
         if (input.heartbeatIntervalMs > 0) {
-            heartbeatTimer = setInterval(() => {
-                invokeHeartbeatCallback(input.onHeartbeat, startedAtMs);
-            }, input.heartbeatIntervalMs);
-        }
-        const clearTimers = () => {
-            clearTimeout(timeout);
-            if (heartbeatTimer !== undefined) {
-                clearInterval(heartbeatTimer);
-                heartbeatTimer = undefined;
-            }
-        };
+            heartbeatTimer = setInterval(() => { invokeHeartbeatCallback(input.onHeartbeat, startedAtMs); }, input.heartbeatIntervalMs);
+        }
+        const clearTimers = () => { clearTimeout(timeout); if (heartbeatTimer !== undefined) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = undefined;
+        } };
         child.stdout.setEncoding("utf8");
         child.stderr.setEncoding("utf8");
-        child.stdout.on("data", (chunk) => {
-            stdout = appendBoundedOutput(stdout, chunk);
-            appendChunkBestEffort(input.stdoutPath, chunk);
-            invokeChunkCallback(input.onStdout, chunk);
-        });
-        child.stderr.on("data", (chunk) => {
-            stderr = appendBoundedOutput(stderr, chunk);
-            appendChunkBestEffort(input.stderrPath, chunk);
-            invokeChunkCallback(input.onStderr, chunk);
-        });
-        child.on("error", (error) => {
-            clearTimers();
-            reject(error);
-        });
+        child.stdout.on("data", (chunk) => { stdout = appendBoundedOutput(stdout, chunk); appendChunkBestEffort(input.stdoutPath, chunk); invokeChunkCallback(input.onStdout, chunk); });
+        child.stderr.on("data", (chunk) => { stderr = appendBoundedOutput(stderr, chunk); appendChunkBestEffort(input.stderrPath, chunk); invokeChunkCallback(input.onStderr, chunk); });
+        child.on("error", (error) => { clearTimers(); reject(error); });
         child.on("close", (exitCode) => {
             clearTimers();
-            resolve({
-                stdout: formatBoundedOutput(stdout),
-                stdoutBytes: stdout.bytes,
-                stdoutTruncated: stdout.truncated,
-                stderr: formatBoundedOutput(stderr),
-                stderrBytes: stderr.bytes,
-                stderrTruncated: stderr.truncated,
-                exitCode,
-                timedOut,
-            });
+            resolve({ stdout: formatBoundedOutput(stdout), stdoutBytes: stdout.bytes, stdoutTruncated: stdout.truncated, stderr: formatBoundedOutput(stderr), stderrBytes: stderr.bytes, stderrTruncated: stderr.truncated, exitCode, timedOut });
         });
     });
 }
-function createBoundedOutput() {
-    return { bytes: 0, text: "", truncated: false };
-}
+function createBoundedOutput() { return { bytes: 0, text: "", truncated: false }; }
 function appendBoundedOutput(current, chunk) {
     const bytes = current.bytes + Buffer.byteLength(chunk);
     const combined = current.text + chunk;
-    if (Buffer.byteLength(combined) <= MAX_BUFFERED_OUTPUT_BYTES) {
+    if (Buffer.byteLength(combined) <= MAX_BUFFERED_OUTPUT_BYTES)
         return { bytes, text: combined, truncated: current.truncated };
-    }
-    const tail = Buffer.from(combined)
-        .subarray(-MAX_BUFFERED_OUTPUT_BYTES)
-        .toString("utf-8")
-        .replace(/^\uFFFD/, "");
+    const tail = Buffer.from(combined).subarray(-MAX_BUFFERED_OUTPUT_BYTES).toString("utf-8").replace(/^\uFFFD/, "");
     return { bytes, text: tail, truncated: true };
 }
-function formatBoundedOutput(output) {
-    return output.truncated ? `${output.text}\n...[truncated]` : output.text;
+function formatBoundedOutput(output) { return output.truncated ? `${output.text}\n...[truncated]` : output.text; }
+async function readFullOutputArtifact(filePath, fallback) { try {
+    return await readFile(filePath, "utf-8");
 }
-async function readFullOutputArtifact(filePath, fallback) {
-    try {
-        return await readFile(filePath, "utf-8");
-    }
-    catch {
-        return fallback;
-    }
+catch {
+    return fallback;
+} }
+function appendChunkBestEffort(filePath, chunk) { try {
+    appendFileSync(filePath, chunk, "utf-8");
 }
-function appendChunkBestEffort(filePath, chunk) {
-    try {
-        appendFileSync(filePath, chunk, "utf-8");
-    }
-    catch {
-        // best-effort: degrade to in-memory buffer only
-    }
+catch { /* best-effort */ } }
+function invokeSpawnCallback(cb, info) { if (!cb)
+    return; try {
+    cb(info);
 }
-function invokeSpawnCallback(callback, info) {
-    if (!callback) {
-        return;
-    }
-    try {
-        callback(info);
-    }
-    catch (error) {
-        process.stderr.write(`LoopAgentClient onSpawn callback error: ${String(error)}\n`);
-    }
+catch (error) {
+    process.stderr.write(`LoopAgentClient onSpawn callback error: ${String(error)}\n`);
+} }
+function invokeChunkCallback(cb, chunk) { if (!cb)
+    return; try {
+    cb(chunk);
 }
-function invokeChunkCallback(callback, chunk) {
-    if (!callback) {
-        return;
-    }
-    try {
-        callback(chunk);
-    }
-    catch (error) {
-        process.stderr.write(`LoopAgentClient output callback error: ${String(error)}\n`);
-    }
-}
-function invokeHeartbeatCallback(callback, startedAtMs) {
-    if (!callback) {
-        return;
-    }
-    try {
-        callback({ at: new Date().toISOString(), elapsedMs: Date.now() - startedAtMs });
-    }
-    catch (error) {
-        process.stderr.write(`LoopAgentClient onHeartbeat callback error: ${String(error)}\n`);
-    }
+catch (error) {
+    process.stderr.write(`LoopAgentClient output callback error: ${String(error)}\n`);
+} }
+function invokeHeartbeatCallback(cb, startedAtMs) { if (!cb)
+    return; try {
+    cb({ at: new Date().toISOString(), elapsedMs: Date.now() - startedAtMs });
 }
-function sanitizeName(name) {
-    return name.replace(/[^a-zA-Z0-9._-]+/g, "-");
+catch (error) {
+    process.stderr.write(`LoopAgentClient onHeartbeat callback error: ${String(error)}\n`);
+} }
+function sanitizeName(name) { return name.replace(/[^a-zA-Z0-9._-]+/g, "-"); }
+function identityAnchor(identity) {
+    return JSON.stringify({
+        schemaVersion: identity.schemaVersion,
+        packageName: identity.packageName,
+        binName: identity.binName,
+        requested: identity.requested,
+        entry: identity.entry,
+        realEntry: identity.realEntry,
+        launch: identity.launch,
+        binarySha256: identity.binarySha256,
+        packageRoot: identity.packageRoot,
+        packageVersion: identity.packageVersion,
+        packageFingerprint: identity.packageFingerprint,
+    });
 }