@xopcai/xopc 0.0.302 → 0.0.306

package/dist/src/knowledge-memory/repository.js

@@ -5,6 +5,12 @@ import { randomUUID } from "node:crypto";
 //#region src/knowledge-memory/repository.ts
 init_fts();
 init_transaction();
+var KnowledgeReviewConflictError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "KnowledgeReviewConflictError";
+	}
+};
 function fromRow(row) {
 	return {
 		id: row.knowledge_id,
@@ -37,6 +43,14 @@ function fromRow(row) {
 function bounded(value, field) {
 	if (!Number.isFinite(value) || value < 0 || value > 1) throw new Error(`${field} must be between 0 and 1.`);
 }
+function statusActorForOrigin(origin) {
+	return origin === "owner" ? "user" : origin === "agent" ? "agent" : "runtime";
+}
+function insertStatusEvent(db, input) {
+	db.prepare(`INSERT INTO knowledge_item_status_events (
+    event_id, knowledge_id, from_status, to_status, actor_type, reason, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(randomUUID(), input.knowledgeId, input.fromStatus, input.toStatus, input.actor, input.reason, input.now);
+}
 function writeKnowledgeItem(input) {
 	validateScope(input.scope);
 	bounded(input.confidence, "confidence");
@@ -67,25 +81,43 @@ function writeKnowledgeItem(input) {
 			created: false
 		};
 		if (existing) {
+			const nextStatus = input.status ?? (input.originClass === "owner" ? "active" : "candidate");
 			db.prepare(`UPDATE knowledge_items SET kind = ?, content = ?, record_class = ?, status = ?, confidence = ?,
         importance = ?, valid_from = ?, valid_to = ?, expires_at = ?, review_at = ?,
         origin_class = ?, source_agent_id = ?, source_conversation_id = ?, source_turn_id = ?,
-        derived_from_recalled_context = ?, source_json = ?, updated_at = ? WHERE knowledge_id = ?`).run(input.kind, input.content.trim(), input.recordClass ?? "memory", input.status ?? (input.originClass === "owner" ? "active" : "candidate"), input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceConversationId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, existing.knowledge_id);
+        derived_from_recalled_context = ?, source_json = ?, updated_at = ? WHERE knowledge_id = ?`).run(input.kind, input.content.trim(), input.recordClass ?? "memory", nextStatus, input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceConversationId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, existing.knowledge_id);
 			db.prepare("DELETE FROM knowledge_items_fts WHERE knowledge_id = ?").run(existing.knowledge_id);
 			db.prepare("INSERT INTO knowledge_items_fts(content, knowledge_id) VALUES (?, ?)").run(input.content.trim(), existing.knowledge_id);
+			if (existing.status !== nextStatus) insertStatusEvent(db, {
+				knowledgeId: existing.knowledge_id,
+				fromStatus: existing.status,
+				toStatus: nextStatus,
+				actor: statusActorForOrigin(input.originClass),
+				reason: "Knowledge replaced from its source.",
+				now
+			});
 			return {
 				item: fromRow(db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(existing.knowledge_id)),
 				created: false
 			};
 		}
 		const id = randomUUID();
+		const status = input.status ?? (input.originClass === "owner" ? "active" : "candidate");
 		db.prepare(`INSERT INTO knowledge_items (
       knowledge_id, principal_id, kind, scope_type, scope_id, content, canonical_key, record_class,
       status, confidence, importance, valid_from, valid_to, expires_at, review_at,
       origin_class, source_agent_id, source_conversation_id, source_turn_id,
       derived_from_recalled_context, source_json, created_at, updated_at
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, principalId, input.kind, input.scope.type, input.scope.id ?? null, input.content.trim(), input.canonicalKey.trim(), input.recordClass ?? "memory", input.status ?? (input.originClass === "owner" ? "active" : "candidate"), input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceConversationId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, now);
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, principalId, input.kind, input.scope.type, input.scope.id ?? null, input.content.trim(), input.canonicalKey.trim(), input.recordClass ?? "memory", status, input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceConversationId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, now);
 		db.prepare("INSERT INTO knowledge_items_fts(content, knowledge_id) VALUES (?, ?)").run(input.content.trim(), id);
+		insertStatusEvent(db, {
+			knowledgeId: id,
+			fromStatus: null,
+			toStatus: status,
+			actor: statusActorForOrigin(input.originClass),
+			reason: "Knowledge admitted.",
+			now
+		});
 		return {
 			item: fromRow(db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(id)),
 			created: true
@@ -112,46 +144,146 @@ function listKnowledgeItems(input = {}) {
       ${input.canonicalKey ? "AND canonical_key = ?" : ""}
     ORDER BY importance DESC, updated_at DESC LIMIT ?`).all(input.principalId ?? "local-owner", ...statuses, ...input.recordClass ? [input.recordClass] : [], ...input.scope ? [input.scope.type, input.scope.id ?? null] : [], ...input.canonicalKey ? [input.canonicalKey] : [], Math.max(1, Math.min(2e3, input.limit ?? 200))).map(fromRow);
 }
-function setKnowledgeStatus(id, status, now = Date.now()) {
-	return getSqliteDatabase().prepare(`UPDATE knowledge_items SET status = ?, updated_at = ?
-    WHERE knowledge_id = ?`).run(status, now, id).changes ? getKnowledgeItem(id) : void 0;
+function transitionKnowledgeStatus(input) {
+	const reason = input.reason.trim();
+	if (!reason) throw new Error("A knowledge status change reason is required.");
+	const content = input.content?.trim();
+	if (input.content !== void 0 && !content) throw new Error("Knowledge content is required.");
+	const now = input.now ?? Date.now();
+	return runSqliteWriteTransaction((db) => {
+		const current = db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(input.id);
+		if (!current) return void 0;
+		if (input.expectedStatus && current.status !== input.expectedStatus) throw new KnowledgeReviewConflictError(`Knowledge status changed from ${input.expectedStatus} to ${current.status}.`);
+		db.prepare(`UPDATE knowledge_items SET status = ?, content = COALESCE(?, content), updated_at = ?
+      WHERE knowledge_id = ?`).run(input.status, content ?? null, now, input.id);
+		if (content !== void 0) {
+			db.prepare("DELETE FROM knowledge_items_fts WHERE knowledge_id = ?").run(input.id);
+			db.prepare("INSERT INTO knowledge_items_fts(content, knowledge_id) VALUES (?, ?)").run(content, input.id);
+		}
+		insertStatusEvent(db, {
+			knowledgeId: input.id,
+			fromStatus: current.status,
+			toStatus: input.status,
+			actor: input.actor,
+			reason,
+			now
+		});
+		return fromRow(db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(input.id));
+	});
 }
-function visibilityClause(context) {
-	const parts = [
-		"k.scope_type = 'global'",
-		"(k.scope_type = 'agent' AND k.scope_id = ?)",
-		"(k.scope_type = 'workspace' AND k.scope_id = ?)",
-		"(k.scope_type = 'session' AND k.scope_id = ?)"
-	];
-	const values = [
-		context.agentId ?? "",
-		context.workspaceId ?? "",
-		context.conversationId ?? ""
-	];
-	if (context.projectId) {
+const REVIEW_TRANSITIONS = {
+	approve: {
+		from: [
+			"candidate",
+			"needs_review",
+			"stale"
+		],
+		to: "active"
+	},
+	edit_and_approve: {
+		from: [
+			"candidate",
+			"needs_review",
+			"stale"
+		],
+		to: "active",
+		requiresContent: true
+	},
+	reject: {
+		from: [
+			"candidate",
+			"needs_review",
+			"stale"
+		],
+		to: "rejected"
+	},
+	archive: {
+		from: [
+			"candidate",
+			"needs_review",
+			"stale",
+			"active"
+		],
+		to: "archived"
+	}
+};
+function reviewKnowledgeItem(input) {
+	const current = getKnowledgeItem(input.id);
+	if (!current) return void 0;
+	const transition = REVIEW_TRANSITIONS[input.action];
+	if (!transition.from.includes(current.status)) throw new KnowledgeReviewConflictError(`Cannot ${input.action} knowledge with status ${current.status}.`);
+	if (transition.requiresContent && !input.content?.trim()) throw new Error("Edited knowledge content is required.");
+	return transitionKnowledgeStatus({
+		id: input.id,
+		status: transition.to,
+		actor: input.actor,
+		reason: input.reason,
+		expectedStatus: input.expectedStatus ?? current.status,
+		...input.content === void 0 ? {} : { content: input.content },
+		...input.now === void 0 ? {} : { now: input.now }
+	});
+}
+function listKnowledgeStatusEvents(knowledgeId) {
+	return getSqliteDatabase().prepare(`SELECT event_id, knowledge_id, from_status, to_status,
+    actor_type, reason, created_at FROM knowledge_item_status_events
+    WHERE knowledge_id = ? ORDER BY created_at ASC, event_id ASC`).all(knowledgeId).map((row) => ({
+		id: row.event_id,
+		knowledgeId: row.knowledge_id,
+		...row.from_status === null ? {} : { fromStatus: row.from_status },
+		toStatus: row.to_status,
+		actor: row.actor_type,
+		reason: row.reason,
+		createdAt: row.created_at
+	}));
+}
+function visibilityClause(context, policy) {
+	const allowed = new Set(policy?.scopes ?? [
+		"global",
+		"agent",
+		"workspace",
+		"project",
+		"session"
+	]);
+	const parts = [];
+	const values = [];
+	if (allowed.has("global")) parts.push("k.scope_type = 'global'");
+	if (allowed.has("agent")) {
+		parts.push("(k.scope_type = 'agent' AND k.scope_id = ?)");
+		values.push(context.agentId ?? "");
+	}
+	if (allowed.has("workspace")) {
+		parts.push("(k.scope_type = 'workspace' AND k.scope_id = ?)");
+		values.push(context.workspaceId ?? "");
+	}
+	if (allowed.has("session")) {
+		parts.push("(k.scope_type = 'session' AND k.scope_id = ?)");
+		values.push(context.conversationId ?? "");
+	}
+	if (allowed.has("project") && context.projectId) {
 		parts.push("(k.scope_type = 'project' AND k.scope_id = ?)");
 		values.push(context.projectId);
 	}
 	return {
-		sql: `(${parts.join(" OR ")})`,
+		sql: `(${parts.length ? parts.join(" OR ") : "0"})`,
 		values
 	};
 }
+function contentSourceClause(policy) {
+	if (!policy) return "1";
+	const allowed = new Set(policy.contentSources);
+	const importedSource = "COALESCE(json_extract(k.source_json, '$.kind'), '') = 'product_import'";
+	const parts = [];
+	if (allowed.has("memory")) parts.push("k.record_class = 'memory'");
+	if (allowed.has("local_import")) parts.push(`(k.record_class = 'source_index' AND ${importedSource})`);
+	if (allowed.has("connector")) parts.push(`(k.record_class = 'source_index' AND NOT (${importedSource}))`);
+	return `(${parts.length ? parts.join(" OR ") : "0"})`;
+}
 function searchKnowledgeItems(input) {
 	const principalId = input.principalId ?? "local-owner";
 	const asOf = input.asOf ?? Date.now();
 	const limit = Math.max(1, Math.min(100, input.limit ?? 12));
-	const visible = visibilityClause(input.context);
-	const sourceParts = [];
-	const sourceValues = [];
-	const importedSource = "COALESCE(json_extract(k.source_json, '$.kind'), '') = 'product_import'";
-	if (input.sources?.includes("connector")) sourceParts.push(`(k.record_class = 'source_index' AND NOT (${importedSource}))`);
-	if (input.sources?.includes("workspace")) sourceParts.push(`(k.record_class = 'source_index' AND ${importedSource})`);
-	const memoryScopes = input.sources?.filter((source) => source !== "connector") ?? [];
-	if (memoryScopes.length) {
-		sourceParts.push(`(k.record_class = 'memory' AND k.scope_type IN (${memoryScopes.map(() => "?").join(", ")}))`);
-		sourceValues.push(...memoryScopes);
-	}
+	const visible = visibilityClause(input.context, input.policy);
+	const contentSource = contentSourceClause(input.policy);
 	const fts = buildFts5SearchQuery(input.query);
 	if (!fts) return [];
 	return getSqliteDatabase().prepare(`SELECT k.*, bm25(knowledge_items_fts) AS rank
@@ -162,13 +294,16 @@ function searchKnowledgeItems(input) {
       AND (k.expires_at IS NULL OR k.expires_at >= ?)
       ${input.recordClass ? "AND k.record_class = ?" : ""}
       ${input.trustedOnly ? "AND k.origin_class != 'untrusted'" : ""}
-      ${input.sources ? `AND (${sourceParts.length ? sourceParts.join(" OR ") : "0"})` : ""}
+      AND ${contentSource}
       AND ${visible.sql}
-    ORDER BY rank ASC, k.importance DESC, k.updated_at DESC LIMIT ?`).all(fts, principalId, asOf, asOf, asOf, ...input.recordClass ? [input.recordClass] : [], ...sourceValues, ...visible.values, limit).map(fromRow);
+    ORDER BY rank ASC, k.importance DESC, k.updated_at DESC LIMIT ?`).all(fts, principalId, asOf, asOf, asOf, ...input.recordClass ? [input.recordClass] : [], ...visible.values, limit).map(fromRow);
+}
+function classifyKnowledgeContentSource(item) {
+	if (item.recordClass === "memory") return "memory";
+	return item.source.kind === "product_import" ? "local_import" : "connector";
 }
-function knowledgeSourceAllowed(item, sources) {
-	if (item.recordClass === "source_index") return sources.includes(item.source.kind === "product_import" ? "workspace" : "connector");
-	return item.scope.type === "session" ? sources.includes("session") : item.scope.type === "workspace" ? sources.includes("workspace") : item.scope.type === "project" ? sources.includes("project") : false;
+function knowledgeItemAllowed(item, policy) {
+	return policy.scopes.includes(item.scope.type) && policy.contentSources.includes(classifyKnowledgeContentSource(item));
 }
 //#endregion
-export { getKnowledgeItem, knowledgeSourceAllowed, listKnowledgeItems, searchKnowledgeItems, setKnowledgeStatus, writeKnowledgeItem };
+export { KnowledgeReviewConflictError, classifyKnowledgeContentSource, getKnowledgeItem, knowledgeItemAllowed, listKnowledgeItems, listKnowledgeStatusEvents, reviewKnowledgeItem, searchKnowledgeItems, transitionKnowledgeStatus, writeKnowledgeItem };

package/dist/src/mcp/channel-bridge.js

@@ -62,10 +62,14 @@ var XopcChannelBridge = class {
 			issueTicket: async () => {
 				const response = await this.client.postJson("/api/realtime/tickets", {
 					clientId: this.realtimeClientId,
-					clientKind: "mcp"
+					clientKind: "mcp",
+					protocolVersion: 2
 				});
-				if (!response.payload?.ticket) throw new Error(response.error?.message ?? "Realtime ticket response is invalid");
-				return response.payload.ticket;
+				if (!response.payload?.ticket || !response.payload.realtime) throw new Error(response.error?.message ?? "Realtime ticket response is invalid");
+				return {
+					ticket: response.payload.ticket,
+					realtime: response.payload.realtime
+				};
 			},
 			createWebSocket: (url) => new WebSocket(url),
 			onEvent: (event) => this.handleRealtimeEvent(event),

package/dist/src/media-understanding/registry.js

@@ -14,6 +14,7 @@ function indexProvider(provider) {
 }
 function registerMediaUnderstandingProvider(provider) {
 	const keys = indexProvider(provider);
+	const previous = new Map(keys.map((key) => [key, registry.get(key)]));
 	const conflicts = keys.filter((key) => registry.has(key));
 	if (conflicts.length > 0) log.warn({
 		providerId: provider.id,
@@ -21,7 +22,11 @@ function registerMediaUnderstandingProvider(provider) {
 	}, `Media-understanding provider "${provider.id}" overrides existing registration(s): ${conflicts.join(", ")}`);
 	for (const key of keys) registry.set(key, provider);
 	return () => {
-		for (const key of keys) if (registry.get(key) === provider) registry.delete(key);
+		for (const key of keys) if (registry.get(key) === provider) {
+			const prior = previous.get(key);
+			if (prior) registry.set(key, prior);
+			else registry.delete(key);
+		}
 	};
 }
 function getMediaUnderstandingProvider(id) {

package/dist/src/migrations/knowledge-memory-read-policy-config.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from './types.js';
+export declare const knowledgeMemoryReadPolicyConfigMigration: Migration;

package/dist/src/migrations/knowledge-memory-read-policy-config.js

@@ -0,0 +1,48 @@
+import { init_config, normalizeKnowledgeMemoryConfigInput } from "../user-context/config.js";
+import { init_lock, isGatewayConfigLockedByAnotherProcessSync } from "../gateway/lock.js";
+import { existsSync, readFileSync } from "node:fs";
+//#region src/migrations/knowledge-memory-read-policy-config.ts
+init_lock();
+init_config();
+const id = "knowledge-memory-read-policy-config";
+function convertedConfig(ctx) {
+	if (!existsSync(ctx.configPath)) return null;
+	const config = JSON.parse(readFileSync(ctx.configPath, "utf8"));
+	const userContext = config.userContext;
+	if (!userContext || typeof userContext !== "object" || Array.isArray(userContext)) return null;
+	const knowledgeMemory = userContext.knowledgeMemory;
+	if (!knowledgeMemory || typeof knowledgeMemory !== "object" || Array.isArray(knowledgeMemory)) return null;
+	const memory = knowledgeMemory;
+	if (!Array.isArray(memory.sources)) return null;
+	userContext.knowledgeMemory = normalizeKnowledgeMemoryConfigInput(memory);
+	return config;
+}
+function item(status) {
+	return {
+		id,
+		title: "Knowledge memory read policy configuration",
+		kind: "config",
+		safety: "auto",
+		status,
+		message: "Split knowledge memory visibility scopes from content sources."
+	};
+}
+const knowledgeMemoryReadPolicyConfigMigration = {
+	id,
+	kind: "config",
+	safety: "auto",
+	detect: (ctx) => convertedConfig(ctx) ? item("planned") : null,
+	apply: (ctx) => {
+		if (isGatewayConfigLockedByAnotherProcessSync(ctx.configPath)) return {
+			...item("skipped"),
+			message: "Deferred knowledge memory config migration until the running gateway restarts."
+		};
+		const config = convertedConfig(ctx);
+		return config ? {
+			...item("applied"),
+			details: { config }
+		} : item("not_needed");
+	}
+};
+//#endregion
+export { knowledgeMemoryReadPolicyConfigMigration };

package/dist/src/migrations/runner.js

@@ -3,6 +3,7 @@ import { init_logger } from "../utils/logger.js";
 import { ConfigSchema, init_schema } from "../config/schema.js";
 import { listRegisteredMigrations } from "./registry.js";
 import { conversationRoutingConfigMigration } from "./conversation-routing-config.js";
+import { knowledgeMemoryReadPolicyConfigMigration } from "./knowledge-memory-read-policy-config.js";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 //#region src/migrations/runner.ts
@@ -11,7 +12,7 @@ init_logger();
 const log = createLogger("Migrations");
 const MIGRATION_LEDGER_FILENAME = "migrations.json";
 const CONFIG_BACKUP_COUNT = 10;
-const CORE_MIGRATIONS = [conversationRoutingConfigMigration];
+const CORE_MIGRATIONS = [conversationRoutingConfigMigration, knowledgeMemoryReadPolicyConfigMigration];
 function listAllMigrations() {
 	return [...CORE_MIGRATIONS, ...listRegisteredMigrations().map((entry) => entry.migration)];
 }

package/dist/src/process/bounded-output.d.ts

@@ -0,0 +1,10 @@
+export interface BoundedOutput {
+    readonly text: string;
+    readonly totalBytes: number;
+    readonly truncated: boolean;
+}
+/** Keeps the newest bytes so failures retain their most useful tail output. */
+export declare function createBoundedOutput(maxBytes: number): {
+    append(chunk: Buffer | string): void;
+    snapshot(): BoundedOutput;
+};

package/dist/src/process/bounded-output.js

@@ -0,0 +1,41 @@
+//#region src/process/bounded-output.ts
+/** Keeps the newest bytes so failures retain their most useful tail output. */
+function createBoundedOutput(maxBytes) {
+	const limit = Math.max(0, Math.floor(maxBytes));
+	let chunks = [];
+	let capturedBytes = 0;
+	let totalBytes = 0;
+	return {
+		append(chunk) {
+			const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			totalBytes += value.byteLength;
+			if (limit === 0) {
+				chunks = [];
+				capturedBytes = 0;
+				return;
+			}
+			chunks.push(value);
+			capturedBytes += value.byteLength;
+			while (capturedBytes > limit && chunks.length > 0) {
+				const excess = capturedBytes - limit;
+				const first = chunks[0];
+				if (first.byteLength <= excess) {
+					chunks.shift();
+					capturedBytes -= first.byteLength;
+				} else {
+					chunks[0] = first.subarray(excess);
+					capturedBytes -= excess;
+				}
+			}
+		},
+		snapshot() {
+			return {
+				text: Buffer.concat(chunks, capturedBytes).toString("utf8"),
+				totalBytes,
+				truncated: totalBytes > capturedBytes
+			};
+		}
+	};
+}
+//#endregion
+export { createBoundedOutput };

package/dist/src/process/kill-tree.d.ts

@@ -1,18 +1,7 @@
-/**
- * Best-effort process-tree termination with graceful shutdown.
- * - Windows: use taskkill /T to include descendants. Sends SIGTERM-equivalent
- *   first (without /F), then force-kills if process survives.
- * - Unix: send SIGTERM to process group first, wait grace period, then SIGKILL.
- *
- * This gives child processes a chance to clean up (close connections, remove
- * temp files, terminate their own children) before being hard-killed.
- *
- * When the child was spawned with `detached: false` (e.g. service-managed
- * runtime under launchd/systemd), pass `detached: false` to skip the Unix
- * `process.kill(-pid, ...)` group-kill — it would otherwise target the
- * gateway's own process group and SIGTERM the gateway itself. (#71662)
- */
-export declare function killProcessTree(pid: number, opts?: {
-    graceMs?: number;
+import { type ChildProcess } from 'node:child_process';
+/** Terminates a child and optionally its process tree, escalating after a grace period. */
+export declare function terminateProcess(child: ChildProcess, options?: {
+    tree?: boolean;
     detached?: boolean;
-}): void;
+    graceMs?: number;
+}): Promise<boolean>;

package/dist/src/process/kill-tree.js

@@ -1,35 +1,7 @@
 import { spawn } from "node:child_process";
 //#region src/process/kill-tree.ts
 const DEFAULT_GRACE_MS = 3e3;
-const MAX_GRACE_MS = 6e4;
-/**
-* Best-effort process-tree termination with graceful shutdown.
-* - Windows: use taskkill /T to include descendants. Sends SIGTERM-equivalent
-*   first (without /F), then force-kills if process survives.
-* - Unix: send SIGTERM to process group first, wait grace period, then SIGKILL.
-*
-* This gives child processes a chance to clean up (close connections, remove
-* temp files, terminate their own children) before being hard-killed.
-*
-* When the child was spawned with `detached: false` (e.g. service-managed
-* runtime under launchd/systemd), pass `detached: false` to skip the Unix
-* `process.kill(-pid, ...)` group-kill — it would otherwise target the
-* gateway's own process group and SIGTERM the gateway itself. (#71662)
-*/
-function killProcessTree(pid, opts) {
-	if (!Number.isFinite(pid) || pid <= 0) return;
-	const graceMs = normalizeGraceMs(opts?.graceMs);
-	if (process.platform === "win32") {
-		killProcessTreeWindows(pid, graceMs);
-		return;
-	}
-	killProcessTreeUnix(pid, graceMs, opts?.detached !== false);
-}
-function normalizeGraceMs(value) {
-	if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_GRACE_MS;
-	return Math.max(0, Math.min(MAX_GRACE_MS, Math.floor(value)));
-}
-function isProcessAlive(pid) {
+function processAlive(pid) {
 	try {
 		process.kill(pid, 0);
 		return true;
@@ -37,56 +9,52 @@ function isProcessAlive(pid) {
 		return false;
 	}
 }
-function killProcessTreeUnix(pid, graceMs, useGroupKill) {
-	if (useGroupKill) try {
-		process.kill(-pid, "SIGTERM");
-	} catch {
-		try {
-			process.kill(pid, "SIGTERM");
-		} catch {
-			return;
-		}
-	}
-	else try {
-		process.kill(pid, "SIGTERM");
-	} catch {
-		return;
-	}
-	setTimeout(() => {
-		if (useGroupKill && isProcessAlive(-pid)) try {
-			process.kill(-pid, "SIGKILL");
-			return;
-		} catch {}
-		if (!isProcessAlive(pid)) return;
-		try {
-			process.kill(pid, "SIGKILL");
-		} catch {}
-	}, graceMs).unref();
+function delay(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms).unref();
+	});
 }
-function runTaskkill(args) {
-	try {
-		spawn("taskkill", args, {
+function taskkill(pid, force) {
+	return new Promise((resolve) => {
+		const child = spawn("taskkill", [
+			...force ? ["/F"] : [],
+			"/T",
+			"/PID",
+			String(pid)
+		], {
 			stdio: "ignore",
-			detached: true,
 			windowsHide: true
 		});
-	} catch {}
+		child.once("error", () => resolve());
+		child.once("close", () => resolve());
+	});
 }
-function killProcessTreeWindows(pid, graceMs) {
-	runTaskkill([
-		"/T",
-		"/PID",
-		String(pid)
-	]);
-	setTimeout(() => {
-		if (!isProcessAlive(pid)) return;
-		runTaskkill([
-			"/F",
-			"/T",
-			"/PID",
-			String(pid)
-		]);
-	}, graceMs).unref();
+/** Terminates a child and optionally its process tree, escalating after a grace period. */
+async function terminateProcess(child, options = {}) {
+	const pid = child.pid;
+	if (!pid || child.exitCode !== null || child.signalCode !== null) return true;
+	const graceMs = Math.max(0, Math.min(6e4, Math.floor(options.graceMs ?? DEFAULT_GRACE_MS)));
+	if (process.platform === "win32" && options.tree) {
+		await taskkill(pid, false);
+		if (graceMs > 0 && processAlive(pid)) await delay(graceMs);
+		if (processAlive(pid)) await taskkill(pid, true);
+		return !processAlive(pid);
+	}
+	const target = options.tree && options.detached ? -pid : pid;
+	try {
+		process.kill(target, "SIGTERM");
+	} catch {
+		return true;
+	}
+	if (graceMs > 0 && processAlive(pid)) await delay(graceMs);
+	if (processAlive(pid)) try {
+		process.kill(target, "SIGKILL");
+	} catch {
+		try {
+			child.kill("SIGKILL");
+		} catch {}
+	}
+	return !processAlive(pid);
 }
 //#endregion
-export { killProcessTree };
+export { terminateProcess };

package/dist/src/process/process-spec.d.ts

@@ -0,0 +1,39 @@
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+export interface ProcessSpec {
+    program: string;
+    args?: readonly string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    input?: string | Buffer;
+    keepStdinOpen?: boolean;
+    timeoutMs?: number | null;
+    maxOutputBytes?: number;
+    signal?: AbortSignal;
+    detached?: boolean;
+    windowsHide?: boolean;
+    shell?: SpawnOptions['shell'];
+    terminationPolicy?: 'root' | 'tree';
+    onOutput?: (stream: 'stdout' | 'stderr', chunk: Buffer) => void;
+}
+export interface ProcessResult {
+    exitCode: number | null;
+    spawnErrorCode?: string;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    aborted: boolean;
+    outputTruncated: boolean;
+    terminationVerified: boolean;
+}
+export interface ProcessHandle {
+    readonly child: ChildProcess;
+    readonly completion: Promise<ProcessResult>;
+    terminate(reason?: 'cancelled' | 'timed_out'): void;
+}
+export declare class ProcessExitError extends Error {
+    readonly spec: ProcessSpec;
+    readonly result: ProcessResult;
+    readonly code: number | string | null;
+    constructor(spec: ProcessSpec, result: ProcessResult);
+}

package/dist/src/process/process-spec.js

@@ -0,0 +1,13 @@
+//#region src/process/process-spec.ts
+var ProcessExitError = class extends Error {
+	code;
+	constructor(spec, result) {
+		super(result.stderr.trim() || `Process exited with code ${String(result.exitCode)}`);
+		this.spec = spec;
+		this.result = result;
+		this.name = "ProcessExitError";
+		this.code = result.spawnErrorCode ?? result.exitCode;
+	}
+};
+//#endregion
+export { ProcessExitError };

package/dist/src/process/run-process.d.ts

@@ -0,0 +1,4 @@
+import { type ProcessHandle, type ProcessResult, type ProcessSpec } from './process-spec.js';
+export declare function spawnProcess(spec: ProcessSpec): ProcessHandle;
+export declare function runProcess(spec: ProcessSpec): Promise<ProcessResult>;
+export declare function runProcessChecked(spec: ProcessSpec): Promise<ProcessResult>;