@akagilnc/pi-workflow-roles 0.1.3758 → 0.1.3783

package/src/collector-target.ts

@@ -0,0 +1,207 @@
+/**
+ * #676 D1: Collector admission target recognition on structured git context.
+ * Explicit PR wins (no association queries). Otherwise gather online candidates
+ * from structured upstream head and HEAD commit association only. Deduped unique
+ * → bind; many → require explicit --pr; zero → unbound so the role can decide
+ * from task materials via the bind-target business tool. No task-text scrape,
+ * no second state machine. Git/config/transport failures keep true cause.
+ */
+import { execFileSync } from "node:child_process";
+
+import type { CollectorRepository } from "./collector-config.ts";
+import {
+  createGhApiRunner,
+  listPullRequestNumbersByCommit,
+  listPullRequestNumbersByHead,
+} from "./collector-github.ts";
+import { CliUsageError } from "./public-cli/cli-errors.ts";
+import {
+  ownerFromGitHubRemoteUrl,
+  ownerRepoFromGitHubRemoteUrl,
+} from "./public-cli/github-remote.ts";
+
+export type ResolveCollectorTargetInput = {
+  readonly projectRoot: string;
+  readonly repository: CollectorRepository;
+  /** Caller-provided PR number when already explicit. */
+  readonly explicitPrNumber?: number;
+};
+
+export type CollectorTargetResolution =
+  | { readonly kind: "bound"; readonly prNumber: number }
+  | { readonly kind: "unbound" };
+
+function ambiguousTarget(detail: string, cause?: unknown): never {
+  throw new CliUsageError(
+    `collector target is ambiguous: ${detail}; pass an explicit --pr`,
+    cause === undefined ? undefined : { cause },
+  );
+}
+
+/** Real git failure — not target ambiguity. Propagates with true cause on exit 1. */
+function gitFailure(detail: string, cause: unknown): never {
+  throw new Error(`collector git failed: ${detail}`, {
+    cause: cause instanceof Error ? cause : new Error(String(cause)),
+  });
+}
+
+function gitText(projectRoot: string, args: readonly string[]): string {
+  return execFileSync("git", [...args], {
+    cwd: projectRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+/** git config --get exit 1 = key absent; other failures keep true cause. */
+function isGitConfigMissing(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const status = (error as { status?: unknown }).status;
+  return status === 1;
+}
+
+function readCurrentBranch(projectRoot: string): string {
+  try {
+    return gitText(projectRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  } catch (error) {
+    gitFailure("cannot read current git branch", error);
+  }
+}
+
+function readHeadSha(projectRoot: string): string {
+  try {
+    return gitText(projectRoot, ["rev-parse", "HEAD"]);
+  } catch (error) {
+    gitFailure("cannot read current HEAD", error);
+  }
+}
+
+/**
+ * Head ref short name from branch.<name>.merge (refs/heads/<ref> or bare ref).
+ * Non-heads merge forms are not a structured head binding.
+ */
+function headRefFromMerge(merge: string): string | undefined {
+  const trimmed = merge.trim();
+  if (trimmed.length === 0) return undefined;
+  if (trimmed.startsWith("refs/heads/")) {
+    const ref = trimmed.slice("refs/heads/".length);
+    return ref.length > 0 ? ref : undefined;
+  }
+  // Reject other refs/* (e.g. refs/remotes/…) — not a PR head ref binding.
+  if (trimmed.startsWith("refs/")) return undefined;
+  return trimmed;
+}
+
+/**
+ * Real upstream head owner + head ref from branch.<name>.remote/merge when configured.
+ * Missing config keys = not configured (undefined). Config/remote execution failures
+ * throw with true cause — never swallowed as "no upstream, keep fallback".
+ */
+function readUpstreamHeadBinding(
+  projectRoot: string,
+  branch: string,
+): { readonly headOwner: string; readonly headRef: string } | undefined {
+  let remote: string | undefined;
+  try {
+    remote = gitText(projectRoot, ["config", "--get", `branch.${branch}.remote`]);
+  } catch (error) {
+    if (isGitConfigMissing(error)) remote = undefined;
+    else gitFailure(`cannot read branch.${branch}.remote`, error);
+  }
+  if (remote === undefined || remote.length === 0) return undefined;
+
+  let merge: string | undefined;
+  try {
+    merge = gitText(projectRoot, ["config", "--get", `branch.${branch}.merge`]);
+  } catch (error) {
+    if (isGitConfigMissing(error)) merge = undefined;
+    else gitFailure(`cannot read branch.${branch}.merge`, error);
+  }
+  if (merge === undefined || merge.length === 0) return undefined;
+
+  const headRef = headRefFromMerge(merge);
+  if (headRef === undefined) return undefined;
+
+  let remoteUrl: string;
+  try {
+    remoteUrl = gitText(projectRoot, ["remote", "get-url", remote]);
+  } catch (error) {
+    gitFailure(`cannot read remote URL for ${remote}`, error);
+  }
+  const headOwner = ownerFromGitHubRemoteUrl(remoteUrl);
+  if (headOwner === undefined) return undefined;
+  return { headOwner, headRef };
+}
+
+/**
+ * Resolve the Collector PR target without guessing from task text.
+ * - Explicit `--pr` → that number (no association queries).
+ * - Otherwise: full online candidates (upstream head + HEAD commit), deduped.
+ * - Exactly 1 → bound. >1 → require explicit `--pr`. 0 → unbound (role bind tool).
+ * - Git/config/transport/HTTP/JSON failures propagate with true cause.
+ */
+export async function resolveCollectorTarget(
+  input: ResolveCollectorTargetInput,
+): Promise<CollectorTargetResolution> {
+  if (input.explicitPrNumber !== undefined) {
+    return { kind: "bound", prNumber: input.explicitPrNumber };
+  }
+
+  const branch = readCurrentBranch(input.projectRoot);
+  const detached = branch.length === 0 || branch === "HEAD";
+
+  // Detached HEAD cannot associate via branch head; commit association still runs.
+  const runner = createGhApiRunner();
+  const { owner, repo } = input.repository;
+  const numbers: number[] = [];
+
+  if (!detached) {
+    const headSha = readHeadSha(input.projectRoot);
+    const upstream = readUpstreamHeadBinding(input.projectRoot, branch);
+
+    // Prefer structured head owner:ref from real upstream merge binding (fork-safe).
+    if (upstream !== undefined) {
+      numbers.push(
+        ...(await listPullRequestNumbersByHead(runner, {
+          owner,
+          repo,
+          headOwner: upstream.headOwner,
+          headRef: upstream.headRef,
+        })),
+      );
+    }
+    // Always also take commit association — never let a sole upstream hit hide a conflict.
+    numbers.push(
+      ...(await listPullRequestNumbersByCommit(runner, {
+        owner,
+        repo,
+        commitSha: headSha,
+      })),
+    );
+  } else {
+    // Detached: commit association only (no branch head).
+    const headSha = readHeadSha(input.projectRoot);
+    numbers.push(
+      ...(await listPullRequestNumbersByCommit(runner, {
+        owner,
+        repo,
+        commitSha: headSha,
+      })),
+    );
+  }
+
+  const unique = [...new Set(numbers)];
+
+  if (unique.length === 1) {
+    return { kind: "bound", prNumber: unique[0]! };
+  }
+  if (unique.length > 1) {
+    ambiguousTarget(
+      `multiple PRs associated with context: ${unique.join(", ")}`,
+    );
+  }
+  // Zero structured git hits — leave unbound so the role can decide from materials.
+  return { kind: "unbound" };
+}
+
+export { ownerRepoFromGitHubRemoteUrl, ownerFromGitHubRemoteUrl };

package/src/collector-tool-schemas.ts

@@ -1,5 +1,6 @@
 import { Type, type Static } from "typebox";
 import { COLLECTOR_ELIGIBILITY_MS } from "./collector-evidence.ts";
+import { openToolObject } from "./open-tool-schema.ts";
 import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.ts";
 
 export const collectorObserveArgsSchema = Type.Object({}, { additionalProperties: false });
@@ -15,31 +16,77 @@ export const collectorWaitArgsSchema = Type.Object({
 }, { additionalProperties: false });
 
 /**
- * #641 chain①: the collector LLM does the splitting/classification (#245:
- * 他自己就是llm为什么不能读不能拆). Findings are submitted as pointer refs into
- * the stored evidence; the runtime enriches each with the machine pointer
- * (repo/PR/comment id/url/author/kind/时间) and validates resolvability.
- * Category is a short LLM classification label, never a body transcription.
+ * #676 A: role-decided target bind. The model judges task materials and submits
+ * the chosen PR and/or issue identity; runtime only performs online association
+ * for the role-chosen ticket — never scrapes task text to lock a target.
  */
-export const collectorFindingArgsSchema = Type.Object({
-  evidenceId: Type.String({ minLength: 1, description: "observe 返回的材料证据 id（evidenceId）" }),
-  category: Type.Optional(Type.String({ minLength: 1, maxLength: 200, description: "该 finding 的简短归类标签；需要头部之外的正文时先用 ak_collector_read 开卷再判读，不得誊写评论正文" })),
-}, { additionalProperties: false });
-
-export const collectorOutputBaseSchema = Type.Object({
-  findings: Type.Optional(Type.Array(collectorFindingArgsSchema, {
-    description: "本次收集到的逐条 findings；零 finding 的模板通知不得进入。正常完工无 finding 时省略。",
+export const collectorBindTargetArgsSchema = Type.Object({
+  prNumber: Type.Optional(Type.Unknown({
+    description: "角色判定的本仓 PR 号（正整数）。与 issueNumber 二选一或同指唯一目标。形状指引，非 schema 闸。",
   })),
-}, { additionalProperties: true, description: "正常完工提交空对象 {}；仅在基础设施真实失败时才填写 infrastructureFailure，无失败时必须省略该字段。" });
+  issueNumber: Type.Optional(Type.Unknown({
+    description: "角色判定的本仓 issue 号（正整数）；runtime 经线上关联解析唯一 PR。形状指引，非 schema 闸。",
+  })),
+}, { additionalProperties: true });
+
+/**
+ * #641 chain① / #676 C / ADR 0057: nested finding item declarations for model
+ * guidance. Host must not pure-shape-reject the envelope (第 0 条). Runtime binds
+ * resolvable evidence pointers only; unprojected content stays distinguishable.
+ */
+const collectorFindingItemDeclaration = (() => {
+  // Nested declarations for model guidance only — open required so host cannot
+  // pure-shape-reject missing optional fields (第 0 条 / ADR 0057 / #676 C).
+  const item = Type.Object(
+    {
+      evidenceId: Type.Unknown({
+        description: "observe 返回的材料指针（必填语义）",
+      }),
+      category: Type.Unknown({
+        description: "简短归类标签，不是摘要",
+      }),
+      summary: Type.Unknown({
+        description: "哪个 bot、什么问题的摘要；不誊抄正文",
+      }),
+    },
+    {
+      additionalProperties: true,
+      description:
+        "单条 finding 指针：evidenceId + 可选 category/summary。形状指引，非 schema 闸。",
+    },
+  );
+  (item as unknown as { required: string[] }).required = [];
+  return item;
+})();
+
+/**
+ * Field declarations + descriptions are guidance for the model — host must not
+ * pure-shape-reject the envelope (第 0 条 / ADR 0057).
+ */
+export const collectorOutputBaseSchema = openToolObject(
+  Type.Object({
+    // No root type:array — host must not shape-reject non-array findings (#676 C).
+    // Nested item declarations ride `items` for registration preservation (ADR 0057).
+    findings: Type.Unsafe({
+      description:
+        "本次收集到的逐条 findings（指针数组为规范形）。零 finding 的模板通知不得进入；正常完工无 finding 时省略。形状指引，非 schema 闸。",
+      items: collectorFindingItemDeclaration,
+    }),
+    unfinishedReasons: Type.Unknown({
+      description:
+        "未完成原因字符串数组（额度/故障/等待届满等现场依据）；不得把未完成表述为无问题。无可报告时省略。形状指引，非 schema 闸。",
+    }),
+  }),
+);
 
 /** Runtime owns the observed evidence; the model submits findings and signals sole-final submission. */
 export const collectorOutputArgsSchema = withInfrastructureFailureDeclaration(
   collectorOutputBaseSchema,
 );
-(collectorOutputArgsSchema as unknown as { required: string[] }).required = [];
 
 export type CollectorObserveArgs = Static<typeof collectorObserveArgsSchema>;
 export type CollectorRequestArgs = Static<typeof collectorRequestArgsSchema>;
 export type CollectorReadArgs = Static<typeof collectorReadArgsSchema>;
 export type CollectorWaitArgs = Static<typeof collectorWaitArgsSchema>;
+export type CollectorBindTargetArgs = Static<typeof collectorBindTargetArgsSchema>;
 export type CollectorOutputArgs = Static<typeof collectorOutputArgsSchema>;

package/src/headless-host/description.ts

@@ -0,0 +1,123 @@
+/**
+ * One headless CLI host description (#645 / #752).
+ * Every host-specific value the generic headless adapter needs — binary, argv
+ * shape, session binding — is data here; lifecycle stays one copy so #646 codex
+ * is another row, not a fork.
+ */
+import { join } from "node:path";
+
+export type HeadlessHostDescription = Readonly<{
+  /** Binary path segments relative to the operator home. */
+  binaryFromHome: readonly string[];
+  /** Durable session-id binding filename beside the session principal. */
+  sessionBindingFile: string;
+  /**
+   * Host-native print-mode flags that never change per turn (no prompt).
+   * Model / effort / system-prompt / schema / session / resume / mcp-config
+   * are composed by the adapter from the turn request — not listed here.
+   */
+  fixedArgs: readonly string[];
+  /** Print-mode flag that takes the user prompt as its value (e.g. `-p`). */
+  promptFlag: string;
+  /** CLI flag for the seat model (e.g. `--model`). */
+  modelFlag: string;
+  /** CLI flag for the seat thinking level (e.g. `--effort`); value is opaque pass-through. */
+  effortFlag: string;
+  /**
+   * CLI flag whose value is a path to the system-prompt file
+   * (`--system-prompt-file`). File delivery keeps ARG_MAX off the critical path.
+   */
+  systemPromptFlag: string;
+  /** CLI flag whose value is a JSON Schema document string. */
+  jsonSchemaFlag: string;
+  /** CLI flag whose value is a path or JSON string for MCP servers. */
+  mcpConfigFlag: string;
+  /** CLI flag to mint a fresh session id (initial turn). */
+  sessionIdFlag: string;
+  /** CLI flag to resume a prior session id. */
+  resumeFlag: string;
+}>;
+
+/** Absolute agent binary for one operator home. */
+export function resolveHeadlessBinary(
+  description: HeadlessHostDescription,
+  operatorHome: string,
+): string {
+  return join(operatorHome, ...description.binaryFromHome);
+}
+
+/**
+ * Build one headless CLI argv for a single process turn.
+ * Shape: `<promptFlag> <prompt> <fixedArgs…> <system/schema/mcp/model/effort/session…>`.
+ */
+export function headlessTurnArgs(options: {
+  readonly description: HeadlessHostDescription;
+  readonly prompt: string;
+  /** Absolute path written by the adapter; paired with `systemPromptFlag`. */
+  readonly systemPromptPath: string;
+  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;
+  readonly effort?: string;
+  /** Fresh session: pass as session id. Resume: pass as resume id. */
+  readonly session: { readonly kind: "new"; readonly id: string } | { readonly kind: "resume"; readonly id: string };
+}): string[] {
+  const { description } = options;
+  const args: string[] = [
+    description.promptFlag,
+    options.prompt,
+    ...description.fixedArgs,
+    description.systemPromptFlag,
+    options.systemPromptPath,
+    description.jsonSchemaFlag,
+    JSON.stringify(options.jsonSchema),
+  ];
+  if (options.mcpConfigPath !== undefined && options.mcpConfigPath !== "") {
+    args.push(description.mcpConfigFlag, options.mcpConfigPath);
+  }
+  if (options.model !== undefined && options.model !== "") {
+    args.push(description.modelFlag, options.model);
+  }
+  if (options.effort !== undefined && options.effort !== "") {
+    args.push(description.effortFlag, options.effort);
+  }
+  if (options.session.kind === "new") {
+    args.push(description.sessionIdFlag, options.session.id);
+  } else {
+    args.push(description.resumeFlag, options.session.id);
+  }
+  return args;
+}
+
+/**
+ * Project shared-envelope MCP server rows into Claude `--mcp-config` JSON.
+ * Env stays a plain object (Claude CLI shape); ACP rows use `{name,value}[]`.
+ */
+export function headlessMcpConfigDocument(
+  mcpServers: readonly Readonly<Record<string, unknown>>[],
+): Readonly<{ mcpServers: Readonly<Record<string, Readonly<Record<string, unknown>>>> }> {
+  const servers: Record<string, Record<string, unknown>> = {};
+  for (const row of mcpServers) {
+    const name = typeof row.name === "string" ? row.name : undefined;
+    const command = typeof row.command === "string" ? row.command : undefined;
+    if (name === undefined || name === "" || command === undefined || command === "") continue;
+    const entry: Record<string, unknown> = { command };
+    if (Array.isArray(row.args)) entry.args = row.args;
+    if (Array.isArray(row.env)) {
+      const env: Record<string, string> = {};
+      for (const item of row.env) {
+        if (typeof item !== "object" || item === null) continue;
+        const record = item as { name?: unknown; value?: unknown };
+        if (typeof record.name === "string" && typeof record.value === "string") {
+          env[record.name] = record.value;
+        }
+      }
+      if (Object.keys(env).length > 0) entry.env = env;
+    } else if (typeof row.env === "object" && row.env !== null && !Array.isArray(row.env)) {
+      entry.env = row.env;
+    }
+    servers[name] = entry;
+  }
+  return Object.freeze({ mcpServers: Object.freeze(servers) });
+}

package/src/headless-host/production-host.ts

@@ -0,0 +1,75 @@
+/**
+ * Production composition for the generic headless CLI RoleTurnHost (#645).
+ * Agent subprocesses inherit the operator home and credentials in place.
+ * No HOME rewrite, no isolated home, no credential parameters — CLI owns auth.
+ * Sitian records on the run are the dossier; host private sessions stay private.
+ *
+ * Intermediate AK tools ride the shared envelope MCP relay via host-native
+ * `--mcp-config` under `--strict-mcp-config`. The terminating receipt is the
+ * host-native `--json-schema` / structured_output schema channel only
+ * (#750 submission-tool-is-schema-channel) — terminating tool is not listed on MCP.
+ */
+import { randomUUID } from "node:crypto";
+
+import type { DurablePrincipalAuthority, RoleTurnHost } from "../host-contracts.ts";
+import { createAcpRoleRuntimeDependencies } from "../acp-host/production-host.ts";
+import { prepareAcpRoleEnvelope } from "../acp-host/role-envelope.ts";
+import { createAcpSessionIdentityAuthority } from "../acp-host/session-identity.ts";
+import { resolveHeadlessBinary, type HeadlessHostDescription } from "./description.ts";
+import { createHeadlessRoleTurnHost } from "./role-turn-host.ts";
+
+export type ProductionHeadlessHostOptions = Readonly<{
+  packageRoot: string;
+  principalAuthority: DurablePrincipalAuthority;
+  description: HeadlessHostDescription;
+}>;
+
+/**
+ * Assemble a production headless RoleTurnHost from the shared envelope prepare
+ * (MCP relay for AK tools) and one host description row. Binary is resolved
+ * from each turn's operator home (`request.home`).
+ */
+export function createProductionHeadlessRoleTurnHost(
+  options: ProductionHeadlessHostOptions,
+): RoleTurnHost {
+  const { packageRoot, principalAuthority, description } = options;
+  const sessionIdentity = createAcpSessionIdentityAuthority(
+    principalAuthority,
+    description.sessionBindingFile,
+  );
+  const roleRuntimeDependencies = createAcpRoleRuntimeDependencies(packageRoot);
+
+  const innerFor = (operatorHome: string): RoleTurnHost =>
+    createHeadlessRoleTurnHost({
+      description,
+      sessionIdentity,
+      binary: resolveHeadlessBinary(description, operatorHome),
+      env: {
+        ...process.env,
+        AK_PACKAGE_ROOT: packageRoot,
+      },
+      prepare: (request) =>
+        prepareAcpRoleEnvelope({
+          request,
+          dependencies: roleRuntimeDependencies,
+          sessionFile: sessionIdentity.resolveSessionFile(request.principal),
+          // Same MCP relay as ACP so intermediate AK tools stay reachable;
+          // headless adapter projects the row into --mcp-config.
+          socketPath: `/tmp/ak-headless-mcp-${randomUUID()}.sock`,
+          // Schema channel owns the terminating receipt; hide it from MCP list.
+          listTerminatingToolOnMcp: false,
+        }),
+    });
+
+  let cachedHome: string | undefined;
+  let cachedHost: RoleTurnHost | undefined;
+  return {
+    executeTurn(request) {
+      if (cachedHost === undefined || cachedHome !== request.home) {
+        cachedHome = request.home;
+        cachedHost = innerFor(request.home);
+      }
+      return cachedHost.executeTurn(request);
+    },
+  };
+}