@piagent/platform 1.2.16 → 1.3.0-ie.8

package/packages/piagent-core/runtime/orchestration/owned-work-budget.ts

@@ -0,0 +1,105 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ensurePrivateStateDirectory, resolveLocalStatePath } from "../../extensions/local-state-path.js";
+import { safeTaskId } from "../../extensions/task-state.js";
+import type { HelperRequest, HelperRole } from "./role-policy.ts";
+import { validateHelperRequest } from "./role-policy.ts";
+
+export const OWNED_WORK_BUDGET_VERSION = "owned-work-budget-v1" as const;
+export type OwnedWorkCeilings = Readonly<{ maxConcurrentHelpers: number; maxTotalHelpers: number; maxScoutPasses: number; maxPlannerPasses: number; maxReviewPasses: number; maxOracleCalls: number; maxRepairPasses: number; maxWriters: number }>;
+export const DEFAULT_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({ maxConcurrentHelpers: 2, maxTotalHelpers: 3, maxScoutPasses: 1, maxPlannerPasses: 1, maxReviewPasses: 1, maxOracleCalls: 1, maxRepairPasses: 1, maxWriters: 1 });
+export const AUTOMATIC_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({ ...DEFAULT_OWNED_WORK_CEILINGS, maxConcurrentHelpers: 1, maxTotalHelpers: 1 });
+const LOCK_WAIT_MS = 5;
+const LOCK_WAIT_CEILING_MS = 250;
+const STALE_LOCK_MS = 30_000;
+type Reservation = { id: string; deduplicationKey: string; role: HelperRole; authority: string; status: "active" | "succeeded" | "failed" | "cancelled" | "orphaned"; reservedAt: string; expiresAt: string; completedAt: string | null; usageRef: { calls: number; tokens: number; outputDigest: string | null } | null };
+type BudgetState = { version: typeof OWNED_WORK_BUDGET_VERSION; taskId: string; taskRunId: string; terminal: boolean; reservations: Reservation[]; updatedAt: string };
+export type HelperReleaseResult = { accepted: boolean; status: Reservation["status"] | "stale"; reason: "released" | "helper-call-budget-exceeded" | "helper-token-budget-exceeded" | "reservation-not-active" };
+
+function digest(value: unknown): string { return crypto.createHash("sha256").update(String(value ?? "")).digest("hex"); }
+function statePath(cwd: string, taskRunId: string): string { return path.join(cwd, ".pi", "piagent-state", "helper-budgets", `${safeTaskId(taskRunId)}.json`); }
+function lockPath(cwd: string, taskRunId: string): string { return `${statePath(cwd, taskRunId)}.lock`; }
+function empty(request: HelperRequest, now: string): BudgetState { return { version: OWNED_WORK_BUDGET_VERSION, taskId: request.taskId, taskRunId: request.taskRunId, terminal: false, reservations: [], updatedAt: now }; }
+function active(state: BudgetState): Reservation[] { return state.reservations.filter((item) => item.status === "active"); }
+function roleLimit(role: HelperRole): number { return role === "scout" || role === "retriever" || role === "researcher" ? 1 : role === "planner" ? 1 : role === "reviewer" ? 1 : role === "oracle" ? 1 : role === "worker" ? 1 : 0; }
+
+function read(cwd: string, request: HelperRequest, now: string): BudgetState {
+  const target = statePath(cwd, request.taskRunId); if (!fs.existsSync(target)) return empty(request, now);
+  const resolved = resolveLocalStatePath(cwd, target, { label: "Helper budget state", kind: "file" });
+  const value = JSON.parse(fs.readFileSync(resolved, "utf8"));
+  if (value?.version !== OWNED_WORK_BUDGET_VERSION || value.taskId !== request.taskId || value.taskRunId !== request.taskRunId || !Array.isArray(value.reservations)) throw new Error("helper budget identity/state is invalid");
+  return value;
+}
+function write(cwd: string, state: BudgetState): void {
+  const target = statePath(cwd, state.taskRunId); ensurePrivateStateDirectory(cwd, path.dirname(target), "Helper budget directory");
+  resolveLocalStatePath(cwd, target, { label: "Helper budget state", allowMissingLeaf: true });
+  const temporary = `${target}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(state)}\n`, { mode: 0o600 }); fs.renameSync(temporary, target); fs.chmodSync(target, 0o600);
+}
+function withLock<T>(cwd: string, taskRunId: string, action: () => T): T {
+  ensurePrivateStateDirectory(cwd, path.dirname(statePath(cwd, taskRunId)), "Helper budget directory");
+  const lock = lockPath(cwd, taskRunId); resolveLocalStatePath(cwd, lock, { label: "Helper budget lock", allowMissingLeaf: true });
+  const started = Date.now(); let fd: number | undefined;
+  while (fd === undefined) {
+    try {
+      fd = fs.openSync(lock, "wx", 0o600);
+    } catch (error) {
+      const code = (error as { code?: string })?.code;
+      if (code !== "EEXIST") throw error;
+      try { if (Date.now() - fs.statSync(lock).mtimeMs > STALE_LOCK_MS) fs.unlinkSync(lock); } catch {}
+      if (Date.now() - started >= LOCK_WAIT_CEILING_MS) throw new Error("helper budget reservation is busy");
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_WAIT_MS);
+    }
+  }
+  try {
+    fs.writeFileSync(fd, `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`);
+    return action();
+  } finally { fs.closeSync(fd); try { fs.unlinkSync(lock); } catch {} }
+}
+function recoverOrphans(state: BudgetState, now: string): number {
+  let recovered = 0; const instant = Date.parse(now);
+  for (const item of state.reservations) if (item.status === "active" && Date.parse(item.expiresAt) <= instant) { item.status = "orphaned"; item.completedAt = now; recovered += 1; }
+  return recovered;
+}
+
+export class OwnedWorkBudgetController {
+  reserve(cwd: string, requestInput: HelperRequest, now = new Date().toISOString(), ceilings: OwnedWorkCeilings = DEFAULT_OWNED_WORK_CEILINGS): { decision: "reserved" | "duplicate" | "blocked"; reason: string; reservationId: string | null; recoveredOrphans: number } {
+    const request = validateHelperRequest(structuredClone(requestInput));
+    return withLock(cwd, request.taskRunId, () => {
+      const state = read(cwd, request, now); const recoveredOrphans = recoverOrphans(state, now);
+      if (state.terminal) return { decision: "blocked", reason: "parent-task-terminal", reservationId: null, recoveredOrphans };
+      const duplicate = state.reservations.find((item) => item.deduplicationKey === request.deduplicationKey && ["active", "succeeded"].includes(item.status));
+      if (duplicate) return { decision: "duplicate", reason: "equivalent-helper-already-owned", reservationId: duplicate.id, recoveredOrphans };
+      if (active(state).length >= ceilings.maxConcurrentHelpers || state.reservations.length >= ceilings.maxTotalHelpers) return { decision: "blocked", reason: "helper-budget-exhausted", reservationId: null, recoveredOrphans };
+      if (state.reservations.filter((item) => item.role === request.role).length >= roleLimit(request.role)) return { decision: "blocked", reason: `${request.role}-ceiling-reached`, reservationId: null, recoveredOrphans };
+      if (request.authority === "single-writer" && active(state).some((item) => item.authority === "single-writer")) return { decision: "blocked", reason: "single-writer-already-owned", reservationId: null, recoveredOrphans };
+      const id = digest(`${request.taskRunId}:${request.deduplicationKey}:${state.reservations.length}`).slice(0, 32);
+      state.reservations.push({ id, deduplicationKey: request.deduplicationKey, role: request.role, authority: request.authority, status: "active", reservedAt: now, expiresAt: new Date(Date.parse(now) + request.ceilings.timeSeconds * 1000).toISOString(), completedAt: null, usageRef: null });
+      state.updatedAt = now; write(cwd, state); return { decision: "reserved", reason: "budget-reserved", reservationId: id, recoveredOrphans };
+    });
+  }
+  release(cwd: string, requestInput: HelperRequest, reservationId: string, outcome: "succeeded" | "failed" | "cancelled", usage: { calls?: number; tokens?: number; output?: string } = {}, now = new Date().toISOString()): HelperReleaseResult {
+    const request = validateHelperRequest(structuredClone(requestInput)); return withLock(cwd, request.taskRunId, () => {
+      const state = read(cwd, request, now); const reservation = state.reservations.find((item) => item.id === reservationId);
+      if (!reservation || reservation.status !== "active") return { accepted: false, status: reservation?.status ?? "stale", reason: "reservation-not-active" };
+      const rawCalls = Number.isFinite(Number(usage.calls)) ? Math.max(0, Math.floor(Number(usage.calls))) : request.ceilings.calls + 1;
+      const rawTokens = Number.isFinite(Number(usage.tokens)) ? Math.max(0, Math.floor(Number(usage.tokens))) : request.contextBudget + 1;
+      const callExceeded = rawCalls > request.ceilings.calls, tokenExceeded = rawTokens > request.contextBudget;
+      reservation.status = outcome === "succeeded" && (callExceeded || tokenExceeded) ? "failed" : outcome;
+      reservation.completedAt = now;
+      reservation.usageRef = {
+        calls: Math.min(rawCalls, request.ceilings.calls + 1),
+        tokens: Math.min(rawTokens, request.contextBudget + 1),
+        outputDigest: reservation.status === "succeeded" && usage.output !== undefined ? digest(usage.output) : null
+      };
+      state.updatedAt = now; write(cwd, state);
+      return {
+        accepted: true, status: reservation.status,
+        reason: callExceeded ? "helper-call-budget-exceeded" : tokenExceeded ? "helper-token-budget-exceeded" : "released"
+      };
+    });
+  }
+  markParentTerminal(cwd: string, requestInput: HelperRequest, now = new Date().toISOString()): void { const request = validateHelperRequest(structuredClone(requestInput)); withLock(cwd, request.taskRunId, () => { const state = read(cwd, request, now); state.terminal = true; for (const item of active(state)) { item.status = "cancelled"; item.completedAt = now; } state.updatedAt = now; write(cwd, state); }); }
+  snapshot(cwd: string, request: HelperRequest, now = new Date().toISOString()): BudgetState { return structuredClone(read(cwd, validateHelperRequest(request), now)); }
+}

