@akagilnc/pi-workflow-roles 0.1.5614 → 0.1.5650

package/src/report-ticket-tool.ts

@@ -0,0 +1,176 @@
+/**
+ * Mid-turn ticket report (#1171): roles call this as soon as they know the
+ * ticket number; the executing process binds and relocates immediately.
+ * When to call lives in this tool's description — not Soul.
+ */
+import { Type } from "typebox";
+import { existsSync } from "node:fs";
+
+import type {
+  DurablePrincipalAuthority,
+  HostContext,
+  HostToolResult,
+  RoleHost,
+} from "./host-contracts.ts";
+import { runDirectoryFromHostContext } from "./host-contracts.ts";
+import { piDurablePrincipalAuthority } from "./pi/durable-principal.ts";
+import {
+  bindAdmittedTicketNumber,
+  relocateAdmittedRunToTicket,
+  type AdmittedRoleInvocation,
+} from "./public-cli/invocation.ts";
+import { isUnboundRunDirectory, sessionDirectoryOf, sessionFileOf } from "./role-run-placement.ts";
+import { readPageSync } from "./run-dossier.ts";
+import { readDeclaredTicketNumber } from "./run-ticket-number.ts";
+import { isRecord } from "./unknown-value.ts";
+
+export const REPORT_TICKET_TOOL_NAME = "ak_report_ticket" as const;
+
+const reportTicketArgsSchema = Type.Object(
+  {
+    ticketNumber: Type.Unknown({
+      description:
+        "本票号（正整数、数字串或前导 #N）。已知票号时开工即报；尚无票号时不要调用。",
+    }),
+  },
+  { additionalProperties: true },
+);
+
+export const REPORT_TICKET_TOOL_DESCRIPTION =
+  "向包申报本票号。已知票号时开工第一件事调用；包当场把本腿归到票号目录。"
+  + "尚无票号（例如中书省建票前）不要调用，取得后再报。"
+  + "交卷时若仍未报过且交卷亦未带票号，包会经既有重交通道再问一次。";
+
+function pageString(page: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = page?.[key];
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+/**
+ * Build the relocate seam's admitted face from durable pages + live principal.
+ * The executing process owns this snapshot for the bind/relocate call only.
+ */
+export function admittedForLiveTicketReport(
+  runDirectory: string,
+  authority: DurablePrincipalAuthority,
+): AdmittedRoleInvocation {
+  const admittedPage = readPageSync(runDirectory, "admitted") ?? {};
+  const invocationPage = readPageSync(runDirectory, "invocation") ?? {};
+  const role = pageString(admittedPage, "role") ?? pageString(invocationPage, "role");
+  const runId = pageString(admittedPage, "runId") ?? pageString(invocationPage, "runId");
+  const bookKey = pageString(admittedPage, "bookKey") ?? pageString(invocationPage, "bookKey");
+  const projectRoot = pageString(admittedPage, "projectRoot")
+    ?? pageString(invocationPage, "projectRoot");
+  if (role === undefined || runId === undefined || bookKey === undefined || projectRoot === undefined) {
+    throw new Error("ak_report_ticket requires durable role/runId/bookKey/projectRoot on the run");
+  }
+  const attachments = Array.isArray(admittedPage.attachments)
+    ? admittedPage.attachments as AdmittedRoleInvocation["attachments"]
+    : [];
+  const sessionDirectory = sessionDirectoryOf(runDirectory);
+  const sessionFile = sessionFileOf(runDirectory);
+  const principal = authority.seal({ sessionDirectory, sessionFile });
+  const ticketNumber = readDeclaredTicketNumber(admittedPage.ticketNumber)
+    ?? readDeclaredTicketNumber(invocationPage.ticketNumber);
+  return {
+    role,
+    runId,
+    bookKey,
+    projectRoot,
+    instruction: typeof admittedPage.instruction === "string" ? admittedPage.instruction : "",
+    instructionEmpty: admittedPage.instructionEmpty === true
+      || (typeof admittedPage.instruction === "string" && admittedPage.instruction.trim() === ""),
+    attachments,
+    runDirectory,
+    principal,
+    ...(ticketNumber === undefined ? {} : { ticketNumber }),
+  } as AdmittedRoleInvocation;
+}
+
+/**
+ * Role-facing tool details only (#1171 / ADR 0087): ticket identity and whether
+ * placement moved. Never hand a package-computed runDirectory back to the seat.
+ */
+export type ReportTicketResult = {
+  readonly ticketNumber: number;
+  readonly relocated: boolean;
+};
+
+/**
+ * Bind + relocate under the existing post-admission seams, then update the
+ * executing process's live path handles (HostContext + optional env + setSessionFile).
+ * Pi: native SessionManager.setSessionFile so later appends stay on the moved file.
+ */
+export async function reportTicketFromHostContext(
+  context: HostContext,
+  rawTicketNumber: unknown,
+  authority: DurablePrincipalAuthority = piDurablePrincipalAuthority,
+): Promise<ReportTicketResult> {
+  const ticketNumber = readDeclaredTicketNumber(rawTicketNumber);
+  if (ticketNumber === undefined) {
+    throw new Error("ak_report_ticket requires an identifiable ticketNumber");
+  }
+  const runDirectory = runDirectoryFromHostContext(context);
+  if (runDirectory === undefined) {
+    throw new Error("ak_report_ticket requires a per-turn run directory");
+  }
+  if (!existsSync(runDirectory)) {
+    throw new Error(`ak_report_ticket run directory missing: ${runDirectory}`);
+  }
+
+  const admitted = admittedForLiveTicketReport(runDirectory, authority);
+  const alreadyPlaced = !isUnboundRunDirectory(runDirectory);
+  // #1171 B2 / #1025: already under a ticket leaf — do not rewrite durable identity.
+  // Placement stays put; no heterogenous-ticket refuse policy (#1171 judge).
+  if (!alreadyPlaced) {
+    await bindAdmittedTicketNumber(admitted, ticketNumber);
+  }
+  // Live handles belong with rename ownership — before derived renderCurrentSync
+  // (#1171 F4-R2). Reuse relocate's heldLease.relocate seam; keep raw I/O throw.
+  const applyLiveHandles = (nextDirectory: string): void => {
+    (context as { runDirectory?: string }).runDirectory = nextDirectory;
+    // Same-leg spawn env only (#1171 F1): never overwrite another leg's ambient
+    // AK_ROLE_RUN_DIR in a shared process. HostContext is the per-turn authority
+    // (host-contracts); Pi dedicated children still refresh when env === old path.
+    if (process.env.AK_ROLE_RUN_DIR === runDirectory) {
+      process.env.AK_ROLE_RUN_DIR = nextDirectory;
+    }
+    // Native host rebind only — SessionManager has no setSessionDir; appends follow sessionFile.
+    context.sessionManager.setSessionFile?.(sessionFileOf(nextDirectory));
+  };
+  const relocation = alreadyPlaced
+    ? undefined
+    : await relocateAdmittedRunToTicket(admitted, authority, { relocate: applyLiveHandles });
+  const nextDirectory = relocation?.newRunDirectory ?? admitted.runDirectory;
+  if (relocation === undefined) applyLiveHandles(nextDirectory);
+
+  return {
+    ticketNumber: alreadyPlaced
+      ? (admitted.ticketNumber ?? ticketNumber)
+      : ticketNumber,
+    relocated: relocation !== undefined,
+  };
+}
+
+/** Register the report-ticket tool on the shared host tool mouth (same as submission). */
+export function registerReportTicketTool(roleHost: RoleHost): void {
+  if (roleHost.getAllTools().some((tool) => tool.name === REPORT_TICKET_TOOL_NAME)) return;
+  roleHost.registerTool({
+    name: REPORT_TICKET_TOOL_NAME,
+    label: "报票号",
+    description: REPORT_TICKET_TOOL_DESCRIPTION,
+    promptSnippet: "已知票号时立即申报，包当场归位",
+    parameters: reportTicketArgsSchema,
+    async execute(_toolCallId, parameters, _signal, _onUpdate, ctx): Promise<HostToolResult<ReportTicketResult>> {
+      const raw = isRecord(parameters) ? parameters.ticketNumber : undefined;
+      const details = await reportTicketFromHostContext(ctx, raw);
+      return {
+        content: [],
+        details,
+      };
+    },
+  });
+}
+
+/** Soft re-ask when a sealed submission still leaves the leg unbound (#1171 / ADR 0073). */
+export const MISSING_TICKET_REASK_MATERIAL = "resources/missing-ticket-reask.md" as const;

package/src/role-envelope.ts

@@ -3,7 +3,7 @@ import { appendFile, mkdir, writeFile } from "node:fs/promises";
 import { createServer, type Server, type Socket } from "node:net";
 import { dirname } from "node:path";
 
-import { sessionFileOf } from "./role-run-placement.ts";
+import { sessionDirectoryOf, sessionFileOf } from "./role-run-placement.ts";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -28,6 +28,7 @@ import {
 } from "./role-runtime.ts";
 import type { PreparedRoleTurn } from "./prepared-role-turn.ts";
 import { projectActivationFlags } from "./role-activation-flags.ts";
+import { projectTurnRequestLiveRunDirectory } from "./role-run-relocation.ts";
 import {
   isCorrectableExecuteError,
   projectCorrectableExecuteRejection,
@@ -170,11 +171,14 @@ export async function prepareRoleEnvelope(options: {
       }
     });
   };
