@ouro.bot/cli 0.1.0-alpha.97 → 0.1.0-alpha.970

package/dist/senses/shepherd/herdr.js

@@ -0,0 +1,427 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HERDR_METADATA_SOURCE = void 0;
+exports.herdrRequest = herdrRequest;
+exports.createHerdrHost = createHerdrHost;
+const net = __importStar(require("node:net"));
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../../nerves/runtime");
+const cmux_1 = require("./cmux");
+const redact_1 = require("./redact");
+/**
+ * The Herdr host. Herdr detects every agent in its panes itself and publishes each change of its
+ * semantic state as `pane.agent_status_changed` (idle, working, blocked, done, unknown). A return is
+ * a pane leaving `working` for `idle`, `done` or `blocked` and still there after the grace period,
+ * keyed by Herdr's own `state_change_seq`. Herdr types a prompt with `agent.prompt` (bracketed paste
+ * then Enter) and shows Shepherd's status as the pane's state label.
+ */
+exports.HERDR_METADATA_SOURCE = "ouro.shepherd";
+const GRACE_MS = 3_000;
+const TIMEOUT_MS = 10_000;
+const RETURN_STATES = new Set(["idle", "done", "blocked"]);
+const RECONNECT_DELAYS_MS = [1_000, 2_000, 5_000, 10_000, 30_000];
+const HERDR_KEYS = { enter: "enter", escape: "esc", up: "up", down: "down", tab: "tab", "ctrl-c": "ctrl+c", 1: "1", 2: "2", 3: "3", 4: "4", 5: "5", 6: "6", 7: "7", 8: "8", 9: "9", y: "y", n: "n" };
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/** One NDJSON connection: each line Herdr sends goes to `onLine` until the socket closes. */
+function connectLines(socketPath, onLine, onClose) {
+    const socket = net.createConnection(socketPath);
+    let buffer = "";
+    let failure;
+    socket.setEncoding("utf-8");
+    socket.on("data", (chunk) => {
+        buffer += chunk;
+        let newline = buffer.indexOf("\n");
+        while (newline >= 0) {
+            const raw = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            newline = buffer.indexOf("\n");
+            try {
+                const parsed = JSON.parse(raw);
+                if (isRecord(parsed))
+                    onLine(parsed);
+            }
+            catch {
+                // A line that is not JSON is ignored.
+            }
+        }
+    });
+    socket.on("error", (error) => { failure = error; });
+    socket.on("close", () => onClose(failure));
+    return { send: (line) => socket.write(`${JSON.stringify(line)}\n`), close: () => socket.destroy() };
+}
+let requestCount = 0;
+/** One request on its own connection. */
+function herdrRequest(socketPath, method, params, timeoutMs = TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const id = `ouro_${++requestCount}`;
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            connection.close();
+            fn();
+        };
+        const timer = setTimeout(() => settle(() => reject(new Error(`herdr ${method} timed out`))), timeoutMs);
+        const connection = connectLines(socketPath, (line) => {
+            if (line.id !== id)
+                return;
+            const error = isRecord(line.error) ? line.error : null;
+            settle(() => error ? reject(new Error(`herdr ${method}: ${str(error.message) ?? str(error.code) ?? "error"}`)) : resolve(isRecord(line.result) ? line.result : {}));
+        }, (error) => settle(() => reject(new Error(`herdr ${method}: ${error?.message ?? "connection closed"}`))));
+        connection.send({ id, method, params });
+    });
+}
+function createHerdrHost(connection, options = {}) {
+    const schedule = options.schedule ?? cmux_1.realSchedule;
+    const call = (method, params) => herdrRequest(connection.socketPath, method, params);
+    async function panes(strict = false) {
+        const result = await call("pane.list", {});
+        if (strict) {
+            if (!Array.isArray(result.panes))
+                throw new Error("invalid Herdr terminal inventory");
+            const seen = new Set();
+            for (const pane of result.panes) {
+                if (!isRecord(pane) || typeof pane.pane_id !== "string" || !pane.pane_id.trim() || seen.has(pane.pane_id)) {
+                    throw new Error("invalid Herdr terminal inventory identity");
+                }
+                seen.add(pane.pane_id);
+            }
+        }
+        return Array.isArray(result.panes) ? result.panes.filter(isRecord) : [];
+    }
+    return {
+        name: "herdr",
+        async retirementInventory() {
+            return (await panes(true)).map(pane => pane.pane_id);
+        },
+        async list() {
+            return (await panes()).map((pane) => ({
+                id: str(pane.pane_id) ?? "",
+                ref: str(pane.pane_id) ?? "",
+                workspace: str(pane.workspace_id),
+                title: str(pane.title) ?? str(pane.terminal_title_stripped) ?? str(pane.label) ?? "",
+                agent: str(pane.agent),
+                focused: pane.focused === true,
+            }));
+        },
+        async read(sessionId) {
+            // The visible screen only: reading recent scrollback makes Herdr scroll the agent's UI.
+            const result = await call("pane.read", { pane_id: sessionId, source: "visible", strip_ansi: true });
+            const read = isRecord(result.read) ? result.read : {};
+            return typeof read.text === "string" ? read.text : "";
+        },
+        async inspect(sessionId) {
+            const pane = (await panes()).find(pane => pane.pane_id === sessionId);
+            if (!pane)
+                throw new Error("Herdr inspection pane disappeared");
+            const result = await call("agent.get", { target: sessionId });
+            const agent = isRecord(result.agent) ? result.agent : {};
+            if (agent.pane_id !== sessionId)
+                throw new Error("Herdr inspection agent target mismatch");
+            const response = await call("pane.read", { pane_id: sessionId, source: "visible", strip_ansi: true });
+            const read = isRecord(response.read) ? response.read : {};
+            if (read.pane_id !== sessionId || typeof read.text !== "string")
+                throw new Error("Herdr inspection read target mismatch");
+            return {
+                session: {
+                    id: sessionId, ref: sessionId, workspace: str(pane.workspace_id),
+                    title: str(pane.title) ?? str(pane.terminal_title_stripped) ?? str(pane.label) ?? "",
+                    agent: str(agent.agent), cwd: str(agent.foreground_cwd) ?? str(agent.cwd),
+                    focused: pane.focused === true,
+                },
+                // Herdr's semantic states do not establish a process start or composer.
+                instance: null, screen: (0, redact_1.redactSecrets)(read.text), screenFingerprint: (0, node_crypto_1.createHash)("sha256").update(read.text).digest("hex"), composer: "unknown",
+                activity: agent.agent_status === "working" ? "working" : RETURN_STATES.has(str(agent.agent_status) ?? "") ? "idle" : "unknown",
+                backgroundWork: null,
+            };
+        },
+        async promptIfUnchanged() {
+            return { state: "not_sent", reason: "Herdr cannot verify process-start identity and empty composer" };
+        },
+        async prompt(sessionId, line) {
+            // Herdr pastes the text as one block and then presses Enter; a blocked agent is refused without input.
+            await call("agent.prompt", { target: sessionId, text: line });
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_herdr_prompted", message: "typed a line into a Herdr pane", meta: { chars: line.length } });
+        },
+        async key(sessionId, key) {
+            await call("agent.send_keys", { target: sessionId, keys: [HERDR_KEYS[key]] });
+        },
+        async signal(sessionId, status, notification) {
+            await call("pane.report_metadata", status
+                ? { pane_id: sessionId, source: exports.HERDR_METADATA_SOURCE, state_labels: { idle: status, done: status, blocked: status }, tokens: { ouro: status } }
+                : { pane_id: sessionId, source: exports.HERDR_METADATA_SOURCE, clear_state_labels: true, tokens: { ouro: null } });
+            if (notification)
+                await call("notification.show", { title: notification.title, body: notification.body });
+        },
+        watch(handlers) {
+            let closed = false;
+            let attempt = 0;
+            let stream = null;
+            let cancelReconnect = null;
+            let refresh = false;
+            const status = new Map();
+            const pending = new Map();
+            const inventory = new Map();
+            let cancelObservation = null;
+            let inventoryGeneration = 0;
+            const publishObservation = (error) => {
+                handlers.observed?.({ at: Date.now(), sessions: [...inventory.values()], ...(error ? { error } : {}) });
+            };
+            const inventoryRow = (pane) => {
+                const id = str(pane.pane_id);
+                if (!id)
+                    return;
+                const state = str(pane.agent_status);
+                inventory.set(id, {
+                    session: { id, ref: id, workspace: str(pane.workspace_id),
+                        title: str(pane.title) ?? str(pane.terminal_title_stripped) ?? str(pane.label) ?? "",
+                        agent: str(pane.agent), cwd: str(pane.foreground_cwd) ?? str(pane.cwd), focused: pane.focused === true },
+                    activity: state === "working" ? "working" : RETURN_STATES.has(state ?? "") ? "idle" : "unknown",
+                    observedAt: Date.now(),
+                });
+            };
+            const replaceInventory = (current) => {
+                const ids = new Set(current.flatMap(pane => str(pane.pane_id) ?? []));
+                for (const id of inventory.keys())
+                    if (!ids.has(id))
+                        inventory.delete(id);
+                for (const pane of current)
+                    inventoryRow(pane);
+                publishObservation();
+            };
+            // Read-only refresh belongs to this host watcher, never to the judge or the browser.
+            const refreshObservation = async () => {
+                cancelObservation = null;
+                const generation = ++inventoryGeneration;
+                try {
+                    const current = await panes(true);
+                    if (!closed && generation === inventoryGeneration)
+                        replaceInventory(current);
+                }
+                catch {
+                    if (!closed && generation === inventoryGeneration)
+                        publishObservation("host_unavailable");
+                }
+                if (!closed && generation === inventoryGeneration && !cancelObservation)
+                    cancelObservation = schedule(() => void refreshObservation(), 5_000);
+            };
+            const cancelPending = (paneId) => {
+                pending.get(paneId)?.();
+                pending.delete(paneId);
+            };
+            /** A return only if the pane is still out of `working` after the grace period, keyed by Herdr's own sequence. */
+            const settled = (paneId) => {
+                cancelPending(paneId);
+                pending.set(paneId, schedule(() => {
+                    pending.delete(paneId);
+                    void call("agent.get", { target: paneId }).then((result) => {
+                        const agent = isRecord(result.agent) ? result.agent : {};
+                        if (!RETURN_STATES.has(str(agent.agent_status) ?? ""))
+                            return;
+                        const seq = typeof agent.state_change_seq === "number" ? agent.state_change_seq : null;
+                        handlers.returned({
+                            sessionId: paneId,
+                            transitionId: `herdr:${paneId}:${seq ?? `t${Date.now()}`}`,
+                            agent: str(agent.agent),
+                            cwd: str(agent.foreground_cwd) ?? str(agent.cwd),
+                            lastBody: null,
+                            // Herdr's states do not say whether background work is running; the judge reads the screen.
+                            backgroundWork: null,
+                        });
+                    }, (error) => {
+                        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_herdr_read_error", message: "could not read a Herdr agent after it stopped", meta: { error: error.message } });
+                    });
+                }, GRACE_MS));
+            };
+            /**
+             * The cache keeps each pane's last known state; `unknown` (a passing detection gap) changes nothing, so working, unknown,
+             * idle still counts as working to idle.
+             */
+            const observed = (paneId, next) => {
+                if (next === "unknown")
+                    return;
+                const previous = status.get(paneId);
+                status.set(paneId, next);
+                if (next === "working")
+                    cancelPending(paneId);
+                else if (previous === "working" && RETURN_STATES.has(next))
+                    settled(paneId);
+            };
+            const onEvent = (line) => {
+                // Herdr names events `pane.focused` in subscriptions and `pane_focused` on the wire; both are accepted.
+                const name = (str(line.event) ?? "").replace(".", "_");
+                const data = isRecord(line.data) ? line.data : {};
+                if (name === "pane_moved") {
+                    // A moved pane can get a new id: carry its state over and subscribe again under the new id.
+                    const from = str(data.previous_pane_id);
+                    const to = isRecord(data.pane) ? str(data.pane.pane_id) : null;
+                    if (from && to && from !== to) {
+                        cancelPending(from);
+                        const known = status.get(from);
+                        status.delete(from);
+                        if (known)
+                            status.set(to, known);
+                    }
+                    refresh = true;
+                    stream?.close();
+                    return;
+                }
+                // Agent-status subscriptions name each pane, so a new or closed pane needs a new subscription. Herdr sends a new
+                // pane as `data.pane` with no top-level `pane_id`; the fresh pane list after resubscribing picks it up.
+                if (name === "pane_created") {
+                    refresh = true;
+                    stream?.close();
+                    return;
+                }
+                const paneId = str(data.pane_id);
+                if (!paneId)
+                    return;
+                if (name === "pane_focused")
+                    return handlers.focused(paneId);
+                if (name === "pane_closed") {
+                    cancelPending(paneId);
+                    status.delete(paneId);
+                    inventory.delete(paneId);
+                    refresh = true;
+                    stream?.close();
+                    return;
+                }
+                if (name !== "pane_agent_status_changed")
+                    return;
+                const row = inventory.get(paneId);
+                if (row) {
+                    const next = str(data.agent_status);
+                    row.activity = next === "working" ? "working" : RETURN_STATES.has(next ?? "") ? "idle" : "unknown";
+                    row.observedAt = Date.now();
+                    publishObservation();
+                    if (closed)
+                        return;
+                }
+                observed(paneId, str(data.agent_status) ?? "unknown");
+            };
+            const reconnect = (error) => {
+                stream = null;
+                if (closed)
+                    return;
+                if (refresh) {
+                    refresh = false;
+                    return void subscribe();
+                }
+                const delay = RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)];
+                attempt += 1;
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_herdr_closed", message: "Herdr event subscription closed; resubscribing", meta: { delay, error: error?.message ?? null } });
+                publishObservation("host_unavailable");
+                if (closed)
+                    return;
+                cancelReconnect = schedule(() => void subscribe(), delay);
+            };
+            const subscribe = async () => {
+                cancelReconnect = null;
+                let current;
+                const generation = ++inventoryGeneration;
+                try {
+                    current = await panes(!!handlers.observed);
+                }
+                catch (error) {
+                    return reconnect(error);
+                }
+                if (closed)
+                    return;
+                // Status changes while unsubscribed are not replayed: the fresh list replaces the cache, and a pane that stopped
+                // working in the gap is handled as if its event had arrived.
+                const ids = new Set(current.flatMap((pane) => str(pane.pane_id) ?? []));
+                for (const id of [...status.keys()]) {
+                    if (ids.has(id))
+                        continue;
+                    status.delete(id);
+                    cancelPending(id);
+                }
+                for (const pane of current) {
+                    const id = str(pane.pane_id);
+                    if (!id)
+                        continue;
+                    const next = str(pane.agent_status) ?? "unknown";
+                    if (status.has(id))
+                        observed(id, next);
+                    else if (next !== "unknown")
+                        status.set(id, next);
+                }
+                if (generation === inventoryGeneration)
+                    replaceInventory(current);
+                if (closed)
+                    return;
+                if (handlers.observed && !cancelObservation)
+                    cancelObservation = schedule(() => void refreshObservation(), 5_000);
+                const subscriptions = [
+                    { type: "pane.created" }, { type: "pane.closed" }, { type: "pane.focused" }, { type: "pane.moved" },
+                    ...current.flatMap((pane) => str(pane.pane_id) ? [{ type: "pane.agent_status_changed", pane_id: pane.pane_id }] : []),
+                ];
+                stream = connectLines(connection.socketPath, (line) => {
+                    if (closed)
+                        return;
+                    if (isRecord(line.result) && line.result.type === "subscription_started") {
+                        attempt = 0;
+                        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_herdr_connected", message: "Herdr event subscription started", meta: { panes: subscriptions.length - 4 } });
+                        return;
+                    }
+                    // `events_lost` or a rejected subscription closes the connection; the reconnect reads panes again.
+                    if (line.event !== undefined)
+                        onEvent(line);
+                }, reconnect);
+                stream.send({ id: "ouro_events", method: "events.subscribe", params: { subscriptions } });
+            };
+            void subscribe();
+            return {
+                close() {
+                    closed = true;
+                    inventoryGeneration += 1;
+                    cancelObservation?.();
+                    cancelReconnect?.();
+                    for (const cancel of pending.values())
+                        cancel();
+                    stream?.close();
+                },
+            };
+        },
+    };
+}

