@akagilnc/pi-workflow-roles 0.1.3758 → 0.1.3783

package/dist/collector-target.js

@@ -0,0 +1,169 @@
+/**
+ * #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 { createGhApiRunner, listPullRequestNumbersByCommit, listPullRequestNumbersByHead, } from "./collector-github.js";
+import { CliUsageError } from "./public-cli/cli-errors.js";
+import { ownerFromGitHubRemoteUrl, ownerRepoFromGitHubRemoteUrl, } from "./public-cli/github-remote.js";
+function ambiguousTarget(detail, cause) {
+    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, cause) {
+    throw new Error(`collector git failed: ${detail}`, {
+        cause: cause instanceof Error ? cause : new Error(String(cause)),
+    });
+}
+function gitText(projectRoot, args) {
+    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) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const status = error.status;
+    return status === 1;
+}
+function readCurrentBranch(projectRoot) {
+    try {
+        return gitText(projectRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    }
+    catch (error) {
+        gitFailure("cannot read current git branch", error);
+    }
+}
+function readHeadSha(projectRoot) {
+    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) {
+    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, branch) {
+    let remote;
+    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;
+    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;
+    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) {
+    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 = [];
+    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/dist/collector-tool-schemas.js

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { COLLECTOR_ELIGIBILITY_MS } from "./collector-evidence.js";
+import { openToolObject } from "./open-tool-schema.js";
 import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.js";
 export const collectorObserveArgsSchema = Type.Object({}, { additionalProperties: false });
 export const collectorRequestArgsSchema = Type.Object({
@@ -13,21 +14,57 @@ export const collectorWaitArgsSchema = Type.Object({
     durationMs: Type.Integer({ minimum: 1, maximum: COLLECTOR_ELIGIBILITY_MS, description: "等待毫秒；单次上限五分钟且不超剩余资格" }),
 }, { 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.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.required = [];

package/dist/headless-host/description.js

@@ -0,0 +1,77 @@
+/**
+ * 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";
+/** Absolute agent binary for one operator home. */
+export function resolveHeadlessBinary(description, operatorHome) {
+    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) {
+    const { description } = options;
+    const args = [
+        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) {
+    const servers = {};
+    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 = { command };
+        if (Array.isArray(row.args))
+            entry.args = row.args;
+        if (Array.isArray(row.env)) {
+            const env = {};
+            for (const item of row.env) {
+                if (typeof item !== "object" || item === null)
+                    continue;
+                const record = item;
+                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/dist/headless-host/mcp-relay.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { connect } from "node:net";
+import { createInterface } from "node:readline";
+
+const socketPath = process.env.AK_ACP_MCP_SOCKET;
+const token = process.env.AK_ACP_MCP_TOKEN;
+if (!socketPath || !token) throw new Error("AK ACP MCP relay identity is missing");
+
+const upstream = connect(socketPath);
+const waiters = new Map();
+let nextId = 0;
+let terminalError;
+let shutdownRequested = false;
+let exiting = false;
+let inFlight = 0;
+let pendingStdout = 0;
+
+function exitStatus() {
+  return terminalError === undefined ? 0 : 1;
+}
+
+function maybeExit() {
+  if (!shutdownRequested || exiting) return;
+  if (inFlight > 0 || waiters.size > 0 || pendingStdout > 0) return;
+  exiting = true;
+  stdinLines.close();
+  if (!upstream.destroyed) upstream.end();
+  process.exit(exitStatus());
+}
+
+function requestShutdown() {
+  shutdownRequested = true;
+  maybeExit();
+}
+
+function settle(error) {
+  if (terminalError !== undefined) return;
+  terminalError = error;
+  for (const waiter of waiters.values()) waiter.reject(error);
+  waiters.clear();
+  maybeExit();
+}
+
+upstream.on("error", (error) => settle(error));
+upstream.on("close", () => {
+  // Shutdown may already be requested (stdin EOF) while an RPC is still
+  // in flight. Outstanding waiters must still settle, or drain never ends.
+  if (!exiting) settle(new Error("AK ACP MCP upstream closed"));
+  maybeExit();
+});
+createInterface({ input: upstream }).on("line", (line) => {
+  let message;
+  try { message = JSON.parse(line); }
+  catch (error) { settle(error); upstream.destroy(); return; }
+  const waiter = waiters.get(message.id);
+  if (waiter === undefined) return;
+  waiters.delete(message.id);
+  if (message.error !== undefined) {
+    const error = new Error(typeof message.error.message === "string" ? message.error.message : "AK ACP MCP relay failure");
+    error.code = message.error.code;
+    error.cause = message.error;
+    waiter.reject(error);
+  } else waiter.resolve(message.result);
+  maybeExit();
+});
+function request(method, params = {}) {
+  if (terminalError !== undefined) return Promise.reject(terminalError);
+  const id = ++nextId;
+  return new Promise((resolve, reject) => {
+    waiters.set(id, { resolve, reject });
+    upstream.write(`${JSON.stringify({ id, token, method, params })}\n`, (error) => {
+      if (error === null || error === undefined) return;
+      const waiter = waiters.get(id);
+      if (waiter === undefined) return;
+      waiters.delete(id);
+      waiter.reject(error);
+      maybeExit();
+    });
+  });
+}
+function send(message) {
+  const payload = `${JSON.stringify(message)}\n`;
+  pendingStdout += 1;
+  process.stdout.write(payload, (error) => {
+    pendingStdout -= 1;
+    if (error) settle(error);
+    maybeExit();
+  });
+}
+function ok(id, result) { if (id !== undefined) send({ jsonrpc: "2.0", id, result }); }
+function fail(id, error) { if (id !== undefined) send({ jsonrpc: "2.0", id, error: { code: -32000, message: error instanceof Error ? error.message : String(error) } }); }
+
+const stdinLines = createInterface({ input: process.stdin });
+stdinLines.on("line", async (line) => {
+  inFlight += 1;
+  try {
+    let message;
+    try { message = JSON.parse(line); }
+    catch (error) { fail(null, error); return; }
+    try {
+      if (message.method === "initialize") {
+        ok(message.id, { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "ak-role-envelope", version: "1" } });
+      } else if (message.method === "ping") {
+        ok(message.id, {});
+      } else if (message.method === "tools/list") {
+        ok(message.id, await request("tools/list"));
+      } else if (message.method === "tools/call") {
+        ok(message.id, await request("tools/call", message.params));
+      } else if (message.method !== "notifications/initialized" && message.method !== "initialized") {
+        fail(message.id, new Error(`Unsupported MCP method: ${String(message.method)}`));
+      }
+    } catch (error) { fail(message.id, error); }
+  } finally {
+    inFlight -= 1;
+    maybeExit();
+  }
+});
+stdinLines.on("close", requestShutdown);
+process.on("SIGTERM", requestShutdown);