opencode-herdr-orchestration 0.2.0 → 0.3.0

package/src/index.js

@@ -1,12 +1,26 @@
 import { tool } from "@opencode-ai/plugin";
 
-import { createAgents, mergeAgent, STATE_TOOL_ACCESS, STATE_TOOLS } from "./agents.js";
+import {
+  createAgents,
+  DEVELOPER_AGENT,
+  mergeAgent,
+  OWNERSHIP_TOOL_ACCESS,
+  OWNERSHIP_TOOLS,
+  RAW_STEERING_TOOL_ACCESS,
+  RAW_STEERING_TOOLS,
+  SHEPHERD_PHASES,
+  STATE_TOOL_ACCESS,
+  STATE_TOOLS,
+  STEERING_TOOL_ACCESS,
+  STEERING_TOOLS,
+} from "./agents.js";
 import { createResponseTool } from "./response.js";
 import { createStateService } from "./state.js";
 
 const SESSION_MODES = new Map();
 
 function modeForAgent(agent) {
+  if (agent === DEVELOPER_AGENT) return "developer";
   if (agent === "shepherd") return "shepherd";
   if (agent === "shepherd-governor") return "governor";
   if (agent === "sheepdog") return "sheepdog";
@@ -24,10 +38,14 @@ function stateError(code, message, retryable = false) {
 // tools. Enforcement mirrors STATE_TOOL_ACCESS in src/agents.js: the planning
 // shepherd writes and reads plan artifacts; shepherd-governor and sheepdog
 // read the authoritative plan; sheepdog writes and reads execution artifacts.
-// Artifacts are durable Markdown files under the repository's shared Git
-// common directory, so linked worktrees share state while separate clones
-// never do. The state service invokes only read-only `git rev-parse`; it
-// never writes arbitrary Git metadata.
+// Artifacts are durable Markdown files under the canonical
+// `<git-common-dir>/flocky` state root in the repository's shared Git common
+// directory, so linked worktrees share state while separate clones never do.
+// Legacy `<git-common-dir>/herdr` artifacts are reconciled into the canonical
+// root before every plan or execution operation — copied, accepted, or failed
+// closed on conflict — and the legacy root is never auto-deleted. The state
+// service invokes only read-only `git rev-parse`; it never writes arbitrary
+// Git metadata.
 export function createStateTools(stateOptions = {}) {
   const state = createStateService(stateOptions);
 
@@ -103,10 +121,236 @@ export function createStateTools(stateOptions = {}) {
   return tools;
 }
 
+// Developer steering submission (M2, Option A, trusted Developer only).
+// The sole submitter is the explicit non-flock `developer` context. The
+// allowlist holds only Developer; every flock role plus unknown, ambiguous,
+// none, and unset are denied fail-closed with no filesystem write. Developer
+// is never inferred from session mode, directory, environment text, or prompt
+// content: only an exact `context.agent === "developer"` passes. The runtime
+// check stays authoritative over static per-agent permission overrides.
+export function createSteeringTools(stateOptions = {}) {
+  const state = createStateService(stateOptions);
+  const name = STEERING_TOOLS.submit;
+  return {
+    [name]: tool({
+      description:
+        "Submit bounded Developer steering for one Plan ID target. Developer context only; flock roles are denied. Provide explicit planId, or omit it only when exactly one active steering target exists.",
+      args: {
+        planId: tool.schema
+          .string()
+          .optional()
+          .describe("Explicit steering target Plan ID; required unless exactly one active target exists."),
+        content: tool.schema
+          .string()
+          .min(1)
+          .describe("Bounded steering content; at most 8192 UTF-8 bytes."),
+      },
+      async execute(args, context) {
+        const allowed = STEERING_TOOL_ACCESS.get(name);
+        if (!allowed?.has(context?.agent)) {
+          return JSON.stringify(
+            stateError(
+              "UNAUTHORIZED_AGENT",
+              `Agent ${context?.agent ?? "unknown"} may not use ${name}.`,
+            ),
+          );
+        }
+        const result = await state.submitSteering(args);
+        context.metadata({
+          title: result.ok ? `${name}: ${result.entry.planId}#${result.entry.sequence}` : `${name}: ${result.error.code}`,
+          metadata: result.ok
+            ? { planId: result.entry.planId, steeringId: result.entry.id, sequence: result.entry.sequence }
+            : { error: result.error.code },
+        });
+        return JSON.stringify(result);
+      },
+    }),
+  };
+}
+
+// Shepherd-only raw steering plus ownership lifecycle tools (M3).
+// Only `shepherd` and `shepherd-governor` pass the runtime allowlist;
+// sheepdog, grazer, sheep, shearers, developer, unknown, and unset are
+// denied fail-closed with no filesystem write. State-level session plus
+// generation fencing stays authoritative inside src/state.js (NOT
+// AUTHORITATIVE PHASE for non-owners). Steering never authorizes push,
+// tag, publish, deploy, merge, or any consequential action; existing
+// approvals still required.
+export function createRawSteeringTools(stateOptions = {}) {
+  const state = createStateService(stateOptions);
+  const definitions = [
+    {
+      name: RAW_STEERING_TOOLS.check,
+      description:
+        "Check unread Developer steering for one Plan ID target without loading bodies. Shepherd phases only with authoritative phase, session, and generation; non-owners receive NOT AUTHORITATIVE PHASE.",
+      run: (args) => state.checkSteering(args),
+    },
+    {
+      name: RAW_STEERING_TOOLS.read,
+      description:
+        "Read ordered exact unread Developer steering with no mutation. Shepherd phases only with authoritative phase, session, and generation.",
+      run: (args) => state.readSteering(args),
+    },
+    {
+      name: RAW_STEERING_TOOLS.consume,
+      description:
+        "Consume Developer steering only after the authoritative owner recorded sync disposition for the sync point; idempotent. Shepherd phases only. Steering never authorizes consequential actions.",
+      run: (args) => state.consumeSteering(args),
+    },
+  ];
+  const tools = {};
+  for (const definition of definitions) {
+    tools[definition.name] = tool({
+      description: definition.description,
+      args: {
+        planId: tool.schema.string().describe("Explicit steering target Plan ID."),
+        phase: tool.schema.string().describe("Owner phase: planning or governance."),
+        session: tool.schema.string().describe("Authoritative session fencing the ownership record."),
+        generation: tool.schema.number().int().min(1).describe("Authoritative generation fencing the ownership record."),
+        ...(definition.name === RAW_STEERING_TOOLS.consume
+          ? {
+              ids: tool.schema.array(tool.schema.string()).min(1).max(1000).describe("Steering ids to consume idempotently."),
+              syncPoint: tool.schema.string().describe("Closed sync point whose disposition was recorded before consume."),
+              disposition: tool.schema.string().describe("Closed disposition recorded before consume."),
+            }
+          : {}),
+      },
+      async execute(args, context) {
+        const allowed = RAW_STEERING_TOOL_ACCESS.get(definition.name);
+        if (!allowed?.has(context?.agent)) {
+          return JSON.stringify(
+            stateError(
+              "UNAUTHORIZED_AGENT",
+              `Agent ${context?.agent ?? "unknown"} may not use ${definition.name}.`,
+            ),
+          );
+        }
+        const result = await definition.run(args);
+        context.metadata({
+          title: result.ok ? `${definition.name}: ${args.planId}` : `${definition.name}: ${result.error.code}`,
+          metadata: result.ok ? { planId: args.planId } : { error: result.error.code },
+        });
+        return JSON.stringify(result);
+      },
+    });
+  }
+  return tools;
+}
+
+export function createOwnershipTools(stateOptions = {}) {
+  const state = createStateService(stateOptions);
+  const definitions = [
+    {
+      name: OWNERSHIP_TOOLS.claim,
+      description:
+        "Claim or hand off validated target lifecycle ownership for one Plan ID with session plus generation fencing. Shepherd phases only; generations must increase and both phases cannot race on the same generation.",
+      run: (args) => state.claimOwnership(args),
+    },
+    {
+      name: OWNERSHIP_TOOLS.read,
+      description: "Read the validated lifecycle record for one Plan ID. Shepherd phases only; non-owners receive NOT AUTHORITATIVE PHASE.",
+      run: (args) => state.readOwnership(args),
+    },
+    {
+      name: OWNERSHIP_TOOLS.sync,
+      description:
+        "Record semantic synchronization disposition for one closed sync point (planning-start, pre-plan, pre-assignment, milestone-executing, result-received, continue, finalize, consequential-preparation). Shepherd phases only; disposition is recorded before consume and consume is idempotent.",
+      run: (args) => state.recordSync(args),
+    },
+    {
+      name: OWNERSHIP_TOOLS.snapshot,
+      description:
+        "Record a bounded lifecycle snapshot for one stage (planning, executing, result-evaluation, consequential-preparation). Shepherd phases only; pending consequential action must be recorded before the consequential-preparation snapshot and check.",
+      run: (args) => state.recordSnapshot(args),
+    },
+    {
+      name: OWNERSHIP_TOOLS.correct,
+      description:
+        "Route semantic correction to sheepdog as normal corrective instructions, never raw records. Shepherd phases only; steering never authorizes consequential actions.",
+      run: (args) => state.routeCorrection(args),
+    },
+  ];
+  const tools = {};
+  for (const definition of definitions) {
+    const isClaim = definition.name === OWNERSHIP_TOOLS.claim;
+    const isSync = definition.name === OWNERSHIP_TOOLS.sync;
+    const isSnapshot = definition.name === OWNERSHIP_TOOLS.snapshot;
+    const isCorrect = definition.name === OWNERSHIP_TOOLS.correct;
+    tools[definition.name] = tool({
+      description: definition.description,
+      args: {
+        planId: tool.schema.string().describe("Lifecycle target Plan ID."),
+        phase: tool.schema.string().describe("Owner phase: planning or governance."),
+        session: tool.schema.string().describe("Authoritative session fencing the ownership record."),
+        ...(isClaim || isSync || isSnapshot || isCorrect
+          ? { generation: tool.schema.number().int().min(1).describe("Authoritative generation fencing the ownership record.") }
+          : {}),
+        ...(isClaim
+          ? {
+              milestone: tool.schema.string().min(1).describe("Bounded milestone summary."),
+              lifecycleState: tool.schema.string().describe("Closed lifecycle state."),
+              currentObjective: tool.schema.string().optional().describe("Bounded current objective semantic summary."),
+              currentAction: tool.schema.string().optional().describe("Bounded current action semantic summary."),
+              activeSheepdogTarget: tool.schema.string().optional().describe("Active sheepdog target or empty when yielded."),
+              relevantRevision: tool.schema.string().optional().describe("Relevant revision summary."),
+              pendingConsequentialAction: tool.schema.string().optional().describe("Pending consequential action summary."),
+            }
+          : {}),
+        ...(isSync
+          ? {
+              syncPoint: tool.schema.string().describe("Closed sync point."),
+              disposition: tool.schema.string().describe("Closed disposition recorded before consume."),
+              note: tool.schema.string().optional().describe("Bounded semantic note."),
+            }
+          : {}),
+        ...(isSnapshot
+          ? {
+              stage: tool.schema.string().describe("Snapshot stage."),
+              milestone: tool.schema.string().optional().describe("Bounded milestone override."),
+              lifecycleState: tool.schema.string().optional().describe("Closed lifecycle state override."),
+              currentObjective: tool.schema.string().optional().describe("Bounded current objective override."),
+              currentAction: tool.schema.string().optional().describe("Bounded current action override."),
+              activeSheepdogTarget: tool.schema.string().optional().describe("Active sheepdog target override."),
+              relevantRevision: tool.schema.string().optional().describe("Relevant revision override."),
+              pendingConsequentialAction: tool.schema.string().optional().describe("Pending consequential action override."),
+            }
+          : {}),
+        ...(isCorrect
+          ? {
+              correction: tool.schema.string().min(1).describe("Normal semantic corrective instructions for sheepdog, never raw records."),
+              syncPoint: tool.schema.string().optional().describe("Related closed sync point."),
+            }
+          : {}),
+      },
+      async execute(args, context) {
+        const allowed = OWNERSHIP_TOOL_ACCESS.get(definition.name);
+        if (!allowed?.has(context?.agent)) {
+          return JSON.stringify(
+            stateError(
+              "UNAUTHORIZED_AGENT",
+              `Agent ${context?.agent ?? "unknown"} may not use ${definition.name}.`,
+            ),
+          );
+        }
+        const result = await definition.run(args);
+        context.metadata({
+          title: result.ok ? `${definition.name}: ${args.planId}` : `${definition.name}: ${result.error.code}`,
+          metadata: result.ok ? { planId: args.planId } : { error: result.error.code },
+        });
+        return JSON.stringify(result);
+      },
+    });
+  }
+  return tools;
+}
+
 export const HerdrOrchestrationPlugin = async (_input, options = {}) => ({
   tool: {
     herdr_agent_response: createResponseTool(options.response),
     ...createStateTools(options.state),
+    ...createSteeringTools(options.state),
+    ...createRawSteeringTools(options.state),
+    ...createOwnershipTools(options.state),
   },
   config(config) {
     config.agent ??= {};
@@ -135,4 +379,18 @@ export const HerdrOrchestrationPlugin = async (_input, options = {}) => ({
 });
 
 export default HerdrOrchestrationPlugin;
-export { createAgents, mergeAgent, modeForAgent, STATE_TOOL_ACCESS, STATE_TOOLS };
+export {
+  createAgents,
+  DEVELOPER_AGENT,
+  mergeAgent,
+  modeForAgent,
+  OWNERSHIP_TOOL_ACCESS,
+  OWNERSHIP_TOOLS,
+  RAW_STEERING_TOOL_ACCESS,
+  RAW_STEERING_TOOLS,
+  SHEPHERD_PHASES,
+  STATE_TOOL_ACCESS,
+  STATE_TOOLS,
+  STEERING_TOOL_ACCESS,
+  STEERING_TOOLS,
+};

package/src/installer.js

@@ -125,6 +125,199 @@ export function findConfigFile(configDir) {
   return join(configDir, "opencode.jsonc");
 }
 
+// 15-M1 project config semantics (live-evidenced on opencode 1.18.29 via
+// `opencode debug config` plus `opencode debug skill` in OS temp probes).
+// Project filename: `opencode.json` in the project root per docs Per project
+// ("Add `opencode.json` in your project root ... traverses up to the nearest
+// Git directory"); live probes show both `opencode.json` and `opencode.jsonc`
+// in cwd load as scope "local" (plugin_origins source project file, scope
+// local) while empty cwd shows global-only (2 globals); when both exist both
+// load as separate local layers, so helpers edit only the found file and
+// preserve the other. Default for a new project file is `opencode.json` per
+// docs; an existing `opencode.jsonc` is preferred when present for JSONC
+// comment coherence with the global helper.
+// Per-key merge: docs Locations ("merged together, not replaced ... later
+// overrides earlier only for conflicting keys") plus Permissions Agents
+// ("merged with the global config, and agent rules take precedence"); live
+// per-key probe shows project `agent.shepherd.permission.bash` probe key
+// merges with plugin keys (`herdr --help` preserved, `*` deny preserved) and
+// a conflicting project `deny` overrides a plugin `allow`; a project custom
+// agent preserves plugin agents (shepherd plus governor plus sheepdog plus
+// grazer plus sheep plus shearers); top-level `permission` does not leak into
+// agent blocks, so helpers target `["agent", name, "permission", ...]` only.
+// Reload: config loads at startup; existing processes keep old config, so quit
+// and restart intentionally, then verify the merged view with
+// `opencode debug config` in the project; invalid project JSON fails that
+// command with "not valid JSON(C)" and no automatic fallback, while
+// `OPENCODE_DISABLE_PROJECT_CONFIG=1 opencode debug config` shows the
+// global-only fallback (live-evidenced OK pluginLen 2 vs FAIL). Helpers below
+// reuse parse plus modify plus applyEdits and backup discipline, stay fail
+// closed inside the project root, and never touch global config.
+// Skill decision: `opencode debug skill` shows 4 skills with 3 file-based
+// globals (`graphify` in ~/.claude/skills plus `herdr` plus `find-skills` in
+// ~/.agents/skills) and zero project `.opencode/skills` files, so M1 stays
+// prompt-embedded with no native SKILL.md; see src/prompts.js plus README.
+export const PROJECT_CONFIG_FILE = "opencode.json";
+export const PROJECT_CONFIG_FILENAMES = Object.freeze(["opencode.jsonc", "opencode.json"]);
+
+export function findProjectConfigFile(projectRoot) {
+  if (typeof projectRoot !== "string" || projectRoot.length === 0) {
+    throw new Error("Project root must be a non-empty path.");
+  }
+  const root = resolve(projectRoot);
+  for (const name of PROJECT_CONFIG_FILENAMES) {
+    const candidate = join(root, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return join(root, PROJECT_CONFIG_FILE);
+}
+
+function isInsideDir(parent, child) {
+  const sep = join("a", "b").slice(1, -1) || (process.platform === "win32" ? "\\" : "/");
+  const resolvedParent = resolve(parent);
+  const resolvedChild = resolve(child);
+  if (process.platform === "win32") {
+    const lowerParent = resolvedParent.toLowerCase();
+    const lowerChild = resolvedChild.toLowerCase();
+    if (lowerChild === lowerParent) return true;
+    return lowerChild.startsWith(lowerParent + sep.toLowerCase());
+  }
+  if (resolvedChild === resolvedParent) return true;
+  return resolvedChild.startsWith(resolvedParent + sep);
+}
+
+function projectConfigConfinement(projectRoot, targetFile) {
+  if (typeof projectRoot !== "string" || projectRoot.length === 0) {
+    throw new Error("Project root must be a non-empty path.");
+  }
+  if (typeof targetFile !== "string" || targetFile.length === 0) {
+    throw new Error("Project config file must be a non-empty path.");
+  }
+  const root = resolve(projectRoot);
+  const target = resolve(targetFile);
+  const globalDir = resolve(configDirectory());
+  const globalFile = resolve(findConfigFile(globalDir));
+  if (target === globalFile) {
+    throw new Error(`Refusing global config file ${target}; project helpers never touch global config.`);
+  }
+  if (isInsideDir(globalDir, target)) {
+    throw new Error(`Refusing path inside global config directory ${globalDir}; project helpers stay inside the project root.`);
+  }
+  if (root === globalDir || isInsideDir(globalDir, root)) {
+    throw new Error(`Refusing global config directory as project root ${root}; use a project checkout.`);
+  }
+  if (target !== root && !isInsideDir(root, target)) {
+    throw new Error(`Refusing outside path ${target}; project helpers stay inside ${root}.`);
+  }
+  const base = target.split(/[\\/]/).pop();
+  if (!PROJECT_CONFIG_FILENAMES.includes(base)) {
+    throw new Error(`Refusing non-project filename ${base}; project helpers edit only opencode.jsonc or opencode.json.`);
+  }
+  const directParent = resolve(join(target, ".."));
+  if (directParent !== root) {
+    throw new Error(`Refusing nested path ${target}; project helpers edit only the project root file.`);
+  }
+  return { root, target };
+}
+
+export function resolveProjectConfigFile(projectRoot, explicitFile) {
+  if (explicitFile !== undefined) {
+    const candidate = resolve(projectRoot, explicitFile);
+    projectConfigConfinement(projectRoot, candidate);
+    return candidate;
+  }
+  const found = findProjectConfigFile(projectRoot);
+  projectConfigConfinement(projectRoot, found);
+  return found;
+}
+
+const PROJECT_AGENT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const PROJECT_PERMISSION_ACTIONS = new Set(["allow", "ask", "deny"]);
+
+function assertProjectAgentName(agentName) {
+  if (typeof agentName !== "string" || !PROJECT_AGENT_NAME_PATTERN.test(agentName)) {
+    throw new Error(`Invalid agent name ${JSON.stringify(agentName)}; use 1-64 letters, digits, dot, underscore, or hyphen starting alphanumeric.`);
+  }
+}
+
+function assertProjectPermissionUpdates(permissionUpdates) {
+  if (!permissionUpdates || typeof permissionUpdates !== "object" || Array.isArray(permissionUpdates)) {
+    throw new Error("Permission updates must be a non-array object mapping tool to action or pattern map.");
+  }
+  for (const [tool, value] of Object.entries(permissionUpdates)) {
+    if (typeof tool !== "string" || tool.length === 0 || tool.includes("/") || tool.includes("\\")) {
+      throw new Error(`Invalid permission tool ${JSON.stringify(tool)}.`);
+    }
+    if (value === undefined) continue;
+    if (typeof value === "string") {
+      if (!PROJECT_PERMISSION_ACTIONS.has(value)) {
+        throw new Error(`Invalid action ${JSON.stringify(value)} for ${tool}; use allow, ask, deny, or undefined to delete.`);
+      }
+      continue;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error(`Invalid permission value for ${tool}; use allow, ask, deny, undefined, or a pattern map.`);
+    }
+    for (const [pattern, action] of Object.entries(value)) {
+      if (typeof pattern !== "string" || pattern.length === 0) {
+        throw new Error(`Invalid permission pattern ${JSON.stringify(pattern)} for ${tool}.`);
+      }
+      if (action !== undefined && !PROJECT_PERMISSION_ACTIONS.has(action)) {
+        throw new Error(`Invalid action ${JSON.stringify(action)} for ${tool} pattern ${JSON.stringify(pattern)}.`);
+      }
+    }
+  }
+}
+
+function parseProjectConfigText(text) {
+  const errors = [];
+  parse(text || "{}", errors, { allowTrailingComma: true, disallowComments: false });
+  if (errors.length) {
+    const first = errors[0];
+    throw new Error(`Invalid OpenCode JSONC at offset ${first.offset}: ${printParseErrorCode(first.error)}.`);
+  }
+}
+
+// Per-key merge for one agent permission block. String values set the tool
+// shorthand; undefined deletes the tool; object values set per-pattern rules
+// with undefined deleting that pattern. Unrelated keys, plugins, tuples, and
+// sibling agents are preserved via modify plus applyEdits. Reapplying the
+// same updates is idempotent (no edits when values already match).
+export function updateProjectAgentPermissions(text, agentName, permissionUpdates) {
+  assertProjectAgentName(agentName);
+  assertProjectPermissionUpdates(permissionUpdates);
+  parseProjectConfigText(text);
+  const source = text || "{}";
+  const formattingOptions = { insertSpaces: true, tabSize: 2, eol: source.includes("\r\n") ? "\r\n" : "\n" };
+  let updated = source;
+  for (const [tool, value] of Object.entries(permissionUpdates)) {
+    if (value === undefined) {
+      updated = applyEdits(updated, modify(updated, ["agent", agentName, "permission", tool], undefined, { formattingOptions }));
+    } else if (typeof value === "string") {
+      updated = applyEdits(updated, modify(updated, ["agent", agentName, "permission", tool], value, { formattingOptions }));
+    } else {
+      for (const [pattern, action] of Object.entries(value)) {
+        updated = applyEdits(updated, modify(updated, ["agent", agentName, "permission", tool, pattern], action, { formattingOptions }));
+      }
+    }
+  }
+  return updated;
+}
+
+export function writeProjectAgentPermissions(projectRoot, agentName, permissionUpdates, explicitFile) {
+  assertProjectAgentName(agentName);
+  assertProjectPermissionUpdates(permissionUpdates);
+  const file = resolveProjectConfigFile(projectRoot, explicitFile);
+  mkdirSync(resolve(projectRoot), { recursive: true });
+  const existed = existsSync(file);
+  const previous = existed ? readFileSync(file, "utf8") : '{\n  "$schema": "https://opencode.ai/config.json"\n}\n';
+  const next = updateProjectAgentPermissions(previous, agentName, permissionUpdates);
+  if (next === previous) return { file, backup: null, changed: false, existed };
+  const backup = backupFile(file);
+  writeFileSync(file, next, "utf8");
+  return { file, backup, changed: true, existed };
+}
+
 export function backupFile(file, now = new Date()) {
   if (!existsSync(file)) return null;
   const stamp = now.toISOString().replace(/[:.]/g, "-");