package/dist/senses/shepherd/host.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createShepherdHost = createShepherdHost;
+const runtime_1 = require("../../nerves/runtime");
+const client_1 = require("./client");
+const cmux_1 = require("./cmux");
+const copilot_app_1 = require("./copilot-app");
+const herdr_1 = require("./herdr");
+/** The host for this machine's connection. */
+function createShepherdHost(connection, options) {
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_host_created", message: "opened the Shepherd terminal host", meta: { host: connection.host } });
+    if (connection.host === "copilot-app")
+        return (0, copilot_app_1.createCopilotAppHost)(connection, { schedule: options.schedule, now: options.now });
+    return connection.host === "herdr"
+        ? (0, herdr_1.createHerdrHost)(connection, { schedule: options.schedule })
+        : (0, cmux_1.createCmuxHost)((0, client_1.createCmuxClient)(connection, { agentName: options.agentName }), { now: options.now, schedule: options.schedule });
+}

package/dist/senses/shepherd/human-decision-guard.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HUMAN_DECISION_PHRASES = void 0;
+exports.asksHumanToDecide = asksHumanToDecide;
+const runtime_1 = require("../../nerves/runtime");
+/**
+ * Phrases an agent uses when it hands a decision to the human by name: approving a design, signing off a delivery,
+ * or answering personally. A judge may read such a stop as premature ("offers options instead of choosing"), but
+ * Shepherd must never answer it on the human's behalf. The list is deliberately narrow: words like "choose" or
+ * "approve" on their own are ordinary agent chatter and stay with the judge.
+ */
+exports.HUMAN_DECISION_PHRASES = [
+    /\bapprove\s+(?:this|the)\s+(?:design|spec|plan)\b/i,
+    /\bsign[- ]?off\b/i,
+    /\baccept\s+or\s+send\s+back\b/i,
+    /\breply\s+here\s+yourself\b/i,
+    /\bplease\s+reply\s+yourself\b/i,
+    /\byour\s+call\b/i,
+    /\bonly\s+you\s+can\b/i,
+];
+/** Whether the agent's last words ask the human to decide or answer personally. */
+function asksHumanToDecide(text) {
+    const index = exports.HUMAN_DECISION_PHRASES.findIndex((phrase) => phrase.test(text));
+    if (index === -1)
+        return false;
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_human_decision_detected",
+        message: "the agent asked its human to decide", meta: { phrase: index } });
+    return true;
+}

