@akagilnc/pi-workflow-roles 0.1.4239 → 0.1.4259

package/dist/engine-detour-tool.js

@@ -1,3 +1,4 @@
+import { basename } from "node:path";
 import { Type } from "typebox";
 import {
   ENGINE_DETOUR_TOOL_NAME,
@@ -7,6 +8,16 @@ import {
   resolveEngineName,
   runEngineDetourOnce
 } from "./engine-detour.js";
+import {
+  engineDetourStdoutByteLength,
+  reportEngineDetourCall
+} from "./engine-detour-usage.js";
+function basenameRunId(runDirectory) {
+  const leaf = basename(runDirectory);
+  const at = leaf.indexOf("@");
+  if (at <= 0) return void 0;
+  return leaf.slice(0, at);
+}
 const engineDetourArgsSchema = Type.Object(
   {
     argv: Type.Array(Type.String({ minLength: 1 }), {
@@ -23,6 +34,9 @@ function isCallerCancellation(error, signal) {
   }
   return false;
 }
+function asError(error, fallback) {
+  return error instanceof Error ? error : new Error(String(error).trim() || fallback);
+}
 function createEngineDetourToolDefinition(input) {
   const engineName = input.engineName;
   const engineModel = input.engineModel;
@@ -43,6 +57,45 @@ function createEngineDetourToolDefinition(input) {
           ctx
         );
       }
+      const sessionParent = ctx.sessionManager?.getSessionFile?.();
+      const startedAt = Date.now();
+      const runDirectory = typeof ctx.runDirectory === "string" && ctx.runDirectory.length > 0 ? ctx.runDirectory : void 0;
+      const runId = runDirectory === void 0 ? void 0 : basenameRunId(runDirectory);
+      const invocationScopeId = typeof ctx.invocationScopeId === "string" && ctx.invocationScopeId.trim() !== "" ? ctx.invocationScopeId.trim() : void 0;
+      const host = typeof ctx.host === "string" && ctx.host.trim() !== "" ? ctx.host.trim() : void 0;
+      const recordCall = (observed2) => {
+        if (typeof sessionParent !== "string" || sessionParent.length === 0) return;
+        reportEngineDetourCall({
+          toolCallId,
+          durationMs: Math.max(0, Date.now() - startedAt),
+          cwd: ctx.cwd,
+          sessionParent,
+          ...runId === void 0 ? {} : { runId },
+          ...invocationScopeId === void 0 ? {} : { invocationScopeId },
+          ...host === void 0 ? {} : { host },
+          ...observed2.code === void 0 ? {} : { code: observed2.code },
+          ...observed2.stdoutByteLength === void 0 ? {} : { stdoutByteLength: observed2.stdoutByteLength }
+        });
+      };
+      const failAfterLedger = (engineCause, observed2, aggregateMessage) => {
+        try {
+          recordCall(observed2);
+        } catch (recordError) {
+          input.fail(
+            new AggregateError(
+              [
+                engineCause,
+                asError(recordError, "engine detour usage ledger write failed")
+              ],
+              aggregateMessage,
+              { cause: engineCause }
+            ),
+            toolCallId,
+            ctx
+          );
+        }
+        input.fail(engineCause, toolCallId, ctx);
+      };
       let result;
       try {
         result = await runEngineDetourOnce({
@@ -52,16 +105,22 @@ function createEngineDetourToolDefinition(input) {
         });
       } catch (error) {
         if (isCallerCancellation(error, signal)) throw error;
-        const cause = error instanceof Error ? error : new Error(String(error).trim() || "\u52B3\u52A1\u5F15\u64CE spawn \u5931\u8D25");
-        input.fail(cause, toolCallId, ctx);
+        return failAfterLedger(
+          asError(error, "\u52B3\u52A1\u5F15\u64CE spawn \u5931\u8D25"),
+          {},
+          "engine detour spawn and usage ledger both failed"
+        );
       }
+      const stdoutByteLength = engineDetourStdoutByteLength(result.stdout);
+      const observed = { code: result.code, stdoutByteLength };
       if (isEngineDetourFailure(result)) {
-        input.fail(
+        return failAfterLedger(
           new Error(engineDetourFailureDiagnostic(result)),
-          toolCallId,
-          ctx
+          observed,
+          "engine detour child-close and usage ledger both failed"
         );
       }
+      recordCall(observed);
       return {
         content: [{ type: "text", text: result.stdout }],
         details: {

package/dist/engine-detour-usage.js

@@ -0,0 +1,285 @@
+/**
+ * #537 typed ak_engine_detour tool usage ledger.
+ *
+ * Observes only the package detour tool path. Bash/CLI ordinary path
+ * (resources/engine-dispatch.md ordinary path) stays outside this ledger — a
+ * permanent blind spot that must never be read as "the seat did not use an engine".
+ *
+ * Runtime owns these facts beside role payloads (ADR 0042); they land in
+ * TerminalResult.decisiveFacts and are written live via sitian (ADR 0077).
+ * No gate, no required field, no index bytes (ADR 0049 / 0057).
+ *
+ * Invocation scope is one public ak-role call (#537), owned by the shared Host
+ * execution envelope (RoleTurnRequest / HostContext). Auto-resume attempts inside
+ * that call share the same scope; only an explicit new public call (including
+ * `ak-role resume`) mints a new one. Never courtAttemptId, never Pi session
+ * toolResult join keys, and never a detour-owned sidecar file.
+ */
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ENGINE_DETOUR_TOOL_NAME } from "./engine-detour.js";
+import { readSitianRecords, resolveSitianRecordPath, sitianReport, } from "./sitian-facade.js";
+/** Sitian event kind for one detour-tool call (volume under session/). */
+export const ENGINE_DETOUR_CALL_KIND = "engine-detour-call";
+/** decisiveFacts key — name states detour-tool scope, not full engine usage. */
+export const ENGINE_DETOUR_TOOL_USAGE_FACT_KEY = "engineDetourToolUsage";
+/**
+ * Run-relative sitian volume path for one detour call.
+ * Openable once the run directory is known (resume.command / top-level runId);
+ * contains no runId bytes itself (#108 + #537 AC8).
+ */
+export const ENGINE_DETOUR_CALL_RECORD_FILE_RELATIVE = `session/${ENGINE_DETOUR_CALL_KIND}/records.jsonl`;
+/** stdout UTF-8 byte length (ticket-frozen metric; empty stdout is real 0). */
+export function engineDetourStdoutByteLength(stdout) {
+    return Buffer.byteLength(stdout, "utf8");
+}
+/**
+ * Deterministic sitian identity: invocation scope + toolCallId.
+ * Must not embed runId — public Terminal decisiveFacts re-expose identity (#108).
+ */
+export function engineDetourCallIdentity(input) {
+    const scope = input.invocationScopeId ?? "";
+    return `engine-detour-call:${scope}:${input.toolCallId}`;
+}
+/** Live sitian write for one detour call. Returns the call fact with pointer. */
+export function reportEngineDetourCall(input) {
+    const payload = {
+        tool: ENGINE_DETOUR_TOOL_NAME,
+        toolCallId: input.toolCallId,
+        durationMs: input.durationMs,
+    };
+    if (input.code !== undefined)
+        payload.code = input.code;
+    if (input.stdoutByteLength !== undefined) {
+        payload.stdoutByteLength = input.stdoutByteLength;
+    }
+    if (input.invocationScopeId !== undefined) {
+        payload.invocationScopeId = input.invocationScopeId;
+    }
+    if (input.runId !== undefined)
+        payload.runId = input.runId;
+    // SitianSubject object form requires runId; invocation scope rides payload always.
+    const subject = input.runId === undefined
+        ? undefined
+        : {
+            runId: input.runId,
+            ...(input.invocationScopeId === undefined
+                ? {}
+                : { invocationScopeId: input.invocationScopeId }),
+        };
+    const pointer = sitianReport({
+        level: "event",
+        kind: ENGINE_DETOUR_CALL_KIND,
+        identity: engineDetourCallIdentity({
+            toolCallId: input.toolCallId,
+            ...(input.invocationScopeId === undefined
+                ? {}
+                : { invocationScopeId: input.invocationScopeId }),
+        }),
+        cwd: input.cwd,
+        sessionParent: input.sessionParent,
+        source: "engine-detour-tool",
+        payload,
+        raw: {
+            sessionFile: input.sessionParent,
+            entryId: input.toolCallId,
+        },
+        ...(input.home === undefined ? {} : { home: input.home }),
+        ...(input.host === undefined ? {} : { host: input.host }),
+        ...(subject === undefined ? {} : { subject }),
+    });
+    return {
+        toolCallId: input.toolCallId,
+        durationMs: input.durationMs,
+        ...(input.code === undefined ? {} : { code: input.code }),
+        ...(input.stdoutByteLength === undefined
+            ? {}
+            : { stdoutByteLength: input.stdoutByteLength }),
+        recordPointer: pointer,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function callFactFromSitianPayload(payload, pointer) {
+    if (!isRecord(payload))
+        return undefined;
+    if (payload.tool !== ENGINE_DETOUR_TOOL_NAME)
+        return undefined;
+    if (typeof payload.toolCallId !== "string" || payload.toolCallId.length === 0) {
+        return undefined;
+    }
+    if (typeof payload.durationMs !== "number" || !Number.isFinite(payload.durationMs)) {
+        return undefined;
+    }
+    return {
+        toolCallId: payload.toolCallId,
+        durationMs: payload.durationMs,
+        ...(typeof payload.code === "number" ? { code: payload.code } : {}),
+        ...(typeof payload.stdoutByteLength === "number"
+            ? { stdoutByteLength: payload.stdoutByteLength }
+            : {}),
+        recordPointer: pointer,
+    };
+}
+function invocationScopeIdOfRecord(record) {
+    if (isRecord(record.subject)) {
+        const fromSubject = record.subject.invocationScopeId;
+        if (typeof fromSubject === "string" && fromSubject.length > 0)
+            return fromSubject;
+    }
+    if (isRecord(record.payload)) {
+        const fromPayload = record.payload.invocationScopeId;
+        if (typeof fromPayload === "string" && fromPayload.length > 0)
+            return fromPayload;
+    }
+    return undefined;
+}
+/**
+ * Read this-invocation detour-tool usage from sitian volume.
+ * When `invocationScopeId` is provided, only records bound to that public call count
+ * (host-neutral boundary — not session toolResult join keys, not courtAttemptId).
+ * When engineMounted is false, returns undefined (field absent).
+ * When engineMounted is true and no calls, returns callCount 0.
+ */
+export async function readEngineDetourToolUsage(input) {
+    if (!input.engineMounted)
+        return undefined;
+    const { recordFile } = resolveSitianRecordPath({
+        level: "event",
+        kind: ENGINE_DETOUR_CALL_KIND,
+        sessionParent: input.sessionParent,
+        ...(input.home === undefined ? {} : { home: input.home }),
+        ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
+    });
+    const { records } = await readSitianRecords(recordFile);
+    const calls = [];
+    for (const record of records) {
+        if (record.kind !== ENGINE_DETOUR_CALL_KIND)
+            continue;
+        const boundScope = invocationScopeIdOfRecord(record);
+        if (input.invocationScopeId !== undefined && input.invocationScopeId.length > 0) {
+            if (boundScope !== input.invocationScopeId)
+                continue;
+        }
+        else if (boundScope !== undefined) {
+            // Unscoped settlement must not pull invocation-bound rows across resume.
+            continue;
+        }
+        const pointer = {
+            identity: record.identity,
+            recordFile,
+            kind: record.kind,
+            level: record.level,
+        };
+        const fact = callFactFromSitianPayload(record.payload, pointer);
+        if (fact === undefined)
+            continue;
+        calls.push(fact);
+    }
+    return { callCount: calls.length, calls };
+}
+/**
+ * Project usage onto the public Terminal face.
+ * Non-resumable: keep absolute recordFile (runId already public via top-level runId).
+ * Resumable: keep an openable run-relative recordFile and identity with no runId
+ * bytes (#108 single disclosure + #537 AC8 reopen).
+ */
+export function projectEngineDetourToolUsageForPublicTerminal(usage, options) {
+    if (options.discloseRecordFile)
+        return usage;
+    return {
+        callCount: usage.callCount,
+        calls: usage.calls.map((call) => ({
+            toolCallId: call.toolCallId,
+            durationMs: call.durationMs,
+            ...(call.code === undefined ? {} : { code: call.code }),
+            ...(call.stdoutByteLength === undefined
+                ? {}
+                : { stdoutByteLength: call.stdoutByteLength }),
+            recordPointer: {
+                identity: call.recordPointer.identity,
+                kind: call.recordPointer.kind,
+                level: call.recordPointer.level,
+                recordFile: ENGINE_DETOUR_CALL_RECORD_FILE_RELATIVE,
+            },
+        })),
+    };
+}
+/** One shared invocation.json reader (ENOENT → undefined; other errors propagate). */
+function readInvocationRecord(runDirectory) {
+    try {
+        const raw = JSON.parse(readFileSync(join(runDirectory, "invocation.json"), "utf8"));
+        return isRecord(raw) ? raw : undefined;
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/** True when invocation.json carries a non-empty engine axis. */
+export async function readInvocationEngineMounted(runDirectory) {
+    const raw = readInvocationRecord(runDirectory);
+    if (raw === undefined)
+        return false;
+    return typeof raw.engine === "string" && raw.engine.trim() !== "";
+}
+/**
+ * Selected host from the admission invocation page — for post-admission
+ * host-transition classification only. In-turn tools take host from the shared
+ * Host envelope (RoleTurnRequest / HostContext), never this reader.
+ * Undefined when absent — callers must not invent "pi".
+ */
+export function readInvocationSelectedHost(runDirectory) {
+    const raw = readInvocationRecord(runDirectory);
+    if (raw === undefined)
+        return undefined;
+    return typeof raw.host === "string" && raw.host.trim() !== ""
+        ? raw.host.trim()
+        : undefined;
+}
+/** Merge usage into decisiveFacts without touching role payloads. */
+export function withEngineDetourToolUsageFact(outcome, usage) {
+    if (usage === undefined)
+        return outcome;
+    const prior = isRecord(outcome.decisiveFacts) ? outcome.decisiveFacts : {};
+    return {
+        ...outcome,
+        decisiveFacts: {
+            ...prior,
+            [ENGINE_DETOUR_TOOL_USAGE_FACT_KEY]: usage,
+        },
+    };
+}
+/** runDirectory owning a session directory (.../runs/<id>@role/session). */
+export function runDirectoryFromSessionDirectory(sessionDirectory) {
+    return dirname(sessionDirectory);
+}
+/** session.jsonl under a session directory. */
+export function sessionFileFromSessionDirectory(sessionDirectory) {
+    return join(sessionDirectory, "session.jsonl");
+}
+/**
+ * Mint one public-invocation scope id when an engine is mounted.
+ * Call once at the public-entry boundary — never inside the auto-resume loop.
+ * The id lives on RoleTurnRequest / HostContext only (no detour sidecar file).
+ */
+export function mintEngineDetourInvocationScope(input) {
+    const engine = input.effectiveEngine?.trim();
+    if (engine === undefined || engine.length === 0)
+        return undefined;
+    return randomUUID();
+}
+/** Attach a minted scope onto a turn request (shared Host envelope field). */
+export function withEngineDetourInvocationScope(request, invocationScopeId) {
+    if (invocationScopeId === undefined || invocationScopeId.length === 0) {
+        return request;
+    }
+    if (typeof request.invocationScopeId === "string" &&
+        request.invocationScopeId.length > 0) {
+        return request;
+    }
+    return { ...request, invocationScopeId };
+}