pactive 0.0.0-stage → 0.0.2-alpha.1

package/pi/extension.ts

@@ -0,0 +1,420 @@
+/**
+ * Pactive — Pi extension (the single shipped entry (Pi loads this .ts directly via jiti; there is no dist copy)).
+ *
+ * Surface:
+ *   - tools: `pactive_status`, `pactive_schedule`
+ *   - command: `/pactive status|tasks|schedule <when> <prompt>|help`
+ *   - events: session_start / input / agent_start / tool_execution_start /
+ *     message_end / agent_settled / session_shutdown → activity + control tracking
+ *
+ * The extension never throws into the host: every core interaction is wrapped
+ * in try/catch and degrades to a readable message.
+ *
+ * unverified (Pi 1.4.0 host API):
+ *   - the event names below come from the Pi extension docs; the payload shapes
+ *     are not used except for `ctx.sessionManager.getSessionId()`.
+ *   - `parameters` (JSON Schema) is used as the tool schema field; the detailed
+ *     design wrote `schema` — the shipped Pi examples use `parameters`.
+ *   - `src/core/index.mjs` is loaded by relative path at runtime; the argument
+ *     shapes of loadState/saveState/mutateState are not frozen yet, so several
+ *     plausible shapes are tried before falling back to an explicit write.
+ */
+
+/** Minimal mirror of the host API (kept local so the extension stays dependency-free). */
+export interface PactiveToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details?: Record<string, unknown>;
+}
+
+export interface PactiveToolDefinition {
+	name: string;
+	label?: string;
+	description: string;
+	parameters: Record<string, unknown>;
+	execute(
+		toolCallId: string,
+		params: Record<string, any>,
+		signal?: AbortSignal,
+		onUpdate?: (update: unknown) => void,
+		ctx?: unknown,
+	): Promise<PactiveToolResult>;
+}
+
+export interface PactiveExtensionAPI {
+	registerTool(tool: PactiveToolDefinition): void;
+	registerCommand(
+		name: string,
+		definition: {
+			description: string;
+			handler(args: string, ctx: PactiveUiContext): Promise<void> | void;
+		},
+	): void;
+	on(event: string, handler: (event: any, ctx?: any) => void): void;
+}
+
+export interface PactiveUiContext {
+	ui?: { notify?: (message: string, level?: string) => void };
+	sessionManager?: { getSessionId?: () => string | undefined };
+	cwd?: string;
+}
+
+const HOST_KIND = "pi";
+
+/** Relative candidates for the core module (resolved against this file). */
+const CORE_CANDIDATES = ["../src/core/index.mjs", "../../src/core/index.mjs"];
+
+let cachedCore: unknown = null;
+
+function errorText(err: unknown): string {
+	return String((err as { message?: unknown })?.message ?? err);
+}
+
+/** Load `src/core/index.mjs` lazily; throws a readable error when it is missing. */
+async function loadCore(): Promise<any> {
+	if (cachedCore) return cachedCore;
+	const env = process.env;
+	const explicit = env.PACTIVE_CORE_MODULE;
+	const candidates = explicit ? [explicit, ...CORE_CANDIDATES] : CORE_CANDIDATES;
+	const tried: string[] = [];
+	for (const candidate of candidates) {
+		const href = candidate.startsWith("/")
+			? `file://${candidate}`
+			: new URL(candidate, import.meta.url).href;
+		tried.push(href);
+		try {
+			const mod: any = await import(href);
+			if (mod && typeof mod.resolvePaths === "function") {
+				cachedCore = mod;
+				return mod;
+			}
+		} catch {
+			/* try the next candidate */
+		}
+	}
+	throw new Error(
+		`pactive: core module not found (tried: ${tried.join(", ")}). Build src/core before loading the extension.`,
+	);
+}
+
+async function readState(core: any, paths: any): Promise<any> {
+	for (const args of [[paths.stateFile], [paths]]) {
+		try {
+			const state = await core.loadState(...args);
+			if (state && typeof state === "object") return state;
+		} catch {
+			/* next shape */
+		}
+	}
+	return null;
+}
+
+/**
+ * Mutate the state through core (locking + atomic write), verifying that the
+ * write landed in this host's state file. `fn` must be pure.
+ */
+async function mutateState(core: any, paths: any, fn: (state: any) => any): Promise<any> {
+	const before = (await readState(core, paths)) ?? core.defaultState();
+	const shapes: unknown[][] = [
+		[fn, paths],
+		[paths, fn],
+		[fn],
+	];
+	for (const args of shapes) {
+		try {
+			const out = await core.mutateState(...(args as [any]));
+			const after = await readState(core, paths);
+			if (after) {
+				const wanted = fn(before);
+				if (JSON.stringify(after) !== JSON.stringify(wanted)) {
+					await writeState(core, paths, wanted);
+					return wanted;
+				}
+				return after;
+			}
+			return out ?? fn(before);
+		} catch {
+			/* next shape */
+		}
+	}
+	const after = fn(before);
+	await writeState(core, paths, after);
+	return after;
+}
+
+async function writeState(core: any, paths: any, state: any): Promise<void> {
+	const shapes: unknown[][] = [
+		[paths.stateFile, state],
+		[state, paths.stateFile],
+		[state],
+	];
+	let last: unknown;
+	for (const args of shapes) {
+		try {
+			await core.saveState(...(args as [any]));
+			return;
+		} catch (err) {
+			last = err;
+		}
+	}
+	throw last instanceof Error ? last : new Error(String(last));
+}
+
+/** Parse `10m` / `18:30` / ISO 8601 / `every 1h` into a schedule spec. */
+function parseWhen(when: unknown, now = Date.now()): { kind: string; when: string; at: number | null } | null {
+	const text = typeof when === "string" ? when.trim() : "";
+	if (text === "") return { kind: "in", when: "10m", at: null };
+	const every = /^every\s+(.+)$/i.exec(text);
+	if (every) return { kind: "every", when: every[1].trim(), at: null };
+	const duration = /^(\d+)\s*(s|sec|m|min|h|hour|d|day)$/i.exec(text);
+	if (duration) {
+		const unit = duration[2].toLowerCase();
+		const factor = unit.startsWith("s")
+			? 1000
+			: unit.startsWith("m")
+				? 60000
+				: unit.startsWith("h")
+					? 3600000
+					: 86400000;
+		return { kind: "in", when: text, at: now + Number(duration[1]) * factor };
+	}
+	const clock = /^(\d{1,2}):(\d{2})$/.exec(text);
+	if (clock) {
+		const at = new Date(now);
+		at.setHours(Number(clock[1]), Number(clock[2]), 0, 0);
+		if (at.getTime() <= now) at.setDate(at.getDate() + 1);
+		return { kind: "at", when: text, at: at.getTime() };
+	}
+	const iso = Date.parse(text);
+	if (!Number.isNaN(iso)) return { kind: "at", when: text, at: iso };
+	return null;
+}
+
+function textResult(text: string, details?: Record<string, unknown>): PactiveToolResult {
+	return details ? { content: [{ type: "text", text }], details } : { content: [{ type: "text", text }] };
+}
+
+const STATUS_PARAMETERS = { type: "object", properties: {}, additionalProperties: false };
+const SCHEDULE_PARAMETERS = {
+	type: "object",
+	properties: {
+		prompt: { type: "string", description: "任务正文（到点注入给会话的内容）" },
+		when: { type: "string", description: "触发时间：时长（10m）/ 时刻（18:30）/ ISO 8601 / every 1h" },
+	},
+	required: ["prompt"],
+	additionalProperties: false,
+};
+
+/** Mark an activity kind; never throws. */
+async function markActivity(kind: "user" | "agent" | "session-start" | "session-end" | "tool"): Promise<void> {
+	try {
+		const core = await loadCore();
+		const paths = core.resolvePaths(HOST_KIND, process.env);
+		await mutateState(core, paths, (state) => {
+			const next = core.markActivity(state, kind);
+			return next && typeof next === "object" ? next : state;
+		});
+	} catch (err) {
+		process.stderr.write(`[pactive] markActivity(${kind}): ${errorText(err)}\n`);
+	}
+}
+
+/** Flip the control flag (the agent stopped → control returned to the human). */
+async function markControlReturned(): Promise<void> {
+	try {
+		const core = await loadCore();
+		const paths = core.resolvePaths(HOST_KIND, process.env);
+		await mutateState(core, paths, (state) => {
+			const next = core.markControlReturned(state);
+			return next && typeof next === "object" ? next : state;
+		});
+	} catch (err) {
+		process.stderr.write(`[pactive] markControlReturned: ${errorText(err)}\n`);
+	}
+}
+
+export default function activate(pi: PactiveExtensionAPI): void {
+	pi.registerTool({
+		name: "pactive_status",
+		label: "Pactive Status",
+		description:
+			"Pactive 主动机制状态：空闲判定与 reason、护栏四闸门、定时任务数、最近活动。只读。",
+		parameters: STATUS_PARAMETERS,
+		async execute() {
+			try {
+				const core = await loadCore();
+				const now = Date.now();
+				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const state = (await readState(core, paths)) ?? core.defaultState();
+				const idle = core.evaluateIdle
+					? core.evaluateIdle(state, now, state.policy ?? {})
+					: { idle: false, reason: "requires-action" };
+				const guard = core.checkGuard ? core.checkGuard(state, now) : { pass: false, reason: "requires-action" };
+				const tasks = core.schedule?.list ? core.schedule.list(state) : (state.tasks ?? []);
+				const activity = core.getActivity ? core.getActivity(state) : null;
+				return textResult(
+					JSON.stringify(
+						{
+							host: HOST_KIND,
+							now,
+							enabled: state.idle?.enabled ?? false,
+							idle,
+							guard,
+							tasks: Array.isArray(tasks) ? tasks.length : 0,
+							activity,
+						},
+						null,
+						2,
+					),
+					{ host: HOST_KIND },
+				);
+			} catch (err) {
+				return textResult(`pactive_status 失败：${errorText(err)}`, { error: true });
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "pactive_schedule",
+		label: "Pactive Schedule",
+		description: "登记一个定时任务（真正落盘）。when 支持时长（10m）、时刻（18:30）、ISO 时间、every 1h。",
+		parameters: SCHEDULE_PARAMETERS,
+		async execute(_toolCallId: string, params: Record<string, any>) {
+			try {
+				const prompt = typeof params?.prompt === "string" ? params.prompt.trim() : "";
+				if (prompt === "") return textResult("pactive_schedule 失败：prompt 必填", { error: true });
+				const now = Date.now();
+				const spec = parseWhen(params?.when, now);
+				if (!spec) {
+					return textResult(`pactive_schedule 失败：无法解析 when（${String(params?.when)}）`, { error: true });
+				}
+				const core = await loadCore();
+				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const next = await mutateState(core, paths, (state) => {
+					const out = core.schedule.add(
+						state,
+						{ ...spec, prompt, content: prompt, owner: state.identity?.agentId },
+						now,
+					);
+					if (out && typeof out === "object" && out.state) return out.state;
+					return out && Array.isArray(out.tasks) ? out : state;
+				});
+				const tasks = core.schedule?.list ? core.schedule.list(next) : (next.tasks ?? []);
+				const created = Array.isArray(tasks) ? tasks[tasks.length - 1] : null;
+				return textResult(
+					JSON.stringify(
+						{
+							ok: true,
+							taskId: created?.id ?? created?.taskId ?? null,
+							dueAt: created?.dueAt ?? spec.at ?? null,
+							kind: spec.kind,
+							when: spec.when,
+							tasks: Array.isArray(tasks) ? tasks.length : 0,
+						},
+						null,
+						2,
+					),
+					{ taskId: created?.id ?? null },
+				);
+			} catch (err) {
+				return textResult(`pactive_schedule 失败：${errorText(err)}`, { error: true });
+			}
+		},
+	});
+
+	pi.registerCommand("pactive", {
+		description: "Pactive：status | tasks | schedule <when> <prompt> | help",
+		async handler(args: string, ctx: PactiveUiContext) {
+			const notify = (message: string, level = "info") => {
+				try {
+					ctx?.ui?.notify?.(message, level);
+				} catch {
+					/* the host may not have a UI in non-interactive modes */
+				}
+				process.stderr.write(`[pactive] ${message}\n`);
+			};
+			const parts = String(args ?? "").trim().split(/\s+/).filter(Boolean);
+			const sub = parts[0] ?? "status";
+			try {
+				const core = await loadCore();
+				const now = Date.now();
+				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const state = (await readState(core, paths)) ?? core.defaultState();
+				if (sub === "status") {
+					const idle = core.evaluateIdle
+						? core.evaluateIdle(state, now, state.policy ?? {})
+						: { idle: false, reason: "requires-action" };
+					const guard = core.checkGuard ? core.checkGuard(state, now) : { pass: false, reason: "requires-action" };
+					const tasks = core.schedule?.list ? core.schedule.list(state) : (state.tasks ?? []);
+					notify(
+						`idle=${idle.idle} reason=${idle.reason} guard=${guard.pass ? "pass" : "blocked"} ` +
+							`(${guard.reason ?? "-"}) tasks=${Array.isArray(tasks) ? tasks.length : 0}`,
+					);
+					return;
+				}
+				if (sub === "tasks") {
+					const tasks = core.schedule?.list ? core.schedule.list(state) : (state.tasks ?? []);
+					const list = Array.isArray(tasks) ? tasks : [];
+					notify(
+						list.length === 0
+							? "没有定时任务"
+							: `pactive: ${list.length} 个定时任务\n` +
+									list.map((task: any) => `- [${task?.id ?? "?"}] ${task?.prompt ?? task?.content ?? ""}`).join("\n"),
+					);
+					return;
+				}
+				if (sub === "schedule") {
+					const when = parts[1] ?? "10m";
+					const prompt = parts.slice(2).join(" ");
+					if (prompt === "") {
+						notify("用法：/pactive schedule <when> <prompt>", "warning");
+						return;
+					}
+					const spec = parseWhen(when, now);
+					if (!spec) {
+						notify(`pactive: 无法解析 when（${when}）`, "warning");
+						return;
+					}
+					const next = await mutateState(core, paths, (current) => {
+						const out = core.schedule.add(
+							current,
+							{ ...spec, prompt, content: prompt, owner: current.identity?.agentId },
+							now,
+						);
+						if (out && typeof out === "object" && out.state) return out.state;
+						return out && Array.isArray(out.tasks) ? out : current;
+					});
+					const tasks = core.schedule?.list ? core.schedule.list(next) : (next.tasks ?? []);
+					const created = Array.isArray(tasks) ? tasks[tasks.length - 1] : null;
+					notify(`pactive: 已登记定时任务 ${created?.id ?? "-"}（${when}）`);
+					return;
+				}
+				notify("用法：/pactive status | tasks | schedule <when> <prompt> | help", "warning");
+			} catch (err) {
+				notify(`pactive 失败：${errorText(err)}`, "error");
+			}
+		},
+	});
+
+	// Session lifecycle → activity + control tracking.
+	pi.on("session_start", () => {
+		void markActivity("session-start");
+	});
+	pi.on("input", () => {
+		void markActivity("user");
+	});
+	pi.on("agent_start", () => {
+		void markActivity("agent");
+	});
+	pi.on("tool_execution_start", () => {
+		void markActivity("tool");
+	});
+	pi.on("message_end", () => {
+		void markActivity("agent");
+	});
+	pi.on("agent_settled", () => {
+		void markControlReturned();
+	});
+	pi.on("session_shutdown", () => {
+		void markControlReturned();
+	});
+}

package/pi/skills/pactive/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pactive
+description: >-
+  Correct usage of the pactive proactive-assistant extension (tools pactive_status / pactive_schedule /
+  pactive_tell / pactive_history and the "/pactive" command family). Use when the task involves checking
+  whether the idle trigger fired or why it did not, scheduling work for later (one-shot or
+  repeating), reading the pactive event ledger, or sending a message to another session on the same
+  machine. Covers the semantics traps (queued is not delivered, idle is disabled by default,
+  human-gated config needs CLI --confirm, the Stop hook blocks at most once per turn) and the
+  "when" syntax (10m / 18:30 / ISO 8601 / every 1h).
+---
+
+# pactive：怎么正确用它
+
+pactive 给会话加**主动机制**：空闲判定（到点才动手）、**定时任务**、**跨会话消息**与**事件账本**。
+
+## 工具与命令
+
+| 入口 | 作用 |
+|---|---|
+| `pactive_status` / `/pactive status` | 空闲判定与 `reason`、护栏四闸门、定时任务数、最近活动（只读） |
+| `pactive_schedule` / `/pactive schedule <when> <prompt>` | 登记一个定时任务（真正落盘，重启后仍在） |
+| `pactive_tell <to> <body>` | 给同机另一个会话投递消息（离线时排队，不伪装成功） |
+| `pactive_history [n]` | 读事件账本尾部：触发 → 投递 → 回应 → 结账 |
+| `/pactive tasks` | 列出待触发的定时任务 |
+
+## 关键语义（别踩）
+
+- **默认不打扰**：`idle.enabled` 默认 `false`。没打开开关，空闲永远不会触发主动行为。
+- **`reason` 是枚举**：`idle | disabled | no-control | busy | threshold | quiet | hourly-limit | min-interval | cooldown | requires-action`。
+  没触发时先看 `reason`，不要猜。
+- **四闸门缺一不可**：控制权已交回 + 不忙 + 超过阈值 + 护栏通过，才可能触发。
+- **`queued` ≠ 已送达**：对端离线时消息进 outbox，等对端上线再补投；回执写 `queued` 就是还没送到。
+- **配置是人工闸门**：`config` 只能由人用 CLI `--confirm` 改；模型/MCP 侧改配置一律得到
+  `need_human_confirmation`，且配置不变。
+- **Stop hook 最多阻断一次**：同一轮里只阻断一次，避免死循环；`UserPromptSubmit` 会重置这个计数。
+
+## `when` 语法
+
+`10m` / `2h` / `30s`（相对时长）、`18:30`（当天时刻，已过则顺延到明天）、
+ISO 8601 时间戳（绝对时刻）、`every 1h`（周期）。缺省 `10m`。
+
+## 排障
+
+- 状态面板里 `reason=disabled` → 开关没开；`reason=busy` → 宿主还在忙；`reason=threshold` → 还没到阈值。
+- 任务登记了但没触发 → 先看 `pactive_history` 里有没有 `triggered` 记录；没有说明调度器没跑到。
+- 消息一直是 `queued` → 对端不在线；看 `pactive_status` 的 peers。

package/skills/pactive/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pactive
+description: >-
+  Correct usage of the pactive proactive-assistant extension (tools pactive_status / pactive_schedule /
+  pactive_tell / pactive_history and the "/pactive" command family). Use when the task involves checking
+  whether the idle trigger fired or why it did not, scheduling work for later (one-shot or
+  repeating), reading the pactive event ledger, or sending a message to another session on the same
+  machine. Covers the semantics traps (queued is not delivered, idle is disabled by default,
+  human-gated config needs CLI --confirm, the Stop hook blocks at most once per turn) and the
+  "when" syntax (10m / 18:30 / ISO 8601 / every 1h).
+---
+
+# pactive：怎么正确用它
+
+pactive 给会话加**主动机制**：空闲判定（到点才动手）、**定时任务**、**跨会话消息**与**事件账本**。
+
+## 工具与命令
+
+| 入口 | 作用 |
+|---|---|
+| `pactive_status` / `/pactive status` | 空闲判定与 `reason`、护栏四闸门、定时任务数、最近活动（只读） |
+| `pactive_schedule` / `/pactive schedule <when> <prompt>` | 登记一个定时任务（真正落盘，重启后仍在） |
+| `pactive_tell <to> <body>` | 给同机另一个会话投递消息（离线时排队，不伪装成功） |
+| `pactive_history [n]` | 读事件账本尾部：触发 → 投递 → 回应 → 结账 |
+| `/pactive tasks` | 列出待触发的定时任务 |
+
+## 关键语义（别踩）
+
+- **默认不打扰**：`idle.enabled` 默认 `false`。没打开开关，空闲永远不会触发主动行为。
+- **`reason` 是枚举**：`idle | disabled | no-control | busy | threshold | quiet | hourly-limit | min-interval | cooldown | requires-action`。
+  没触发时先看 `reason`，不要猜。
+- **四闸门缺一不可**：控制权已交回 + 不忙 + 超过阈值 + 护栏通过，才可能触发。
+- **`queued` ≠ 已送达**：对端离线时消息进 outbox，等对端上线再补投；回执写 `queued` 就是还没送到。
+- **配置是人工闸门**：`config` 只能由人用 CLI `--confirm` 改；模型/MCP 侧改配置一律得到
+  `need_human_confirmation`，且配置不变。
+- **Stop hook 最多阻断一次**：同一轮里只阻断一次，避免死循环；`UserPromptSubmit` 会重置这个计数。
+
+## `when` 语法
+
+`10m` / `2h` / `30s`（相对时长）、`18:30`（当天时刻，已过则顺延到明天）、
+ISO 8601 时间戳（绝对时刻）、`every 1h`（周期）。缺省 `10m`。
+
+## 排障
+
+- 状态面板里 `reason=disabled` → 开关没开；`reason=busy` → 宿主还在忙；`reason=threshold` → 还没到阈值。
+- 任务登记了但没触发 → 先看 `pactive_history` 里有没有 `triggered` 记录；没有说明调度器没跑到。
+- 消息一直是 `queued` → 对端不在线；看 `pactive_status` 的 peers。

package/src/core/activity.mjs

@@ -0,0 +1,67 @@
+export const ACTIVITY_KINDS = ['user', 'agent', 'session-start', 'session-end', 'tool'];
+
+/**
+ * Record activity on the shared timeline. Mutates and returns the state.
+ * Only user and agent activity open a new activity epoch.
+ */
+export function markActivity(state, kind, now = Date.now()) {
+  if (!ACTIVITY_KINDS.includes(kind)) {
+    throw new Error(`unknown activity kind: ${kind}`);
+  }
+  const ts = Number.isFinite(now) ? now : Date.now();
+  switch (kind) {
+    case 'user':
+      state.lastUserActivityAt = ts;
+      state.lastActivityAt = ts;
+      state.epoch += 1;
+      state.controlReturned = false;
+      break;
+    case 'agent':
+      state.lastAgentActivityAt = ts;
+      state.lastActivityAt = ts;
+      state.epoch += 1;
+      state.controlReturned = false;
+      break;
+    case 'tool':
+      state.lastAgentActivityAt = ts;
+      state.lastActivityAt = ts;
+      state.controlReturned = false;
+      break;
+    case 'session-start':
+      state.lastActivityAt = ts;
+      state.controlReturned = false;
+      state.busy = false;
+      break;
+    case 'session-end':
+      state.lastActivityAt = ts;
+      state.controlReturned = false;
+      state.busy = false;
+      break;
+    default:
+      break;
+  }
+  return state;
+}
+
+/** The host gave control back: the agent is idle and may be prompted. */
+export function markControlReturned(state, now = Date.now()) {
+  const ts = Number.isFinite(now) ? now : Date.now();
+  state.controlReturned = true;
+  state.busy = false;
+  state.lastActivityAt = ts;
+  return state;
+}
+
+export function getActivity(state, now = Date.now()) {
+  const ts = Number.isFinite(now) ? now : Date.now();
+  const lastActivityAt = Number.isFinite(state.lastActivityAt) ? state.lastActivityAt : 0;
+  return {
+    lastActivityAt,
+    lastUserActivityAt: Number.isFinite(state.lastUserActivityAt) ? state.lastUserActivityAt : 0,
+    lastAgentActivityAt: Number.isFinite(state.lastAgentActivityAt) ? state.lastAgentActivityAt : 0,
+    epoch: Number.isFinite(state.epoch) ? state.epoch : 0,
+    busy: state.busy === true,
+    controlReturned: state.controlReturned === true,
+    idleForMs: ts - lastActivityAt,
+  };
+}

package/src/core/config.mjs

@@ -0,0 +1,84 @@
+import { pactiveError } from './errors.mjs';
+
+export const CONFIG_SCHEMA = {
+  'idle.enabled': { type: 'boolean', default: false, humanGated: true },
+  'idle.thresholdMs': { type: 'number', default: 900000, humanGated: true, min: 0 },
+  'policy.quietStart': { type: 'string|null', default: null, humanGated: true },
+  'policy.quietEnd': { type: 'string|null', default: null, humanGated: true },
+  'policy.hourlyLimit': { type: 'number', default: 6, humanGated: true, min: 0 },
+  'policy.minIntervalMs': { type: 'number', default: 600000, humanGated: true, min: 0 },
+  'policy.cooldownMs': { type: 'number', default: 1800000, humanGated: true, min: 0 },
+};
+
+export const config = {
+  get(state, key) {
+    const spec = specOf(key);
+    const current = readPath(state, key);
+    return current === undefined ? spec.default : current;
+  },
+
+  describe() {
+    const defaults = {};
+    const humanGatedKeys = [];
+    for (const [key, spec] of Object.entries(CONFIG_SCHEMA)) {
+      defaults[key] = spec.default;
+      if (spec.humanGated) humanGatedKeys.push(key);
+    }
+    return { schema: CONFIG_SCHEMA, defaults, humanGatedKeys };
+  },
+
+  /** Gated keys only change with an explicit confirmation; without one nothing is written. */
+  setHumanGated(state, key, value, options = {}) {
+    const spec = specOf(key);
+    const confirm = options && options.confirm === true;
+    if (spec.humanGated && !confirm) {
+      return { ok: false, key, reason: 'need_human_confirmation' };
+    }
+    if (!validValue(spec, value)) {
+      return { ok: false, key, reason: 'invalid-value' };
+    }
+    writePath(state, key, value);
+    return { ok: true, key, value };
+  },
+};
+
+function specOf(key) {
+  const spec = Object.prototype.hasOwnProperty.call(CONFIG_SCHEMA, key) ? CONFIG_SCHEMA[key] : null;
+  if (!spec) {
+    throw pactiveError('CONFIG_KEY_UNKNOWN', `unknown config key: ${key}`);
+  }
+  return spec;
+}
+
+function validValue(spec, value) {
+  if (value === null) return spec.type === 'string|null';
+  if (spec.type === 'boolean') return typeof value === 'boolean';
+  if (spec.type === 'number') {
+    if (typeof value !== 'number' || !Number.isFinite(value)) return false;
+    if (typeof spec.min === 'number' && value < spec.min) return false;
+    return true;
+  }
+  if (spec.type === 'string|null') return typeof value === 'string';
+  return false;
+}
+
+function readPath(state, key) {
+  const parts = key.split('.');
+  let current = state;
+  for (const part of parts) {
+    if (current === null || typeof current !== 'object') return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+function writePath(state, key, value) {
+  const parts = key.split('.');
+  let current = state;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const part = parts[i];
+    if (!current[part] || typeof current[part] !== 'object') current[part] = {};
+    current = current[part];
+  }
+  current[parts[parts.length - 1]] = value;
+}