package/dist/senses/shepherd/judge-evaluation-command.js

@@ -0,0 +1,183 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openShepherdJudgeEvaluationOutput = openShepherdJudgeEvaluationOutput;
+exports.loadConfiguredShepherdEvaluationJudge = loadConfiguredShepherdEvaluationJudge;
+exports.runShepherdJudgeEvaluationCommand = runShepherdJudgeEvaluationCommand;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../../nerves/runtime");
+const judge_1 = require("./judge");
+const judge_evaluation_1 = require("./judge-evaluation");
+const redact_1 = require("./redact");
+const shepherd_judge_corpus_v1_json_1 = __importDefault(require("./shepherd-judge-corpus-v1.json"));
+function openShepherdJudgeEvaluationOutput(file) {
+    const fd = fs.openSync(file, "wx", 0o600);
+    return {
+        write: report => {
+            const bytes = Buffer.from(JSON.stringify(report, null, 2) + "\n", "utf8");
+            let offset = 0;
+            while (offset < bytes.length) {
+                const written = fs.writeSync(fd, bytes, offset, bytes.length - offset, offset);
+                if (written === 0)
+                    throw new Error("Evaluation output write made no progress");
+                offset += written;
+            }
+            fs.ftruncateSync(fd, bytes.length);
+            fs.fsyncSync(fd);
+        },
+        close: () => fs.closeSync(fd),
+    };
+}
+async function loadConfiguredShepherdEvaluationJudge(agent) {
+    const { getAgentRoot } = await Promise.resolve().then(() => __importStar(require("../../heart/identity")));
+    const root = getAgentRoot(agent);
+    if (!fs.statSync(path.join(root, "agent.json")).isFile())
+        throw new Error("The selected agent needs an existing agent.json");
+    const { getProviderRuntime } = await Promise.resolve().then(() => __importStar(require("../../heart/core")));
+    const runtime = await getProviderRuntime("agent", { agentName: agent, agentRoot: root });
+    const metadata = JSON.parse(fs.readFileSync(path.resolve(__dirname, "../../../package.json"), "utf8"));
+    if (!metadata || typeof metadata !== "object" || !("version" in metadata) || typeof metadata.version !== "string") {
+        throw new Error("Could not identify the evaluation runtime package version");
+    }
+    const digest = (name) => (0, node_crypto_1.createHash)("sha256")
+        .update(fs.readFileSync(path.join(__dirname, `${name}${path.extname(__filename)}`))).digest("hex");
+    const observed = {
+        resetTurnState: messages => runtime.resetTurnState?.(messages),
+        streamTurn: async (request) => {
+            const response = await runtime.streamTurn(request);
+            (0, judge_1.assertShepherdJudgeCompletion)(response);
+            if (!(0, judge_1.isShepherdJudgeAnswerValid)(response.content ?? "")) {
+                throw new judge_1.ShepherdJudgeResponseError("invalid_answer", response.usage?.input_tokens ?? null);
+            }
+            return response;
+        },
+    };
+    return {
+        judge: (0, judge_1.createShepherdJudge)(async () => observed, 20_000),
+        provenance: {
+            provider: runtime.id, model: runtime.model, runtimeVersion: metadata.version,
+            judgeSha256: digest("judge"), evaluatorSha256: digest("judge-evaluation"),
+        },
+    };
+}
+function parseArgs(argv) {
+    const values = new Map();
+    for (let i = 0; i < argv.length; i += 2) {
+        const name = argv[i], value = argv[i + 1];
+        if (!["--agent", "--output"].includes(name) || values.has(name) || !value?.trim() || value.startsWith("--")) {
+            throw new Error("Usage: shepherd:judge-eval -- --agent NAME --output NEW_PRIVATE_REPORT.json");
+        }
+        values.set(name, value);
+    }
+    const agent = values.get("--agent"), output = values.get("--output");
+    if (!agent || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,99}$/.test(agent) || !output) {
+        throw new Error("Explicit --agent NAME and --output NEW_PRIVATE_REPORT.json are required");
+    }
+    return { agent, output };
+}
+async function runShepherdJudgeEvaluationCommand(argv, dependencies = {
+    loadJudge: loadConfiguredShepherdEvaluationJudge, openOutput: openShepherdJudgeEvaluationOutput,
+    // eslint-disable-next-line no-console -- explicit evaluation command terminal output
+    print: message => console.log(message),
+}) {
+    let output = null;
+    let exitCode = 1;
+    let summary = null;
+    let outputClosed = false;
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_judge_evaluation_command_start",
+        message: "starting explicit tool-free classification command", meta: {} });
+    try {
+        const args = parseArgs(argv);
+        (0, judge_evaluation_1.validateShepherdJudgeCorpus)(shepherd_judge_corpus_v1_json_1.default);
+        output = dependencies.openOutput(args.output);
+        const { judge, provenance } = await dependencies.loadJudge(args.agent);
+        const destination = output;
+        const report = await (0, judge_evaluation_1.runShepherdJudgeEvaluation)(shepherd_judge_corpus_v1_json_1.default, judge, provenance, results => {
+            if (results.length % 20 !== 0)
+                return;
+            destination.write({ schemaVersion: 1, phase: "judge-classification-only", state: "running",
+                ...provenance, completedCalls: results.length, results, admissionExercised: false, nativeHostQualified: false, v1Qualified: false });
+            dependencies.print(JSON.stringify({ phase: "judge-classification-only", completedCalls: results.length, v1Qualified: false }));
+        });
+        output.write(report);
+        summary = {
+            phase: report.phase, classificationPassed: report.classificationPassed, v1Qualified: false,
+            uniqueCases: report.uniqueCases, calls: report.results.length,
+            unsafeProposedActions: report.unsafeProposedActions, unattendedKeys: report.unattendedKeys, errors: report.errors,
+            errorCounts: report.errorCounts,
+            report: args.output, boundary: "Classification evidence only; not v1 qualification.",
+        };
+        exitCode = report.classificationPassed ? 0 : 1;
+    }
+    catch (error) {
+        const detail = (0, redact_1.redactSecrets)(String(error)).slice(0, 2000);
+        dependencies.print(JSON.stringify({ error: detail, v1Qualified: false }));
+        if (output) {
+            try {
+                output.write({ schemaVersion: 1, phase: "judge-classification-only", state: "error", error: detail, v1Qualified: false });
+            }
+            catch (writeError) {
+                dependencies.print(JSON.stringify({ error: `Could not persist evaluation error: ${(0, redact_1.redactSecrets)(String(writeError)).slice(0, 2000)}` }));
+            }
+        }
+        (0, runtime_1.emitNervesEvent)({ component: "senses", level: "error", event: "senses.shepherd_judge_evaluation_command_error",
+            message: "classification command failed; no v1 qualification",
+            meta: { phase: "judge-classification-only", outputReserved: output !== null, error: detail } });
+    }
+    finally {
+        try {
+            output?.close();
+            outputClosed = output !== null;
+        }
+        catch (error) {
+            exitCode = 1;
+            const detail = (0, redact_1.redactSecrets)(String(error)).slice(0, 2000);
+            dependencies.print(JSON.stringify({ error: `Could not close evaluation output: ${detail}`, v1Qualified: false }));
+            (0, runtime_1.emitNervesEvent)({ component: "senses", level: "error", event: "senses.shepherd_judge_evaluation_output_close_error",
+                message: "evaluation output close failed", meta: { phase: "judge-classification-only", error: detail } });
+        }
+    }
+    if (summary && outputClosed) {
+        dependencies.print(JSON.stringify(summary));
+        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_judge_evaluation_command_end",
+            message: "classification report persisted and closed", meta: { classificationPassed: summary.classificationPassed, v1Qualified: false } });
+    }
+    return exitCode;
+}

package/dist/senses/shepherd/judge-evaluation-entry.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const judge_evaluation_command_1 = require("./judge-evaluation-command");
+const runtime_1 = require("../../nerves/runtime");
+const redact_1 = require("./redact");
+void (0, judge_evaluation_command_1.runShepherdJudgeEvaluationCommand)(process.argv.slice(2)).then(code => { process.exitCode = code; }).catch(error => {
+    const detail = (0, redact_1.redactSecrets)(String(error)).slice(0, 2000);
+    (0, runtime_1.emitNervesEvent)({ component: "senses", level: "error", event: "senses.shepherd_judge_evaluation_entry_error",
+        message: "classification command rejected unexpectedly", meta: { phase: "judge-classification-only", error: detail } });
+    // eslint-disable-next-line no-console -- terminal UX: last-resort nonzero evaluation failure
+    console.error(JSON.stringify({ error: detail, v1Qualified: false }));
+    process.exitCode = 1;
+});