harnery 0.11.0 → 0.12.0

package/src/commands/policy.ts

@@ -0,0 +1,50 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import type { NormalizedPolicy } from "../core/policy/index.ts";
+import { loadPolicyFile, policyDigest } from "../core/policy/index.ts";
+
+interface PolicyCheckOpts {
+  json?: boolean;
+}
+
+export function registerPolicyCommand(program: Command, emit: EmitContext): void {
+  const command = program
+    .command("policy")
+    .description("Inspect host-enforced workflow policy documents.");
+
+  command
+    .command("check <file>")
+    .description("Validate and print a normalized policy without running a workflow.")
+    .option("--json", "Emit the normalized policy and digest as JSON")
+    .action((file: string, opts: PolicyCheckOpts) => {
+      try {
+        const policy = loadPolicyFile(file);
+        const result = { policy, sha256: policyDigest(policy) };
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(result);
+        } else {
+          emit.text(renderPolicy(policy, result.sha256));
+        }
+      } catch (error) {
+        emit.error({ code: "policy_invalid", message: (error as Error).message });
+        emit.setExitCode(1);
+      }
+    });
+}
+
+export function renderPolicy(policy: Readonly<NormalizedPolicy>, digest: string): string {
+  const lines = [
+    `${policy.name} (schema ${policy.schema_version})`,
+    `sha256: ${digest}`,
+    `cost ceiling: ${policy.max_cost_usd === undefined ? "none" : `$${policy.max_cost_usd.toFixed(4)}`}`,
+    `unknown cost: ${policy.unknown_cost}`,
+    `network: ${policy.network}`,
+    `external actions: ${policy.external_actions}`,
+    `harnesses: ${policy.allowed_harnesses?.join(", ") ?? "any"}`,
+    `models: ${policy.allowed_models?.join(", ") ?? "any"}`,
+    `paths: ${policy.allowed_paths?.join(", ") ?? "any"}`,
+    `isolation: ${policy.allowed_isolation?.join(", ") ?? "any"}`,
+  ];
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/workflow.ts

@@ -3,6 +3,8 @@ import type { EmitContext } from "../commander.ts";
 import { workflowSubscriptionOnly } from "../core/config.ts";
 import { createBuiltinHarnessRegistry } from "../core/harnesses/index.ts";
 import { findCoordRoot } from "../core/hooks/resolve/coord-root.ts";
+import type { PolicyIsolation } from "../core/policy/index.ts";
+import { loadPolicyFile } from "../core/policy/index.ts";
 
 /**
  * `workflow run <script>`: execute a workflow script — bounded, schema-gated,
@@ -22,6 +24,8 @@ interface WorkflowRunOpts {
   resumeFrom?: string;
   subscriptionOnly?: boolean;
   allowApiBilling?: boolean;
+  policy?: string;
+  isolation?: PolicyIsolation;
   json?: boolean;
 }
 
@@ -39,7 +43,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
   workflow
     .command("run <script>")
     .description(
-      "Execute a workflow script (plain JS: `export default async ({agent, parallel, stage, log, evidence}) => …`). " +
+      "Execute a workflow script (plain JS: `export default async ({agent, parallel, stage, log, evidence, authorize}) => …`). " +
         "Subagents spawn as headless harness-CLI subprocesses, coordination-registered.",
     )
     .option("--max-agents <n>", "Total-agent ceiling for the run (default 50)")
@@ -63,6 +67,14 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
       "Permit an exported API key to override a stored subscription login (per-token billing); " +
         "without this the engine refuses that silent-override state",
     )
+    .option(
+      "--policy <file>",
+      "Host policy JSON/JSONC applied before dispatch and external mutation",
+    )
+    .option(
+      "--isolation <mode>",
+      "Host-created execution boundary: shared | worktree | sandbox | remote (default shared)",
+    )
     .option("--json", "Emit the full RunReport as JSON")
     .action(async (script: string, opts: WorkflowRunOpts) => {
       const coordRoot = findCoordRoot();
@@ -80,6 +92,16 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
         });
         process.exit(1);
       }
+      if (
+        opts.isolation &&
+        !(["shared", "worktree", "sandbox", "remote"] as const).includes(opts.isolation)
+      ) {
+        emit.error({
+          code: "bad_isolation",
+          message: `unknown isolation ${JSON.stringify(opts.isolation)} (expected: shared | worktree | sandbox | remote)`,
+        });
+        process.exit(1);
+      }
       // Flag beats config; the two flags contradict each other by design.
       const subscriptionOnly = opts.subscriptionOnly || workflowSubscriptionOnly(coordRoot);
       if (subscriptionOnly && opts.allowApiBilling) {
@@ -111,6 +133,12 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
                 { toolEvidence: adapter.profile.capabilities.toolEvidence },
               ]),
           ),
+          policy: opts.policy ? loadPolicyFile(opts.policy) : undefined,
+          isolation: opts.isolation,
+          // CLI harness subprocesses inherit the host network. A policy that
+          // forbids network must therefore deny dispatch unless a future host
+          // adapter creates and declares a network-disabled boundary.
+          networkAccess: "enabled",
         });
         if (opts.json) {
           emit.config({ format: "json" });

package/src/core/policy/evaluate.ts

@@ -0,0 +1,311 @@
+import { createHash } from "node:crypto";
+import { isAbsolute, relative, resolve } from "node:path";
+import type {
+  NormalizedPolicy,
+  PolicyEvaluation,
+  PolicyIsolation,
+  PolicyRequest,
+  PolicyRequestSummary,
+  PolicyRuleResult,
+  PolicySpec,
+  PolicyVerdict,
+} from "./types.ts";
+import { POLICY_SCHEMA_VERSION } from "./types.ts";
+
+const VERDICTS = ["allow", "ask", "deny"] as const;
+const ISOLATIONS = ["shared", "worktree", "sandbox", "remote"] as const;
+const MAX_NAME = 200;
+const MAX_FIELD = 500;
+const MAX_LIST = 100;
+const POLICY_FIELDS = new Set([
+  "schema_version",
+  "name",
+  "max_cost_usd",
+  "unknown_cost",
+  "allowed_harnesses",
+  "allowed_models",
+  "allowed_paths",
+  "network",
+  "external_actions",
+  "allowed_isolation",
+]);
+
+export class PolicyDeniedError extends Error {
+  readonly decisionId: string;
+
+  constructor(message: string, decisionId: string) {
+    super(message);
+    this.name = "PolicyDeniedError";
+    this.decisionId = decisionId;
+  }
+}
+
+export function normalizePolicy(
+  input: PolicySpec,
+  options: { baseDir?: string } = {},
+): Readonly<NormalizedPolicy> {
+  if (!isRecord(input)) throw new Error("policy must be an object");
+  const unknownFields = Object.keys(input).filter((field) => !POLICY_FIELDS.has(field));
+  if (unknownFields.length > 0) {
+    throw new Error(`policy contains unknown field(s): ${unknownFields.sort().join(", ")}`);
+  }
+  const schemaVersion = input.schema_version ?? POLICY_SCHEMA_VERSION;
+  if (schemaVersion !== POLICY_SCHEMA_VERSION) {
+    throw new Error(`unsupported policy schema_version ${JSON.stringify(schemaVersion)}`);
+  }
+  const baseDir = resolve(options.baseDir ?? process.cwd());
+  const normalized: NormalizedPolicy = {
+    schema_version: POLICY_SCHEMA_VERSION,
+    name: boundedString(input.name ?? "workflow policy", "policy name", MAX_NAME),
+    max_cost_usd: optionalMoney(input.max_cost_usd, "max_cost_usd"),
+    unknown_cost: enumValue(input.unknown_cost ?? "deny", ["ask", "deny"], "unknown_cost"),
+    allowed_harnesses: optionalStringList(input.allowed_harnesses, "allowed_harnesses"),
+    allowed_models: optionalStringList(input.allowed_models, "allowed_models"),
+    allowed_paths: optionalPathList(input.allowed_paths, baseDir),
+    network: enumValue(input.network ?? "deny", VERDICTS, "network"),
+    external_actions: enumValue(input.external_actions ?? "deny", VERDICTS, "external_actions"),
+    allowed_isolation: optionalEnumList(input.allowed_isolation, ISOLATIONS, "allowed_isolation"),
+  };
+  return deepFreeze(normalized);
+}
+
+export function policyDigest(policy: NormalizedPolicy): string {
+  return createHash("sha256").update(JSON.stringify(policy)).digest("hex");
+}
+
+export function evaluatePolicy(
+  policy: Readonly<NormalizedPolicy>,
+  rawRequest: PolicyRequest,
+): PolicyEvaluation {
+  const request = summarizePolicyRequest(rawRequest);
+  const rules: PolicyRuleResult[] = [];
+  const add = (code: string, verdict: PolicyVerdict, reason: string): void => {
+    rules.push({ code, verdict, reason });
+  };
+
+  if (policy.allowed_harnesses && request.phase === "dispatch") {
+    if (!request.harness || !policy.allowed_harnesses.includes(request.harness)) {
+      add(
+        "harness_not_allowed",
+        "deny",
+        `harness ${JSON.stringify(request.harness ?? "unknown")} is not allowed`,
+      );
+    }
+  }
+  if (policy.allowed_models && request.phase === "dispatch") {
+    if (!request.model || !policy.allowed_models.includes(request.model)) {
+      add(
+        "model_not_allowed",
+        "deny",
+        `model ${JSON.stringify(request.model ?? "unknown")} is not allowed`,
+      );
+    }
+  }
+  if (policy.allowed_paths) {
+    if (!request.path || !policy.allowed_paths.some((root) => contains(root, request.path!))) {
+      add(
+        "path_not_allowed",
+        "deny",
+        `path ${JSON.stringify(request.path ?? "unknown")} is outside the allowed roots`,
+      );
+    }
+  }
+  if (policy.allowed_isolation && !policy.allowed_isolation.includes(request.isolation)) {
+    add(
+      "isolation_not_allowed",
+      "deny",
+      `isolation ${JSON.stringify(request.isolation)} is not allowed`,
+    );
+  }
+  if (request.network_access !== "disabled" && policy.network !== "allow") {
+    add(
+      request.network_access === "unknown" ? "network_unknown" : "network_restricted",
+      policy.network,
+      request.network_access === "unknown"
+        ? "network access is unknown"
+        : "network access requires policy authorization",
+    );
+  }
+  if (request.phase === "external_mutation" && policy.external_actions !== "allow") {
+    add(
+      "external_action_restricted",
+      policy.external_actions,
+      "external mutation requires policy authorization",
+    );
+  }
+  if (policy.max_cost_usd !== undefined && request.phase === "dispatch") {
+    const current = request.current_cost_usd ?? 0;
+    if (current >= policy.max_cost_usd) {
+      add(
+        "cost_budget_exhausted",
+        "deny",
+        `run cost $${current.toFixed(4)} has reached the $${policy.max_cost_usd.toFixed(4)} ceiling`,
+      );
+    } else if (request.projected_cost_usd === null || request.projected_cost_usd === undefined) {
+      add(
+        "dispatch_cost_unknown",
+        policy.unknown_cost,
+        `dispatch cost is unknown under a $${policy.max_cost_usd.toFixed(4)} ceiling`,
+      );
+    } else if (current + request.projected_cost_usd > policy.max_cost_usd) {
+      add(
+        "cost_budget_exceeded",
+        "deny",
+        `projected run cost $${(current + request.projected_cost_usd).toFixed(4)} exceeds the $${policy.max_cost_usd.toFixed(4)} ceiling`,
+      );
+    }
+  }
+
+  if (rules.length === 0) {
+    rules.push({ code: "policy_allow", verdict: "allow", reason: "all configured rules allow" });
+  }
+  const verdict = rules.some((rule) => rule.verdict === "deny")
+    ? "deny"
+    : rules.some((rule) => rule.verdict === "ask")
+      ? "ask"
+      : "allow";
+  const decisive = rules.filter((rule) => rule.verdict === verdict);
+  return {
+    verdict,
+    reason: decisive.map((rule) => rule.reason).join("; "),
+    rules,
+  };
+}
+
+/** Bound and normalize the receipt-safe subset before it reaches a journal or proof. */
+export function summarizePolicyRequest(input: PolicyRequest): PolicyRequestSummary {
+  if (!isRecord(input)) throw new Error("policy request must be an object");
+  const phase = enumValue(input.phase, ["dispatch", "external_mutation"], "policy phase");
+  const isolation = enumValue(input.isolation, ISOLATIONS, "policy isolation");
+  const networkAccess = enumValue(
+    input.network_access,
+    ["enabled", "disabled", "unknown"],
+    "policy network_access",
+  );
+  return {
+    phase,
+    action: boundedString(input.action, "policy action", MAX_FIELD),
+    path: optionalBounded(input.path, "policy path"),
+    harness: optionalBounded(input.harness, "policy harness"),
+    model: optionalBounded(input.model, "policy model"),
+    effort: optionalBounded(input.effort, "policy effort"),
+    max_attempts: optionalWholeNumber(input.max_attempts, "policy max_attempts", 1),
+    max_turns: optionalWholeNumber(input.max_turns, "policy max_turns", 1),
+    timeout_ms: optionalWholeNumber(input.timeout_ms, "policy timeout_ms", 1),
+    prompt_bytes: optionalWholeNumber(input.prompt_bytes, "policy prompt_bytes", 0),
+    isolation,
+    network_access: networkAccess,
+    service: optionalBounded(input.service, "policy service"),
+    target: optionalBounded(safeTarget(input.target), "policy target"),
+    current_cost_usd: optionalMoney(input.current_cost_usd, "current_cost_usd"),
+    projected_cost_usd:
+      input.projected_cost_usd === null
+        ? null
+        : optionalMoney(input.projected_cost_usd, "projected_cost_usd"),
+  };
+}
+
+function contains(root: string, candidate: string): boolean {
+  const rel = relative(resolve(root), resolve(candidate));
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function optionalPathList(value: unknown, baseDir: string): readonly string[] | undefined {
+  const values = optionalStringList(value, "allowed_paths");
+  if (!values) return undefined;
+  return [...new Set(values.map((item) => resolve(baseDir, item)))].sort();
+}
+
+function optionalStringList(value: unknown, field: string): readonly string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_LIST) {
+    throw new Error(`${field} must be a non-empty array with at most ${MAX_LIST} entries`);
+  }
+  return [
+    ...new Set(value.map((item, index) => boundedString(item, `${field}[${index}]`, MAX_FIELD))),
+  ].sort();
+}
+
+function optionalEnumList<T extends string>(
+  value: unknown,
+  allowed: readonly T[],
+  field: string,
+): readonly T[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_LIST) {
+    throw new Error(`${field} must be a non-empty array with at most ${MAX_LIST} entries`);
+  }
+  return [...new Set(value.map((item) => enumValue(item, allowed, field)))].sort();
+}
+
+function enumValue<T extends string>(value: unknown, values: readonly T[], field: string): T {
+  if (typeof value !== "string" || !values.includes(value as T)) {
+    throw new Error(`${field} must be one of: ${values.join(", ")}`);
+  }
+  return value as T;
+}
+
+function optionalMoney(value: unknown, field: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error(`${field} must be a finite non-negative number`);
+  }
+  return value;
+}
+
+function optionalWholeNumber(value: unknown, field: string, minimum: number): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isSafeInteger(value) || (value as number) < minimum) {
+    throw new Error(`${field} must be a safe integer greater than or equal to ${minimum}`);
+  }
+  return value as number;
+}
+
+function boundedString(value: unknown, field: string, max: number): string {
+  if (typeof value !== "string") throw new Error(`${field} must be a string`);
+  const normalized = withoutControls(value).replace(/\s+/g, " ").trim();
+  if (!normalized) throw new Error(`${field} must not be empty`);
+  if (normalized.length > max) throw new Error(`${field} exceeds ${max} characters`);
+  return normalized;
+}
+
+function optionalBounded(value: unknown, field: string): string | undefined {
+  return value === undefined ? undefined : boundedString(value, field, MAX_FIELD);
+}
+
+function safeTarget(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  try {
+    const url = new URL(value);
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    const query = value.indexOf("?");
+    const fragment = value.indexOf("#");
+    const boundary = Math.min(
+      query === -1 ? value.length : query,
+      fragment === -1 ? value.length : fragment,
+    );
+    return value.slice(0, boundary);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function withoutControls(value: string): string {
+  return Array.from(value, (character) => {
+    const code = character.charCodeAt(0);
+    return code < 32 || code === 127 ? " " : character;
+  }).join("");
+}
+
+function deepFreeze<T>(value: T): Readonly<T> {
+  if (value && typeof value === "object") {
+    for (const child of Object.values(value as Record<string, unknown>)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+export type { PolicyIsolation };

package/src/core/policy/file.ts

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { stripJsonComments } from "../config.ts";
+import { normalizePolicy } from "./evaluate.ts";
+import type { NormalizedPolicy, PolicySpec } from "./types.ts";
+
+export function loadPolicyFile(path: string): Readonly<NormalizedPolicy> {
+  const absolute = resolve(path);
+  let parsed: PolicySpec;
+  try {
+    parsed = JSON.parse(stripJsonComments(readFileSync(absolute, "utf8"))) as PolicySpec;
+  } catch (error) {
+    throw new Error(`cannot parse policy at ${absolute}: ${(error as Error).message}`);
+  }
+  try {
+    return normalizePolicy(parsed, { baseDir: dirname(absolute) });
+  } catch (error) {
+    throw new Error(`invalid policy at ${absolute}: ${(error as Error).message}`);
+  }
+}

package/src/core/policy/index.ts

@@ -0,0 +1,26 @@
+export {
+  evaluatePolicy,
+  normalizePolicy,
+  PolicyDeniedError,
+  policyDigest,
+  summarizePolicyRequest,
+} from "./evaluate.ts";
+export { loadPolicyFile } from "./file.ts";
+export type {
+  DispatchCostEstimator,
+  ExternalMutationRequest,
+  NormalizedPolicy,
+  PolicyAskResolution,
+  PolicyAskResolver,
+  PolicyDecision,
+  PolicyEvaluation,
+  PolicyIsolation,
+  PolicyNetworkAccess,
+  PolicyPhase,
+  PolicyRequest,
+  PolicyRequestSummary,
+  PolicyRuleResult,
+  PolicySpec,
+  PolicyVerdict,
+} from "./types.ts";
+export { POLICY_SCHEMA_VERSION } from "./types.ts";

package/src/core/policy/types.ts

@@ -0,0 +1,107 @@
+export const POLICY_SCHEMA_VERSION = 1 as const;
+
+export type PolicyVerdict = "allow" | "ask" | "deny";
+export type PolicyPhase = "dispatch" | "external_mutation";
+export type PolicyIsolation = "shared" | "worktree" | "sandbox" | "remote";
+export type PolicyNetworkAccess = "enabled" | "disabled" | "unknown";
+
+/** Host-owned policy document. Workflow metadata cannot supply this value. */
+export interface PolicySpec {
+  schema_version?: typeof POLICY_SCHEMA_VERSION;
+  name?: string;
+  max_cost_usd?: number;
+  /** Applied when a cost ceiling exists but the host cannot price a dispatch. */
+  unknown_cost?: Exclude<PolicyVerdict, "allow">;
+  allowed_harnesses?: readonly string[];
+  allowed_models?: readonly string[];
+  /** Absolute paths, or paths relative to the policy file. */
+  allowed_paths?: readonly string[];
+  network?: PolicyVerdict;
+  external_actions?: PolicyVerdict;
+  /** Allowed host-declared execution boundaries. No strength ordering is inferred. */
+  allowed_isolation?: readonly PolicyIsolation[];
+}
+
+export interface NormalizedPolicy {
+  schema_version: typeof POLICY_SCHEMA_VERSION;
+  name: string;
+  max_cost_usd?: number;
+  unknown_cost: Exclude<PolicyVerdict, "allow">;
+  allowed_harnesses?: readonly string[];
+  allowed_models?: readonly string[];
+  allowed_paths?: readonly string[];
+  network: PolicyVerdict;
+  external_actions: PolicyVerdict;
+  allowed_isolation?: readonly PolicyIsolation[];
+}
+
+export interface PolicyRequest {
+  phase: PolicyPhase;
+  action: string;
+  path?: string;
+  harness?: string;
+  model?: string;
+  effort?: string;
+  max_attempts?: number;
+  max_turns?: number;
+  timeout_ms?: number;
+  /** Prompt size for host estimation. Prompt content is never included. */
+  prompt_bytes?: number;
+  isolation: PolicyIsolation;
+  network_access: PolicyNetworkAccess;
+  service?: string;
+  target?: string;
+  current_cost_usd?: number;
+  projected_cost_usd?: number | null;
+}
+
+export type PolicyRequestSummary = PolicyRequest;
+
+export interface PolicyRuleResult {
+  code: string;
+  verdict: PolicyVerdict;
+  reason: string;
+}
+
+export interface PolicyEvaluation {
+  verdict: PolicyVerdict;
+  reason: string;
+  rules: PolicyRuleResult[];
+}
+
+export interface PolicyAskResolution {
+  verdict: "allow" | "deny";
+  reason?: string;
+}
+
+export type PolicyAskResolver = (
+  request: Readonly<PolicyRequestSummary>,
+  evaluation: Readonly<PolicyEvaluation>,
+) => Promise<PolicyAskResolution> | PolicyAskResolution;
+
+export interface PolicyDecision {
+  id: string;
+  checked_at: string;
+  policy: string;
+  phase: PolicyPhase;
+  initial_verdict: PolicyVerdict;
+  verdict: "allow" | "deny";
+  resolved_by: "policy" | "host" | "fail_closed";
+  reason: string;
+  rule_codes: string[];
+  request: PolicyRequestSummary;
+}
+
+export interface ExternalMutationRequest {
+  /** Short verb phrase, for example "publish release" or "write report". */
+  action: string;
+  path?: string;
+  network?: boolean;
+  service?: string;
+  /** Bounded destination descriptor. Do not include credentials or payloads. */
+  target?: string;
+}
+
+export type DispatchCostEstimator = (
+  request: Readonly<PolicyRequestSummary>,
+) => Promise<number | null> | number | null;