+  const mutableRequest = request as {
+    runDirectory: string;
+    principal: { sessionDirectory?: string; sessionFile?: string };
+  };
   const context: HostContext = {
     cwd: request.cwd,
     mode: "print",
     model: request.model === undefined ? undefined : { provider: request.model.provider },
-    runDirectory: request.runDirectory,
     ...(request.courtAttemptId === undefined ? {} : { courtAttemptId: request.courtAttemptId }),
     ...(request.invocationScopeId === undefined ? {} : { invocationScopeId: request.invocationScopeId }),
     ...(request.host === undefined || request.host.trim() === "" ? {} : { host: request.host.trim() }),
@@ -202,6 +206,27 @@ export async function prepareRoleEnvelope(options: {
       // and non-correctable MCP catch). Submission does not abort the turn.
     },
   };
+  // #1171: report-ticket updates HostContext.runDirectory; keep the shared turn
+  // request (and principal session paths) on the same leaf for adapter exit-copy.
+  Object.defineProperty(context, "runDirectory", {
+    configurable: true,
+    enumerable: true,
+    get() {
+      return mutableRequest.runDirectory;
+    },
+    set(next: string) {
+      if (typeof next !== "string" || next.trim() === "") return;
+      if (mutableRequest.runDirectory === next) return;
+      projectTurnRequestLiveRunDirectory(mutableRequest, next);
+      sessionFile = sessionFileOf(next);
+      if (typeof mutableRequest.principal.sessionDirectory !== "string") {
+        mutableRequest.principal.sessionDirectory = sessionDirectoryOf(next);
+      }
+      if (typeof mutableRequest.principal.sessionFile !== "string") {
+        mutableRequest.principal.sessionFile = sessionFile;
+      }
+    },
+  });
   const bookCustomMessage = (customType: string, message: { content?: string; details?: unknown }): void => {
     const payload = {
       ...(message.content === undefined ? {} : { content: message.content }),
@@ -599,7 +624,7 @@ export async function prepareRoleEnvelope(options: {
     } catch (error) {
       // Closing the relay is ordinary cleanup, not required envelope work.
       await retainPackageFault({
-        runDirectory: request.runDirectory,
+        runDirectory: mutableRequest.runDirectory,
         diagnostic: `relay close failed beside envelope shutdown: ${describeErrorIdentity(error)}`,
         error,
       });

package/src/role-run-placement.ts

@@ -17,7 +17,6 @@ export type RoleRunPlacement = {
   readonly runDirectory: string;
   readonly sessionDirectory: string;
   readonly sessionFile: string;
-  readonly attachmentsDirectory: string;
 };
 
 /** Writer leaf `<runId>@<role>`. Empty sides stay empty; this is not a validator. */
@@ -158,7 +157,6 @@ export function roleRunPlacement(
     runDirectory,
     sessionDirectory,
     sessionFile: sessionFileIn(sessionDirectory),
-    attachmentsDirectory: join(runDirectory, "attachments"),
   };
 }
 

package/src/role-run-relocation.ts

@@ -3,7 +3,7 @@
  * Live callers project typed fields; only historical migrators walk durable pages.
  *
  * Scope is typed machine-consumed path fields only — never free text, never
- * frozen attachment/artifact bytes. Nested walk is confined to package-owned
+ * caller file-flag path strings. Nested walk is confined to package-owned
  * `session/` seams.
  */
 import { readdir, readFile, writeFile } from "node:fs/promises";
@@ -43,6 +43,12 @@ const RUN_STATE_PAGE_FIELDS = [
   "sessionFile",
 ] as const;
 
+/** Typed principal session coordinates rewritten when the owning run leaf moves. */
+export const PRINCIPAL_SESSION_PATH_FIELDS = [
+  "sessionDirectory",
+  "sessionFile",
+] as const;
+
 const SOURCE_RUN_LOCATOR_FIELDS = ["runDirectory"] as const;
 const SUMMONS_PATH_FIELDS = ["sourceRunPath"] as const;
 const OFFICER_POINTER_FIELDS = ["sessionFile", "runDirectory"] as const;
@@ -146,6 +152,41 @@ export function rewriteRunDirectoryPathFields(
   ]);
 }
 
+/** Principal session paths only — shared live + durable projection after a run move. */
+export function rewritePrincipalSessionPaths(
+  principal: Record<string, unknown>,
+  oldRunDirectory: string,
+  newRunDirectory: string,
+): void {
+  rewriteRunDirectoryPathFields(
+    principal,
+    PRINCIPAL_SESSION_PATH_FIELDS,
+    oldRunDirectory,
+    newRunDirectory,
+  );
+}
+
+/**
+ * Live turn request: move runDirectory and rewrite principal session paths in place.
+ * Callers that lack authority.seal use this; admitted refresh seals after the same rewrite.
+ */
+export function projectTurnRequestLiveRunDirectory(
+  request: {
+    runDirectory: string;
+    principal: { sessionDirectory?: string; sessionFile?: string };
+  },
+  newRunDirectory: string,
+): void {
+  const old = request.runDirectory;
+  if (old === newRunDirectory) return;
+  request.runDirectory = newRunDirectory;
+  rewritePrincipalSessionPaths(
+    request.principal as Record<string, unknown>,
+    old,
+    newRunDirectory,
+  );
+}
+
 /** In-place rewrite of selected fields against a rewrite set. */
 export function rewriteRunDirectoryPathFieldsAgainstRewrites(
   record: Record<string, unknown>,
@@ -227,7 +268,7 @@ export function rewriteAdmittedRoleRunPage(
   if (isRecord(page.principal)) {
     rewriteRunDirectoryPathFieldsAgainstRewrites(
       page.principal,
-      ["sessionDirectory", "sessionFile"],
+      PRINCIPAL_SESSION_PATH_FIELDS,
       rewrites,
     );
   }
@@ -385,7 +426,7 @@ async function rewriteSessionTranscriptBindings(
 /**
  * Package-owned nested seams under session/ only:
  * sitian records.jsonl,
- * session transcript typed parent bindings. Never walks attachments/.
+ * session transcript typed parent bindings. Never walks caller file paths.
  */
 async function rewriteNestedMachinePathPages(
   pagesDirectory: string,
@@ -447,7 +488,7 @@ export async function rewriteRoleRunDurablePages(input: {
       if (isRecord(page.principal)) {
         rewriteRunDirectoryPathFieldsAgainstRewrites(
           page.principal,
-          ["sessionDirectory", "sessionFile"],
+          PRINCIPAL_SESSION_PATH_FIELDS,
           rewrites,
         );
       }

package/src/role-runtime.ts

@@ -16,6 +16,7 @@ import { sitianReport } from "./sitian-facade.ts";
 import { sitianReportSafe } from "./host-session-record.ts";
 import { createSubmissionLedgerHost, sealAcceptedSubmission } from "./submission-ledger.ts";
 import { registerFiledSubmissionTool, type FiledSubmissionBeforeAccept } from "./filed-submission.ts";
+import { registerReportTicketTool, REPORT_TICKET_TOOL_NAME } from "./report-ticket-tool.ts";
 import type { RoleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 import { activationTraceRecordSchema, namedActivationCause, type ActivationTraceRecord, type ActivationTraceWriter } from "./activation-trace.ts";
@@ -1790,6 +1791,11 @@ export function createRoleRuntimeExtension(
         }
 
         await executeActivationStage(entry.role, activationStage(entry.role, activateByRole), { clock, writeTrace });
+        // #1171: same registration mouth as submission tools; when-to-call is on the tool itself.
+        registerReportTicketTool(roleHost);
+        roleHost.setActiveTools([
+          ...new Set([...roleHost.getActiveTools(), REPORT_TICKET_TOOL_NAME]),
+        ]);
         roleReferenceMaterials = await dependencies.loadRoleReferenceMaterials?.(entry.role) ?? "";
         // #357 T2 / #378 / #380 / #391 / #818: any role+engine activation registers the package detour tool once.
         // Gate is resolveEngineName (RoleHost flag → env fallback) — no per-engine execute branch; no role-module spawn.

package/src/worker-submission-gates.ts

@@ -264,6 +264,8 @@ export function createWorkerSubmissionGate(
   let unfinishedReasonBounces = 0;
   let invocationScopeId: string | undefined;
   let record: HostRecordSession | undefined;
+  /** Live parent — mid-turn run relocate (#1171) may move its session file. */
+  let parentRef: WorkerSubmissionGateParent | undefined;
   /** Parent session file retained so every gate sitian write path-derives the same ledger home. */
   let sessionParent: string | undefined;
   const explicitHome =
@@ -278,6 +280,25 @@ export function createWorkerSubmissionGate(
       return null;
     }
   };
+  /**
+   * #1171: report-ticket renames the run leaf; the gate nest moves with it, but the
+   * in-memory HostRecordSession still names the old path. Reopen under the live
+   * parent (continueRecent resumes the moved nest) before any append.
+   */
+  const liveRecord = (): HostRecordSession | undefined => {
+    if (record === undefined || root === undefined || parentRef === undefined) return record;
+    const file = record.getSessionFile();
+    if (file !== undefined && existsSync(file)) return record;
+    const parentFile = parentRef.getSessionFile();
+    if (parentFile === undefined || parentFile.length === 0) return record;
+    sessionParent = parentFile;
+    record = createRecordSession({
+      cwd: root,
+      kind: WORKER_SUBMISSION_GATE_RECORD_KIND,
+      parent: parentRef,
+    });
+    return record;
+  };
   const gateSitian = (cwd: string, payload: Record<string, unknown>) => {
     sitianReport({
       level: "event",
@@ -294,6 +315,7 @@ export function createWorkerSubmissionGate(
       invocationScopeId = scope;
       uninstallPackageWorkerHooks(cwd);
       root = cwd;
+      parentRef = parent;
       sessionParent = parent.getSessionFile();
       record = createRecordSession({
         cwd,
@@ -322,9 +344,10 @@ export function createWorkerSubmissionGate(
       });
     },
     assertAcceptable(status, details) {
+      const gateRecord = liveRecord();
       if (status === "unfinished" && !unfinishedReasonPresent(details)) {
         if (unfinishedReasonBounces < unfinishedReasonBounceLimit) {
-          record?.appendCustomEntry(WORKER_UNFINISHED_REASON_BOUNCE_ENTRY_TYPE, {
+          gateRecord?.appendCustomEntry(WORKER_UNFINISHED_REASON_BOUNCE_ENTRY_TYPE, {
             version: 1, invocationScopeId,
           });
           unfinishedReasonBounces += 1;
@@ -338,7 +361,7 @@ export function createWorkerSubmissionGate(
       // Gate ① — forgetfulness reminder (ADR 0066; behavior unchanged).
       if (!headMoved && !reminded) {
         reminded = true;
-        record?.appendCustomEntry(WORKER_COMMIT_REMINDER_BOUNCE_ENTRY_TYPE, { version: 1 });
+        gateRecord?.appendCustomEntry(WORKER_COMMIT_REMINDER_BOUNCE_ENTRY_TYPE, { version: 1 });
         gateSitian(root, {
           type: WORKER_COMMIT_REMINDER_BOUNCE_ENTRY_TYPE,
           version: 1,
@@ -358,7 +381,7 @@ export function createWorkerSubmissionGate(
         return;
       }
       prefixReminded = true;
-      record?.appendCustomEntry(WORKER_PREFIX_REMINDER_BOUNCE_ENTRY_TYPE, { version: 1 });
+      gateRecord?.appendCustomEntry(WORKER_PREFIX_REMINDER_BOUNCE_ENTRY_TYPE, { version: 1 });
       gateSitian(root, {
         type: WORKER_PREFIX_REMINDER_BOUNCE_ENTRY_TYPE,
         version: 1,