@akagilnc/pi-workflow-roles 0.1.4586 → 0.1.4620

package/src/headless-host/description.ts

@@ -83,7 +83,11 @@ export function headlessTurnArgs(options: {
   readonly description: ClaudePrintHostDescription;
   /** Absolute path written by the adapter; paired with `systemPromptFlag`. */
   readonly systemPromptPath: string;
-  readonly jsonSchema: Readonly<Record<string, unknown>>;
+  /**
+   * Closed JSON Schema for structured_output seats.
+   * Optional: omit for prose-exit seats (#959 navigator) so the model may speak free text.
+   */
+  readonly jsonSchema?: Readonly<Record<string, unknown>>;
   /** Absolute path to host-native MCP config JSON; omitted when no AK MCP servers. */
   readonly mcpConfigPath?: string;
   readonly model?: string;
@@ -99,9 +103,10 @@ export function headlessTurnArgs(options: {
     ...description.fixedArgs,
     description.systemPromptFlag,
     options.systemPromptPath,
-    description.jsonSchemaFlag,
-    JSON.stringify(options.jsonSchema),
   ];
+  if (options.jsonSchema !== undefined) {
+    args.push(description.jsonSchemaFlag, JSON.stringify(options.jsonSchema));
+  }
   if (options.pluginDir) args.push("--plugin-dir", options.pluginDir);
   if (options.mcpConfigPath !== undefined && options.mcpConfigPath !== "") {
     args.push(description.mcpConfigFlag, options.mcpConfigPath);
@@ -145,7 +150,7 @@ function codexTomlStringTable(entries: Readonly<Record<string, string>>): string
  * Free-form JSON leaf for Type.Unknown under Codex strict transport.
  * Strict rejects bare untyped nodes and root-level additionalProperties:true;
  * a $defs anyOf of JSON values (with nested additionalProperties as $ref)
- * is accepted and keeps array/object receipts expressible (navigator candidates).
+ * is accepted and keeps array/object receipts expressible.
  * Package code still does not validate or reject the receipt against schema.
  */
 const CODEX_JSON_VALUE_DEF = "codexJsonValue";
@@ -398,8 +403,11 @@ function codexMcpConfigArgs(
 export function codexTurnArgs(options: {
   /** Absolute path for `-c model_instructions_file=…`. */
   readonly systemPromptPath: string;
-  /** Absolute path for `--output-schema` (closed transport schema). */
-  readonly outputSchemaPath: string;
+  /**
+   * Absolute path for `--output-schema` (closed transport schema).
+   * Optional: omit for prose-exit seats (#959 navigator) so agent_message stays free text.
+   */
+  readonly outputSchemaPath?: string;
   readonly mcpServers: readonly Readonly<Record<string, unknown>>[];
   readonly model?: string;
   readonly effort?: string;
@@ -441,7 +449,9 @@ export function codexTurnArgs(options: {
   }
 
   args.push("-c", `model_instructions_file=${codexTomlString(options.systemPromptPath)}`);
-  args.push("--output-schema", options.outputSchemaPath);
+  if (options.outputSchemaPath !== undefined) {
+    args.push("--output-schema", options.outputSchemaPath);
+  }
   args.push(...codexMcpConfigArgs(options.mcpServers));
 
   if (options.model !== undefined && options.model !== "") {

package/src/headless-host/role-turn-host.ts

@@ -39,6 +39,7 @@ import {
   isPlainObject,
   type HeadlessHostDescription,
 } from "./description.ts";
+import { NAVIGATOR_OUTPUT_TOOL_NAME } from "../package-contracts/navigator-output.ts";
 
 export type HeadlessRoleTurnHostConfig = Readonly<{
   description: HeadlessHostDescription;
@@ -406,7 +407,8 @@ function terminalFromSpawned(
 function buildTurnArgs(options: {
   readonly description: HeadlessHostDescription;
   readonly systemPromptPath: string;
-  readonly jsonSchema: Readonly<Record<string, unknown>>;
+  /** Closed schema; omit for #959 navigator prose-exit seats. */
+  readonly jsonSchema?: Readonly<Record<string, unknown>>;
   readonly mcpServers: readonly Readonly<Record<string, unknown>>[];
   readonly mcpConfigPath?: string;
   readonly outputSchemaPath?: string;
@@ -422,10 +424,10 @@ function buildTurnArgs(options: {
     if (options.sessionKind === "resume" && !options.sessionId) {
       throw new Error("codex resume requires a bound thread_id");
     }
-    if (options.outputSchemaPath === undefined) throw new Error("codex requires an output schema path");
+    // #959: prose-exit seats (navigator) omit --output-schema; other seats still require it.
     return codexTurnArgs({
       systemPromptPath: options.systemPromptPath,
-      outputSchemaPath: options.outputSchemaPath,
+      ...(options.outputSchemaPath === undefined ? {} : { outputSchemaPath: options.outputSchemaPath }),
       mcpServers: options.mcpServers,
       ...(options.model === undefined ? {} : { model: options.model }),
       ...(options.effort === undefined ? {} : { effort: options.effort }),
@@ -443,7 +445,8 @@ function buildTurnArgs(options: {
   return headlessTurnArgs({
     description: options.description,
     systemPromptPath: options.systemPromptPath,
-    jsonSchema: options.jsonSchema,
+    // #959: navigator omits --json-schema so free-form prose is a lawful exit.
+    ...(options.jsonSchema === undefined ? {} : { jsonSchema: options.jsonSchema }),
     mcpConfigPath: options.mcpConfigPath,
     ...(options.model === undefined ? {} : { model: options.model }),
     ...(options.effort === undefined ? {} : { effort: options.effort }),
@@ -482,12 +485,15 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
         ? (prompt) => applyCodexSkillInvocation(request.methods, prompt)
         : (prompt) => prompt;
       if (codex) {
-        outputSchemaPath = join(request.runDirectory, "headless-output-schema.json");
-        await writeFile(
-          outputSchemaPath,
-          `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}\n`,
-          "utf8",
-        );
+        // #959: navigator is a prose-exit seat — no closed output-schema.
+        if (prepared.terminatingToolName !== NAVIGATOR_OUTPUT_TOOL_NAME) {
+          outputSchemaPath = join(request.runDirectory, "headless-output-schema.json");
+          await writeFile(
+            outputSchemaPath,
+            `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}\n`,
+            "utf8",
+          );
+        }
       } else {
         mcpConfigPath = join(request.runDirectory, "headless-mcp-config.json");
         await writeFile(
@@ -517,7 +523,10 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
             args = buildTurnArgs({
               description: config.description,
               systemPromptPath,
-              jsonSchema: prepared.jsonSchema,
+              // #959: navigator prose exit — no closed JSON schema on claude either.
+              ...(prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME
+                ? {}
+                : { jsonSchema: prepared.jsonSchema }),
               mcpServers: prepared.mcpServers,
               ...(mcpConfigPath === undefined ? {} : { mcpConfigPath }),
               ...(outputSchemaPath === undefined ? {} : { outputSchemaPath }),
@@ -657,6 +666,20 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               });
             }
 
+            // #959: navigator prose exit — final agent_message is presented as-is.
+            // Empty text is not a lawful accepted receipt (align pi no_receipt / loud empty).
+            if (prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME) {
+              if (observation.finalMessage.trim() === "") {
+                return terminalFromSpawned(spawned, {
+                  cause: "output",
+                  identity: { name: "HeadlessEmptyOutput", code: "empty-stdout" },
+                  diagnostic: spawned.stderr.trim() || "codex exec produced empty agent_message",
+                  details: { sessionId, exitCode: spawned.code },
+                });
+              }
+              await prepared.ingestStructuredOutput({ prose: observation.finalMessage });
+              return { status: "delivered", stderr: spawned.stderr };
+            }
             let receipt: unknown;
             try {
               receipt = JSON.parse(observation.finalMessage);
@@ -716,6 +739,14 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
 
           if (envelope.structured_output !== undefined) {
             await prepared.ingestStructuredOutput(envelope.structured_output);
+          } else if (
+            prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME
+            && typeof envelope.result === "string"
+            && envelope.result.trim() !== ""
+          ) {
+            // #959: claude prose exit — free-form result text is the receipt body
+            // when structured_output is absent (json-schema omitted for navigator).
+            await prepared.ingestStructuredOutput({ prose: envelope.result });
           }
           return { status: "delivered", stderr: spawned.stderr };
         },