package/packages/piagent-core/runtime/orchestration/role-binder.ts

@@ -0,0 +1,48 @@
+import crypto from "node:crypto";
+import type { AuthenticatedModelCatalog, AuthenticatedModelCatalogEntry } from "../model/authenticated-catalog.ts";
+import type { RuntimeModelSnapshot } from "../model/runtime-snapshot.ts";
+import type { SolverDecision, TaskFeatures } from "../solver/solver-types.ts";
+import type { HelperRole, RolePolicy } from "./role-policy.ts";
+import { validateRolePolicy } from "./role-policy.ts";
+
+export const ROLE_BINDER_VERSION = "role-binder-v1" as const;
+export const PROVIDER_ROLE_MAPPING_VERSION = "openai-codex-role-map-v1" as const;
+export type RoleBinding = {
+  version: typeof ROLE_BINDER_VERSION; mappingVersion: typeof PROVIDER_ROLE_MAPPING_VERSION; role: HelperRole;
+  disposition: "recommended" | "unavailable" | "parent-no-helper"; provider: string | null; modelId: string | null; effort: string | null;
+  parentPreserved: true; reasonCodes: string[]; bindingDigest: string;
+};
+
+const ROLE_CANDIDATES: Record<HelperRole, Array<{ tier: "luna" | "terra" | "sol"; effort: string }>> = {
+  retriever: [{ tier: "luna", effort: "low" }, { tier: "luna", effort: "medium" }],
+  scout: [{ tier: "luna", effort: "medium" }],
+  planner: [{ tier: "terra", effort: "high" }],
+  worker: [{ tier: "terra", effort: "medium" }],
+  reviewer: [{ tier: "terra", effort: "high" }],
+  oracle: [{ tier: "sol", effort: "xhigh" }, { tier: "sol", effort: "high" }],
+  researcher: [{ tier: "terra", effort: "medium" }]
+};
+
+function digest(value: unknown): string { return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function tier(entry: AuthenticatedModelCatalogEntry, expected: string): boolean { return new RegExp(`(?:^|[-_/])${expected}(?:$|[-_/])`, "i").test(entry.modelId); }
+function result(role: HelperRole, disposition: RoleBinding["disposition"], parent: RuntimeModelSnapshot, reasonCodes: string[], model?: AuthenticatedModelCatalogEntry, effort?: string): RoleBinding {
+  const base = { version: ROLE_BINDER_VERSION, mappingVersion: PROVIDER_ROLE_MAPPING_VERSION, role, disposition, provider: model?.provider ?? null, modelId: model?.modelId ?? null, effort: effort ?? null, parentPreserved: true as const, reasonCodes };
+  return { ...base, bindingDigest: digest(base) };
+}
+
+export function bindRole(input: { policy: RolePolicy; features: TaskFeatures; solver: SolverDecision; runtime: RuntimeModelSnapshot; catalog: AuthenticatedModelCatalog; helperBudgetAvailable: boolean; workerExplicitlyEnabled?: boolean }): RoleBinding {
+  const policy = validateRolePolicy(input.policy); const parent = input.runtime;
+  if (!input.helperBudgetAvailable) return result(policy.role, "parent-no-helper", parent, ["helper-budget-unavailable"]);
+  if (input.features.riskLane === "tiny") return result(policy.role, "parent-no-helper", parent, ["tiny-task-solo"]);
+  if (policy.role === "worker" && !input.workerExplicitlyEnabled) return result(policy.role, "parent-no-helper", parent, ["worker-disabled-default"]);
+  if (input.features.externalAction || input.features.destructiveAction || input.features.permissionExpansion) return result(policy.role, "parent-no-helper", parent, ["approval-action-not-delegated"]);
+  if (input.catalog.availability !== "authenticated") return result(policy.role, "unavailable", parent, ["authenticated-catalog-unavailable"]);
+  for (const candidate of ROLE_CANDIDATES[policy.role]) {
+    const matches = input.catalog.models.filter((model) => tier(model, candidate.tier));
+    for (const model of matches) {
+      if (model.supportedThinkingLevels !== null && !model.supportedThinkingLevels.includes(candidate.effort)) continue;
+      return result(policy.role, "recommended", parent, [`role-${policy.role}`, `tier-${candidate.tier}`, "runtime-catalog-match"], model, candidate.effort);
+    }
+  }
+  return result(policy.role, "unavailable", parent, ["preferred-model-or-effort-unavailable", "parent-preserved-no-substitution"]);
+}

package/packages/piagent-core/runtime/orchestration/role-policy.ts

@@ -0,0 +1,113 @@
+import crypto from "node:crypto";
+import { globMatchesPath, normalizePathCandidate } from "../../extensions/policy-core.js";
+
+export const ROLE_POLICY_SCHEMA_VERSION = 1 as const;
+export const ROLE_POLICY_VERSION = "role-policy-v1" as const;
+export const HELPER_REQUEST_SCHEMA_VERSION = 1 as const;
+export const HELPER_ROLES = Object.freeze(["retriever", "scout", "planner", "worker", "reviewer", "oracle", "researcher"] as const);
+export type HelperRole = typeof HELPER_ROLES[number];
+export type HelperAuthority = "read-only" | "single-writer";
+export type RolePolicy = {
+  schemaVersion: 1; policyVersion: typeof ROLE_POLICY_VERSION; role: HelperRole; authority: HelperAuthority;
+  enabledByDefault: boolean; readScope: string[]; writeScope: string[]; allowedTools: string[];
+  modelSelectionSource: "runtime-catalog" | "parent"; effortSelectionSource: "runtime-snapshot" | "parent";
+  contextBudget: number; ceilings: { timeSeconds: number; calls: number; retries: number };
+  outputSchema: string; stoppingRule: string; approvalRestrictions: string[];
+};
+export type HelperRequest = {
+  schemaVersion: 1; policyVersion: typeof ROLE_POLICY_VERSION; role: HelperRole; objectiveHash: string; objectiveText: string;
+  taskId: string; taskRunId: string; sessionHash: string; authority: HelperAuthority; readScope: string[]; writeScope: string[];
+  allowedTools: string[]; model: { provider: string; modelId: string; effort: string; source: string } | null;
+  contextBudget: number; ceilings: { timeSeconds: number; calls: number; retries: number }; outputSchema: string;
+  stoppingRule: string; approvalRestrictions: string[]; parentAuthorityDigest: string; singleWriterOwnership: string | null;
+  deduplicationKey: string;
+};
+
+const READ_TOOLS = ["read", "grep", "find", "ls"];
+const MUTATION_TOOLS = new Set(["edit", "write", "apply_patch", "bash", "contact_supervisor"]);
+const HASH = /^[a-f0-9]{64}$/;
+const REF = /^[a-z0-9][a-z0-9:._/-]{0,255}$/i;
+const ROLE_FIELDS = new Set(["schemaVersion", "policyVersion", "role", "authority", "enabledByDefault", "readScope", "writeScope", "allowedTools", "modelSelectionSource", "effortSelectionSource", "contextBudget", "ceilings", "outputSchema", "stoppingRule", "approvalRestrictions"]);
+const REQUEST_FIELDS = new Set(["schemaVersion", "policyVersion", "role", "objectiveHash", "objectiveText", "taskId", "taskRunId", "sessionHash", "authority", "readScope", "writeScope", "allowedTools", "model", "contextBudget", "ceilings", "outputSchema", "stoppingRule", "approvalRestrictions", "parentAuthorityDigest", "singleWriterOwnership", "deduplicationKey"]);
+
+function object(value: unknown): Record<string, any> | undefined { return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : undefined; }
+function exact(value: Record<string, any>, fields: Set<string>, label: string): string[] { return [...Object.keys(value).filter((field) => !fields.has(field)).map((field) => `${label} unknown field: ${field}`), ...[...fields].filter((field) => !(field in value)).map((field) => `${label} missing field: ${field}`)]; }
+function strings(value: unknown, max: number, itemMax = 300): value is string[] { return Array.isArray(value) && value.length <= max && new Set(value).size === value.length && value.every((item) => typeof item === "string" && item.length > 0 && item.length <= itemMax); }
+function ceilings(value: unknown): boolean { const item = object(value); return Boolean(item && exact(item, new Set(["timeSeconds", "calls", "retries"]), "ceilings").length === 0 && Number.isInteger(item.timeSeconds) && item.timeSeconds >= 1 && item.timeSeconds <= 3600 && Number.isInteger(item.calls) && item.calls >= 1 && item.calls <= 100 && Number.isInteger(item.retries) && item.retries >= 0 && item.retries <= 3); }
+function digest(value: unknown): string { return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function boundedObjective(value: unknown): string { return String(value ?? "").replace(/\s+/g, " ").trim().slice(0, 1000); }
+function safeScopePattern(value: string): boolean {
+  const normalized = normalizePathCandidate(value);
+  return Boolean(normalized && !/^\/|^[A-Za-z]:\//.test(normalized) && !normalized.split("/").some((part) => part === "." || part === "..") && !/[?\[\]{}\0]/.test(normalized));
+}
+function scopeCovers(parent: string, child: string): boolean {
+  const allowed = normalizePathCandidate(parent), requested = normalizePathCandidate(child);
+  if (!safeScopePattern(allowed) || !safeScopePattern(requested)) return false;
+  if (allowed === "**" || allowed === requested) return true;
+  if (allowed.endsWith("/**")) {
+    const prefix = allowed.slice(0, -3); return requested === prefix || requested.startsWith(`${prefix}/`);
+  }
+  return !requested.includes("*") && globMatchesPath(allowed, requested);
+}
+function scopeSubset(child: string[], parent: string[]): boolean { return child.every((item) => parent.some((allowed) => scopeCovers(allowed, item))); }
+
+export function rolePolicyValidationErrors(input: unknown): string[] {
+  const value = object(input); if (!value) return ["role policy must be an object"];
+  const errors = exact(value, ROLE_FIELDS, "role policy");
+  if (value.schemaVersion !== 1 || value.policyVersion !== ROLE_POLICY_VERSION || !HELPER_ROLES.includes(value.role)) errors.push("role policy identity is invalid");
+  if (!["read-only", "single-writer"].includes(value.authority) || typeof value.enabledByDefault !== "boolean") errors.push("role authority/default is invalid");
+  if (!strings(value.readScope, 100) || !strings(value.writeScope, 100) || !strings(value.allowedTools, 32) || !strings(value.approvalRestrictions, 16)) errors.push("role policy collections are invalid");
+  if (value.authority === "read-only" && (value.writeScope.length > 0 || value.allowedTools.some((tool: string) => MUTATION_TOOLS.has(tool)))) errors.push("read-only role cannot receive mutation authority");
+  if (value.role === "worker" && (value.enabledByDefault || value.authority !== "single-writer")) errors.push("worker must be disabled by default and single-writer");
+  if (value.modelSelectionSource !== "runtime-catalog" || !["runtime-snapshot", "parent"].includes(value.effortSelectionSource)) errors.push("selection source is invalid");
+  if (!Number.isInteger(value.contextBudget) || value.contextBudget < 256 || value.contextBudget > 100000 || !ceilings(value.ceilings)) errors.push("role budgets are invalid");
+  if (typeof value.outputSchema !== "string" || value.outputSchema.length < 3 || value.outputSchema.length > 200 || typeof value.stoppingRule !== "string" || value.stoppingRule.length < 3 || value.stoppingRule.length > 500) errors.push("output/stopping contract is invalid");
+  return errors;
+}
+export function validateRolePolicy(input: unknown): RolePolicy { const errors = rolePolicyValidationErrors(input); if (errors.length) throw new Error(errors.join("; ")); return input as RolePolicy; }
+
+export function helperRequestValidationErrors(input: unknown): string[] {
+  const value = object(input); if (!value) return ["helper request must be an object"];
+  const errors = exact(value, REQUEST_FIELDS, "helper request");
+  if (value.schemaVersion !== 1 || value.policyVersion !== ROLE_POLICY_VERSION || !HELPER_ROLES.includes(value.role) || !HASH.test(String(value.objectiveHash)) || !HASH.test(String(value.sessionHash)) || !HASH.test(String(value.parentAuthorityDigest)) || !HASH.test(String(value.deduplicationKey))) errors.push("helper identity/digests are invalid");
+  if (typeof value.objectiveText !== "string" || value.objectiveText.length < 3 || value.objectiveText.length > 1000 || !REF.test(String(value.taskId)) || !REF.test(String(value.taskRunId))) errors.push("helper objective/task identity is invalid");
+  if (!["read-only", "single-writer"].includes(value.authority) || !strings(value.readScope, 100) || !strings(value.writeScope, 100) || !value.readScope.every(safeScopePattern) || !value.writeScope.every(safeScopePattern) || !strings(value.allowedTools, 32) || !strings(value.approvalRestrictions, 16)) errors.push("helper authority collections are invalid");
+  if (value.authority === "read-only" && (value.writeScope.length > 0 || value.allowedTools.some((tool: string) => MUTATION_TOOLS.has(tool)))) errors.push("read-only helper cannot mutate");
+  if (value.role === "worker" && (value.authority !== "single-writer" || typeof value.singleWriterOwnership !== "string" || !REF.test(value.singleWriterOwnership))) errors.push("worker requires explicit single-writer ownership");
+  if (value.role !== "worker" && value.singleWriterOwnership !== null) errors.push("read-only helper cannot own a writer lease");
+  if (!Number.isInteger(value.contextBudget) || value.contextBudget < 256 || value.contextBudget > 100000 || !ceilings(value.ceilings)) errors.push("helper budgets are invalid");
+  if (typeof value.outputSchema !== "string" || value.outputSchema.length > 200 || typeof value.stoppingRule !== "string" || value.stoppingRule.length > 500) errors.push("helper output/stopping contract is invalid");
+  const model = value.model === null ? null : object(value.model);
+  if (value.model !== null && (!model || exact(model, new Set(["provider", "modelId", "effort", "source"]), "model").length || ![model.provider, model.modelId, model.effort, model.source].every((item) => typeof item === "string" && item.length > 0 && item.length <= 160))) errors.push("helper model binding is invalid");
+  return errors;
+}
+export function validateHelperRequest(input: unknown): HelperRequest { const errors = helperRequestValidationErrors(input); if (errors.length) throw new Error(errors.join("; ")); return input as HelperRequest; }
+
+export function defaultRolePolicy(role: HelperRole, scope: string[] = ["**"]): RolePolicy {
+  const readOnly = role !== "worker";
+  const policy: RolePolicy = {
+    schemaVersion: 1, policyVersion: ROLE_POLICY_VERSION, role, authority: readOnly ? "read-only" : "single-writer",
+    enabledByDefault: readOnly, readScope: [...scope], writeScope: [], allowedTools: readOnly ? [...READ_TOOLS] : [...READ_TOOLS, "bash", "edit", "write", "contact_supervisor"],
+    modelSelectionSource: "runtime-catalog", effortSelectionSource: "runtime-snapshot", contextBudget: role === "oracle" ? 12000 : role === "reviewer" ? 9000 : 6000,
+    ceilings: { timeSeconds: role === "oracle" ? 900 : 600, calls: role === "retriever" ? 20 : 40, retries: 0 },
+    outputSchema: `${role}-result-v1`, stoppingRule: "Stop when the bounded objective is answered or evidence is insufficient; return uncertainty.",
+    approvalRestrictions: ["no-external-write", "no-destructive-action", "no-permission-expansion"]
+  };
+  return validateRolePolicy(policy);
+}
+
+export function createHelperRequest(input: { policy: RolePolicy; objective: string; taskId: string; taskRunId: string; sessionId: string; parentReadScope: string[]; parentWriteScope: string[]; parentAllowedTools: string[]; requestedReadScope?: string[]; requestedWriteScope?: string[]; model?: HelperRequest["model"]; singleWriterOwnership?: string | null }): HelperRequest {
+  const policy = validateRolePolicy(input.policy); const objectiveText = boundedObjective(input.objective);
+  const readScope = input.requestedReadScope ?? policy.readScope; const writeScope = input.requestedWriteScope ?? policy.writeScope;
+  if (!scopeSubset(readScope, input.parentReadScope) || !scopeSubset(writeScope, input.parentWriteScope)) throw new Error("helper request cannot broaden parent scope");
+  if (policy.allowedTools.some((tool) => !input.parentAllowedTools.includes(tool))) throw new Error("helper request cannot broaden parent tools");
+  const authority = policy.authority;
+  const request: HelperRequest = {
+    schemaVersion: 1, policyVersion: ROLE_POLICY_VERSION, role: policy.role, objectiveHash: digest(objectiveText), objectiveText,
+    taskId: input.taskId, taskRunId: input.taskRunId, sessionHash: digest(input.sessionId), authority, readScope: [...readScope], writeScope: [...writeScope], allowedTools: [...policy.allowedTools],
+    model: input.model ?? null, contextBudget: policy.contextBudget, ceilings: { ...policy.ceilings }, outputSchema: policy.outputSchema, stoppingRule: policy.stoppingRule,
+    approvalRestrictions: [...policy.approvalRestrictions], parentAuthorityDigest: digest({ read: input.parentReadScope, write: input.parentWriteScope, tools: input.parentAllowedTools }),
+    singleWriterOwnership: input.singleWriterOwnership ?? null, deduplicationKey: digest({ role: policy.role, objective: objectiveText, readScope, writeScope })
+  };
+  return validateHelperRequest(request);
+}

package/packages/piagent-core/runtime/policy/authority-manifest.ts

@@ -0,0 +1,4 @@
+// Compatibility boundary: the authority implementation lives in the capability
+// layer so both core Task Contract code and runtime consumers can depend on it
+// without reversing the core -> runtime architecture boundary.
+export * from "../../capabilities/authority-manifest.ts";

package/packages/piagent-core/runtime/policy/authority-resume-policy.ts

@@ -0,0 +1,227 @@
+import crypto from "node:crypto";
+
+import {
+  AUTHORITY_PROFILE_IDS,
+  inspectAuthoritySnapshotCompatibility,
+  type AuthorityProfileId
+} from "../../capabilities/authority-manifest.ts";
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { appendTaskJournalEventAtMost, readTaskJournal } from "../../extensions/task-journal.js";
+
+export const AUTHORITY_RESUME_POLICY_VERSION = "authority-resume-v1" as const;
+export const AUTHORITY_RESUME_EVENT_TYPE = "authority-new-attempt-required" as const;
+
+export type AuthorityResumeReason =
+  | "compatible"
+  | "missing-task-snapshot"
+  | "task-identity-mismatch"
+  | "unknown-snapshot-version"
+  | "unknown-manifest-version"
+  | "manifest-digest-mismatch"
+  | "invalid-snapshot"
+  | "mechanical-rollback-requested"
+  | "capability-kill-switch-requested"
+  | "authority-journal-corrupt"
+  | "authority-resume-state-invalid";
+
+export type AuthorityResumeDecision = {
+  policyVersion: typeof AUTHORITY_RESUME_POLICY_VERSION;
+  disposition: "resume-pinned" | "new-attempt-required" | "blocked";
+  enforcementSafe: boolean;
+  reason: AuthorityResumeReason;
+  pinnedProfile: AuthorityProfileId | null;
+  requestedProfile: AuthorityProfileId | null;
+  killedCapabilities: string[];
+  persisted: boolean;
+  recordedAt: string | null;
+};
+
+type ResumeInput = {
+  authorityProfile?: AuthorityProfileId;
+  environment?: NodeJS.ProcessEnv;
+  recordedAt?: string;
+};
+
+const OFF_VALUES = new Set(["0", "false", "no", "off", "disabled"]);
+const FEATURE_KILL_SWITCHES = Object.freeze([
+  ["PIAGENT_AUTO_CONTEXT", "CAP-05"],
+  ["PIAGENT_DYNAMIC_TOOLS", "CAP-06"],
+  ["PIAGENT_SOLVER_MODE", "CAP-08"],
+  ["PIAGENT_PHASE_TOOLS", "CAP-09"],
+  ["PIAGENT_ACCEPTANCE_ASSURANCE", "CAP-11"],
+  ["PIAGENT_AUTO_RECOVERY", "CAP-12"],
+  ["PIAGENT_SEMANTIC_REPAIR", "CAP-13"],
+  ["PIAGENT_HELPERS_MODE", "CAP-14"],
+  ["PIAGENT_PARENT_ROUTING", "CAP-15"],
+  ["PIAGENT_CONTEXT_TELEMETRY", "CAP-17"]
+] as const);
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+
+function requestedProfile(input: ResumeInput): AuthorityProfileId | null {
+  if (input.authorityProfile) return input.authorityProfile;
+  const value = String(input.environment?.PIAGENT_AUTHORITY_PROFILE ?? "").trim().toLowerCase();
+  return (AUTHORITY_PROFILE_IDS as readonly string[]).includes(value) ? value as AuthorityProfileId : null;
+}
+
+function explicitKilledCapabilities(task: TaskContract, environment: NodeJS.ProcessEnv | undefined): string[] {
+  if (!environment || !task.authoritySnapshot) return [];
+  return FEATURE_KILL_SWITCHES
+    .filter(([name, capabilityId]) => {
+      const value = environment[name];
+      const pinned = task.authoritySnapshot?.capabilities.find((entry) => entry.id === capabilityId);
+      return value !== undefined && OFF_VALUES.has(String(value).trim().toLowerCase()) && pinned?.authority !== "off";
+    })
+    .map(([, capabilityId]) => capabilityId)
+    .sort();
+}
+
+function snapshotDigest(task: TaskContract): string | null {
+  const value = task.authoritySnapshot?.snapshotDigest;
+  return typeof value === "string" && SHA256.test(value) ? value : null;
+}
+
+function eventKey(task: TaskContract, reason: AuthorityResumeReason, profile: AuthorityProfileId | null, killed: string[]): string {
+  const payload = JSON.stringify({
+    taskId: task.taskId,
+    taskRunId: task.taskRunId,
+    createdAt: task.createdAt,
+    authoritySnapshotDigest: snapshotDigest(task),
+    reason,
+    requestedProfile: profile,
+    killedCapabilities: killed
+  });
+  return `sha256:${crypto.createHash("sha256").update("piagent-authority-resume-v1\n").update(payload).digest("hex")}`;
+}
+
+function baseDecision(task: TaskContract, input: ResumeInput): AuthorityResumeDecision {
+  const pinnedProfile = task.authoritySnapshot?.profile ?? null;
+  const profile = requestedProfile(input);
+  const killed = explicitKilledCapabilities(task, input.environment);
+  if (!task.authoritySnapshot) return decision("new-attempt-required", "missing-task-snapshot", pinnedProfile, profile, killed);
+  if (task.authoritySnapshot.taskId !== task.taskId
+    || task.authoritySnapshot.taskRunId !== task.taskRunId
+    || task.authoritySnapshot.capturedAt !== task.createdAt) {
+    return decision("new-attempt-required", "task-identity-mismatch", pinnedProfile, profile, killed);
+  }
+  const compatibility = inspectAuthoritySnapshotCompatibility(task.authoritySnapshot);
+  if (compatibility.disposition !== "resume-pinned") {
+    return decision("new-attempt-required", compatibility.reason, pinnedProfile, profile, killed);
+  }
+  if (profile === "mechanical-only" && pinnedProfile !== "mechanical-only") {
+    return decision("new-attempt-required", "mechanical-rollback-requested", pinnedProfile, profile, killed);
+  }
+  if (killed.length > 0) {
+    return decision("new-attempt-required", "capability-kill-switch-requested", pinnedProfile, profile, killed);
+  }
+  return decision("resume-pinned", "compatible", pinnedProfile, profile, []);
+}
+
+function decision(
+  disposition: AuthorityResumeDecision["disposition"],
+  reason: AuthorityResumeReason,
+  pinnedProfile: AuthorityProfileId | null,
+  profile: AuthorityProfileId | null,
+  killedCapabilities: string[],
+  persisted = false,
+  recordedAt: string | null = null
+): AuthorityResumeDecision {
+  return {
+    policyVersion: AUTHORITY_RESUME_POLICY_VERSION,
+    disposition,
+    enforcementSafe: disposition !== "blocked",
+    reason,
+    pinnedProfile,
+    requestedProfile: profile,
+    killedCapabilities,
+    persisted,
+    recordedAt
+  };
+}
+
+function persistedDecision(cwd: string, task: TaskContract): AuthorityResumeDecision | undefined {
+  const journal = readTaskJournal(cwd, { taskRunId: task.taskRunId });
+  if (journal.corruptions.length > 0) {
+    return decision("blocked", "authority-journal-corrupt", task.authoritySnapshot?.profile ?? null, null, []);
+  }
+  const events = journal.events.filter((event: any) => event.eventType === AUTHORITY_RESUME_EVENT_TYPE);
+  if (events.length === 0) return undefined;
+  if (events.length !== 1) return decision("blocked", "authority-resume-state-invalid", task.authoritySnapshot?.profile ?? null, null, []);
+  const event = events[0] as any, data = event.data;
+  const profile = data?.requestedProfile === null || AUTHORITY_PROFILE_IDS.includes(data?.requestedProfile) ? data?.requestedProfile ?? null : undefined;
+  const killed = Array.isArray(data?.killedCapabilities)
+    ? data.killedCapabilities.filter((value: unknown): value is string => typeof value === "string")
+    : [];
+  const valid = event.taskId === task.taskId
+    && event.taskRunId === task.taskRunId
+    && data?.policyVersion === AUTHORITY_RESUME_POLICY_VERSION
+    && data?.taskCreatedAt === task.createdAt
+    && data?.authoritySnapshotDigest === snapshotDigest(task)
+    && ["missing-task-snapshot", "task-identity-mismatch", "unknown-snapshot-version", "unknown-manifest-version", "manifest-digest-mismatch", "invalid-snapshot", "mechanical-rollback-requested", "capability-kill-switch-requested"].includes(data?.reason)
+    && profile !== undefined
+    && killed.length === (data?.killedCapabilities?.length ?? -1)
+    && JSON.stringify(killed) === JSON.stringify([...new Set(killed)].sort())
+    && event.idempotencyKey === eventKey(task, data.reason, profile, killed);
+  if (!valid) return decision("blocked", "authority-resume-state-invalid", task.authoritySnapshot?.profile ?? null, null, []);
+  return decision("new-attempt-required", data.reason, task.authoritySnapshot?.profile ?? null, profile, killed, true, event.recordedAt);
+}
+
+export function inspectTaskAuthorityResumePolicy(cwd: string, task: TaskContract, input: ResumeInput = {}): AuthorityResumeDecision {
+  return persistedDecision(cwd, task) ?? baseDecision(task, input);
+}
+
+export function ensureTaskAuthorityResumePolicy(cwd: string, task: TaskContract, input: ResumeInput = {}): AuthorityResumeDecision {
+  const current = inspectTaskAuthorityResumePolicy(cwd, task, input);
+  if (current.disposition !== "new-attempt-required" || current.persisted) return current;
+  const key = eventKey(task, current.reason, current.requestedProfile, current.killedCapabilities);
+  try {
+    appendTaskJournalEventAtMost(cwd, {
+      eventType: AUTHORITY_RESUME_EVENT_TYPE,
+      taskId: task.taskId,
+      taskRunId: task.taskRunId,
+      sessionId: task.sessionId,
+      sessionName: task.sessionName,
+      idempotencyKey: key,
+      data: {
+        policyVersion: AUTHORITY_RESUME_POLICY_VERSION,
+        taskCreatedAt: task.createdAt,
+        authoritySnapshotDigest: snapshotDigest(task),
+        reason: current.reason,
+        requestedProfile: current.requestedProfile,
+        killedCapabilities: current.killedCapabilities
+      }
+    }, { maximum: 1, recordedAt: input.recordedAt });
+  } catch {
+    return decision("blocked", "authority-journal-corrupt", current.pinnedProfile, current.requestedProfile, current.killedCapabilities);
+  }
+  return persistedDecision(cwd, task)
+    ?? decision("blocked", "authority-resume-state-invalid", current.pinnedProfile, current.requestedProfile, current.killedCapabilities);
+}
+
+export function authorityReplacementState(cwd: string, task: TaskContract): {
+  required: boolean;
+  enforcementSafe: boolean;
+  reason: AuthorityResumeReason | null;
+  recordedAt: string | null;
+  requestedProfile: AuthorityProfileId | null;
+  killedCapabilities: string[];
+} {
+  const persisted = persistedDecision(cwd, task);
+  if (!persisted) {
+    return {
+      required: false,
+      enforcementSafe: true,
+      reason: null,
+      recordedAt: null,
+      requestedProfile: null,
+      killedCapabilities: []
+    };
+  }
+  return {
+    required: persisted.disposition === "new-attempt-required" && persisted.persisted,
+    enforcementSafe: persisted.enforcementSafe,
+    reason: persisted.reason,
+    recordedAt: persisted.recordedAt,
+    requestedProfile: persisted.requestedProfile,
+    killedCapabilities: persisted.killedCapabilities
+  };
+}

package/packages/piagent-core/runtime/policy/task-authority-runtime.ts

@@ -0,0 +1,115 @@
+import {
+  createTaskAuthoritySnapshot,
+  taskAuthoritySnapshotValidationErrors,
+  type AuthorityProfileId,
+  type NormalizedAuthority,
+  type TaskAuthorityEntry,
+  type TaskAuthoritySnapshot
+} from "../../capabilities/authority-manifest.ts";
+import { parentRoutingModeFromEnvironment } from "../model/model-route-policy.ts";
+import { helpersMode } from "../orchestration/helper-lifecycle.ts";
+import { solverModeFromEnvironment } from "../solver/solver-shadow.ts";
+import { phaseToolModeFromEnvironment } from "../tools/phase-tool-runtime.ts";
+
+export type AuthorityAction = "observe" | "advise" | "block" | "mutate" | "model-turn" | "dispatch";
+export type TaskAuthorityCarrier = {
+  taskId: string;
+  taskRunId: string;
+  createdAt: string;
+  authoritySnapshot?: TaskAuthoritySnapshot;
+};
+export type TaskAuthorityDecision = {
+  allowed: boolean;
+  capabilityId: string;
+  action: AuthorityAction;
+  authority: NormalizedAuthority | "legacy-unbound";
+  mode: string;
+  reason: "allowed" | "authority-too-low" | "budget-not-declared" | "missing-task-snapshot" | "invalid-task-snapshot" | "task-identity-mismatch";
+  entry?: TaskAuthorityEntry;
+};
+
+const LEGACY_HARD_INVARIANTS = new Set(["CAP-01", "CAP-02", "CAP-03", "CAP-04"]);
+
+function snapshotDisposition(task: TaskAuthorityCarrier): { snapshot?: TaskAuthoritySnapshot; reason?: TaskAuthorityDecision["reason"] } {
+  if (!task.authoritySnapshot) return { reason: "missing-task-snapshot" };
+  if (taskAuthoritySnapshotValidationErrors(task.authoritySnapshot).length > 0) return { reason: "invalid-task-snapshot" };
+  if (task.authoritySnapshot.taskId !== task.taskId || task.authoritySnapshot.taskRunId !== task.taskRunId || task.authoritySnapshot.capturedAt !== task.createdAt) {
+    return { reason: "task-identity-mismatch" };
+  }
+  return { snapshot: task.authoritySnapshot };
+}
+
+function actionAllowed(entry: TaskAuthorityEntry, action: AuthorityAction): boolean {
+  if (entry.authority === "off") return false;
+  if (action === "observe") return true;
+  if (action === "advise") return entry.authority === "advise" || entry.authority === "enforce" || entry.authority === "orchestrate";
+  if (action === "block" || action === "mutate") return entry.authority === "enforce" || entry.authority === "orchestrate";
+  if (action === "dispatch") return entry.authority === "orchestrate" && entry.budgets.automaticDispatches > 0;
+  return (entry.authority === "enforce" || entry.authority === "orchestrate")
+    && (entry.budgets.systemContinuations > 0 || entry.budgets.reviewRounds > 0 || entry.budgets.automaticDispatches > 0);
+}
+
+export function taskAuthorityDecision(task: TaskAuthorityCarrier, capabilityId: string, action: AuthorityAction): TaskAuthorityDecision {
+  const disposition = snapshotDisposition(task);
+  if (!disposition.snapshot) {
+    const legacyHardInvariant = LEGACY_HARD_INVARIANTS.has(capabilityId) && ["observe", "advise", "block", "mutate"].includes(action);
+    return { allowed: legacyHardInvariant, capabilityId, action, authority: "legacy-unbound", mode: "legacy-unbound", reason: legacyHardInvariant ? "allowed" : disposition.reason as TaskAuthorityDecision["reason"] };
+  }
+  const entry = disposition.snapshot.capabilities.find((candidate) => candidate.id === capabilityId);
+  if (!entry) return { allowed: false, capabilityId, action, authority: "legacy-unbound", mode: "invalid", reason: "invalid-task-snapshot" };
+  const allowed = actionAllowed(entry, action);
+  const budgetMissing = (action === "model-turn" || action === "dispatch") && ["enforce", "orchestrate"].includes(entry.authority) && !allowed;
+  return { allowed, capabilityId, action, authority: entry.authority, mode: entry.mode, reason: allowed ? "allowed" : budgetMissing ? "budget-not-declared" : "authority-too-low", entry };
+}
+
+export function taskAuthorityMode(task: TaskAuthorityCarrier, capabilityId: string): string {
+  const disposition = snapshotDisposition(task);
+  return disposition.snapshot?.capabilities.find((candidate) => candidate.id === capabilityId)?.mode ?? "off";
+}
+
+export function createBoundTaskAuthority(input: { taskId: string; taskRunId: string; createdAt: string; profile?: AuthorityProfileId }): TaskAuthoritySnapshot {
+  return createTaskAuthoritySnapshot({ taskId: input.taskId, taskRunId: input.taskRunId, capturedAt: input.createdAt, profile: input.profile ?? "broad-default" });
+}
+
+export function taskAuthorityProfileFromEnvironment(value = process.env.PIAGENT_AUTHORITY_PROFILE): AuthorityProfileId {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  return normalized === "mechanical-only" || normalized === "strict-high-risk" ? normalized : "broad-default";
+}
+
+function featureMode(value: string | undefined): "off" | "on" | undefined {
+  if (value === undefined || !value.trim()) return undefined;
+  return ["0", "false", "no", "off", "disabled"].includes(value.trim().toLowerCase()) ? "off" : "on";
+}
+
+function explicitOff(value: string | undefined): "off" | undefined {
+  return value !== undefined && ["0", "false", "no", "off", "disabled"].includes(value.trim().toLowerCase()) ? "off" : undefined;
+}
+
+export function createEnvironmentBoundTaskAuthority(
+  input: { taskId: string; taskRunId: string; createdAt: string; profile?: AuthorityProfileId },
+  environment: NodeJS.ProcessEnv = process.env
+): TaskAuthoritySnapshot {
+  const profile = input.profile ?? taskAuthorityProfileFromEnvironment(environment.PIAGENT_AUTHORITY_PROFILE);
+  const overrides: Record<string, string> = {};
+  const autoContext = featureMode(environment.PIAGENT_AUTO_CONTEXT), dynamicTools = featureMode(environment.PIAGENT_DYNAMIC_TOOLS);
+  const recovery = featureMode(environment.PIAGENT_AUTO_RECOVERY), telemetry = featureMode(environment.PIAGENT_CONTEXT_TELEMETRY);
+  const assurance = explicitOff(environment.PIAGENT_ACCEPTANCE_ASSURANCE), semanticRepair = explicitOff(environment.PIAGENT_SEMANTIC_REPAIR);
+  if (autoContext) overrides["CAP-05"] = autoContext;
+  if (dynamicTools) overrides["CAP-06"] = dynamicTools;
+  if (environment.PIAGENT_SOLVER_MODE !== undefined) overrides["CAP-08"] = solverModeFromEnvironment(environment.PIAGENT_SOLVER_MODE);
+  if (environment.PIAGENT_PHASE_TOOLS !== undefined) overrides["CAP-09"] = phaseToolModeFromEnvironment(environment.PIAGENT_PHASE_TOOLS);
+  if (recovery) overrides["CAP-12"] = recovery;
+  if (environment.PIAGENT_HELPERS_MODE !== undefined) overrides["CAP-14"] = helpersMode(environment.PIAGENT_HELPERS_MODE);
+  if (environment.PIAGENT_PARENT_ROUTING !== undefined) overrides["CAP-15"] = parentRoutingModeFromEnvironment(environment.PIAGENT_PARENT_ROUTING);
+  if (telemetry) overrides["CAP-17"] = telemetry;
+  if (assurance) overrides["CAP-11"] = assurance;
+  if (semanticRepair) overrides["CAP-13"] = semanticRepair;
+  if (profile === "mechanical-only") {
+    for (const [capabilityId, mode] of Object.entries(overrides)) if (mode !== "off") delete overrides[capabilityId];
+  }
+  if (overrides["CAP-05"] === "off") Object.assign(overrides, { "CAP-07": "off", "CAP-08": "off", "CAP-14": "off", "CAP-15": "off" });
+  if (overrides["CAP-08"] === "off") Object.assign(overrides, { "CAP-14": "off", "CAP-15": "off" });
+  if (overrides["CAP-14"] === "off") overrides["CAP-15"] = "off";
+  if (overrides["CAP-09"] === "off" || overrides["CAP-11"] === "off" || overrides["CAP-12"] === "off") overrides["CAP-13"] = "off";
+  return createTaskAuthoritySnapshot({ taskId: input.taskId, taskRunId: input.taskRunId, capturedAt: input.createdAt, profile, modeOverrides: overrides, resolutionSource: Object.keys(overrides).length > 0 ? "explicit-overrides" : "profile" });
+}