negotium 0.1.37 → 0.1.39

package/dist/types/packages/core/src/agents/topic-cleanup.d.ts

@@ -11,8 +11,12 @@
  * Permanent forensic preservation lives in `wiki/archive/` via
  * `archiveSessionLogs`; this module is the matching teardown side.
  */
-import { type ConversationEntry } from "../storage/conversations";
-import type { AgentKind } from "../types";
+import type { AgentKind, UnifiedEvent } from "../types";
+export interface TopicConversationEntry {
+    ts: string;
+    agent: AgentKind;
+    event: UnifiedEvent;
+}
 export interface PurgeSessionRef {
     agent: AgentKind;
     sessionId: string;
@@ -37,10 +41,21 @@ export interface PurgeTopicLogsOptions {
      */
     extraSessions?: PurgeSessionRef[];
 }
-/** Remove every provider rollout currently manifested by a topic log. */
-export declare function cleanupTopicRollouts(opts: PurgeTopicLogsOptions): Promise<boolean>;
-/** Remove rollout ids captured from a point-in-time conversation manifest. */
-export declare function cleanupTopicRolloutsFromEntries(opts: PurgeTopicLogsOptions, entries: ConversationEntry[]): Promise<boolean>;
+export interface TopicLogMaintenanceHost {
+    readonly agents: readonly AgentKind[];
+    readonly readActiveConversation: (userId: number | string, topicName: string) => TopicConversationEntry[];
+    readonly readRawConversation: (userId: number | string, topicName: string) => TopicConversationEntry[];
+    readonly activeConversationPath: (userId: number | string, topicName: string) => string;
+    readonly rawConversationPath: (userId: number | string, topicName: string) => string;
+    readonly cleanupRollouts: (agent: AgentKind, cwd: string, sessionIds: string[]) => Promise<void>;
+    readonly warn: (context: Record<string, unknown>, message: string) => void;
+}
+export interface TopicLogMaintenance {
+    cleanupTopicRollouts(opts: PurgeTopicLogsOptions): Promise<boolean>;
+    cleanupTopicRolloutsFromEntries(opts: PurgeTopicLogsOptions, entries: TopicConversationEntry[]): Promise<boolean>;
+    rotateTopicLogs(opts: RotateTopicLogsOptions): Promise<RotateTopicLogsResult>;
+    purgeTopicLogs(opts: PurgeTopicLogsOptions): Promise<boolean>;
+}
 export interface RotateTopicLogsOptions extends PurgeTopicLogsOptions {
     /** Number of complete user turns carried into the replacement session. */
     retainTurns: number;
@@ -51,27 +66,18 @@ export interface RotateTopicLogsResult {
     retainedTurns: number;
     retainedEntries: number;
 }
+export declare function createTopicLogMaintenance(host: TopicLogMaintenanceHost): TopicLogMaintenance;
+/** Remove every provider rollout currently manifested by a topic log. */
+export declare const cleanupTopicRollouts: (opts: PurgeTopicLogsOptions) => Promise<boolean>;
+/** Remove rollout ids captured from a point-in-time conversation manifest. */
+export declare const cleanupTopicRolloutsFromEntries: (opts: PurgeTopicLogsOptions, entries: TopicConversationEntry[]) => Promise<boolean>;
 /**
  * Replace a topic's native provider sessions while retaining a bounded tail
- * of its provider-neutral conversation log. This is used by long-lived Cron
- * topics: a fresh native rollout keeps prompt/session state bounded, and the
- * retained tail gives the next rollout enough context to continue naturally.
+ * of its provider-neutral conversation log.
  */
-export declare function rotateTopicLogs(opts: RotateTopicLogsOptions): Promise<RotateTopicLogsResult>;
+export declare const rotateTopicLogs: (opts: RotateTopicLogsOptions) => Promise<RotateTopicLogsResult>;
 /**
  * Best-effort teardown of every artifact associated with a topic's
- * conversation lifecycle. Order matters and is intentional:
- *
- *   1. Read the unified log first — it's the authoritative manifest of
- *      every SDK session id the topic has emitted. Merge any DB session id
- *      passed via `extraSessions` for synthetic rollouts not yet emitted.
- *   2. Dispatch per-agent rollout cleanup in parallel (independent
- *      filesystems, no shared state).
- *   3. Unlink the unified log LAST so a partial rollout-cleanup failure
- *      leaves the manifest in place for a future retry.
- *
- * Errors at every step are logged and reported through the return value.
- * Callers must not commit a reset/delete state transition when this returns
- * false, because the retained manifest can otherwise resurrect old context.
+ * conversation lifecycle.
  */
-export declare function purgeTopicLogs(opts: PurgeTopicLogsOptions): Promise<boolean>;
+export declare const purgeTopicLogs: (opts: PurgeTopicLogsOptions) => Promise<boolean>;

package/dist/types/packages/core/src/mcp/factories/index.d.ts

@@ -1,4 +1,5 @@
 export { parseSessionCommContext, type SessionCommContext, type SessionCommContextDefaults, } from "../session-comm/context";
+export { createSessionTargetCatalog, type SessionTarget, type SessionTargetCatalog, type SessionTargetCatalogHost, type SessionTopicEntry, type SessionTopicRow, type ValidateSessionTargetResult, } from "../session-comm/topic-catalog";
 export { executeVaultHttpRequest } from "../vault-http";
 export { executeVaultRun } from "../vault-run";
 export { createWikiMcpServer, type WikiMcpContext, type WikiMcpHost, type WikiSurface, type WikiTopicBrief, } from "../wiki-server";

package/dist/types/packages/core/src/mcp/session-comm/topic-catalog.d.ts

@@ -0,0 +1,46 @@
+export interface SessionTopicRow {
+    id: string;
+    title: string;
+    kind: string | null;
+    agent: string | null;
+    sessionId: string | null;
+    description: string | null;
+}
+export interface SessionTopicEntry<TAgent extends string = string> {
+    sessionId: string;
+    messageThreadId: number;
+    name: string;
+    kind: "agent" | "channel";
+    description?: string;
+    topicId?: string;
+    agent?: TAgent;
+}
+export interface SessionTarget<TAgent extends string = string> {
+    key: string;
+    topic: SessionTopicEntry<TAgent>;
+}
+export type ValidateSessionTargetResult<TAgent extends string = string> = {
+    ok: true;
+    target: SessionTopicEntry<TAgent>;
+} | {
+    ok: false;
+    error: {
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        isError: true;
+    };
+};
+export interface SessionTargetCatalogHost<TAgent extends string = string> {
+    readonly listRows: () => SessionTopicRow[];
+    readonly currentTopicId?: string;
+    readonly currentTopicName?: string;
+    readonly isAgent: (value: string | null) => value is TAgent;
+}
+export interface SessionTargetCatalog<TAgent extends string = string> {
+    listTargets(): SessionTarget<TAgent>[];
+    getTopics(): Record<string, SessionTopicEntry<TAgent>>;
+    validateTarget(to: string): ValidateSessionTargetResult<TAgent>;
+}
+export declare function createSessionTargetCatalog<TAgent extends string = string>(host: SessionTargetCatalogHost<TAgent>): SessionTargetCatalog<TAgent>;

package/dist/types/packages/core/src/platform/mcp-config.d.ts

@@ -1,4 +1,5 @@
 import { type RuntimeMcpScope } from "./mcp-catalog-policy";
+import { browserOwnerCapability } from "./playwright/capability";
 import type { AgentKind, AgentQueryOptions, PeerRuntimeBridgeContext } from "../types";
 export type { RuntimeMcpScope } from "./mcp-catalog-policy";
 /**
@@ -100,7 +101,7 @@ export interface RuntimeMcpCatalogEntry {
     build(ctx: RuntimeMcpBuildContext): Record<string, unknown> | null;
 }
 export declare const CODEX_BROWSER_CAPABILITY_ENV = "NEGOTIUM_BROWSER_CAPABILITY";
-export declare function browserOwnerCapability(capability: string, owner: string): string;
+export { browserOwnerCapability };
 export declare function browserOwnerForContext(ctx: {
     userId?: string;
     session?: string;

package/dist/types/packages/core/src/platform/playwright/capability.d.ts

@@ -0,0 +1 @@
+export declare function browserOwnerCapability(capability: string, owner: string): string;

package/dist/types/packages/core/src/platform/playwright/manager.d.ts

@@ -1,18 +1,78 @@
-import { PLAYWRIGHT_PORTS_DIR } from "../config";
-export { cleanupZombiePlaywright, isBrowserJanitorOwner, selectOrphanBrowserPids, } from "./browser-processes";
+import { type BrowserProxyConfig, PLAYWRIGHT_PORTS_DIR } from "../config";
+export interface PlaywrightProfileBinding {
+    readonly instanceKey: string;
+    readonly ownerId: string;
+    readonly profile: string;
+}
+export interface PlaywrightChildEnvironmentContext {
+    instanceKey: string;
+    ownerId: string;
+    capability: string;
+    proxy: BrowserProxyConfig | null;
+    browserRsBin?: string;
+    environment: NodeJS.ProcessEnv;
+}
+export interface PlaywrightManagerHost {
+    readonly portsDir: string;
+    readonly basePort: number;
+    readonly maxPort: number;
+    readonly browserBin: string;
+    readonly fallbackBrowserBin: string;
+    readonly browserRsBin?: string;
+    readonly resolveProxy: () => BrowserProxyConfig | null;
+    readonly resolveTopicBinding: (userId: string, topic?: string) => PlaywrightProfileBinding;
+    readonly resolveNamedBinding: (ownerId: string, rawProfile: string) => PlaywrightProfileBinding;
+    readonly resolveInstanceDataDir: (instanceKey: string) => string;
+    readonly createChildEnvironment: (context: PlaywrightChildEnvironmentContext) => NodeJS.ProcessEnv;
+    /** Reap an orphan that owns this exact host-managed data directory. */
+    readonly cleanupBrowserProcessesForDataDir: (userDataDir: string) => void;
+    /** Reap host-managed browsers that are not represented by the supplied live directories. */
+    readonly reapOrphanBrowsers: (liveUserDataDirs: Iterable<string>) => void;
+}
+export { cleanupZombiePlaywright, isBrowserJanitorOwner, reapOrphanBrowsers, selectOrphanBrowserPids, } from "./browser-processes";
+export { probePlaywrightMcpTransports } from "./transport-probe";
 export { browserProcessMatchesExpectedProfile, extractUserDataDirArg, selectIdleEvictionKey, selectReusablePort, waitForChildProcessExit, waitForChildProcessSpawnError, } from "./manager-utils";
 export { PLAYWRIGHT_PORTS_DIR };
 /** Multiple topics assigned to one profile reuse one browser process. */
 export declare function makeInstanceKey(userId: string, topic: string | undefined): string;
+export declare function resolvePlaywrightTopicBinding(userId: string, topic: string | undefined): PlaywrightProfileBinding;
 export declare function makeBrowserProfileInstanceKey(ownerId: string, rawProfile: string): string;
+export declare function resolvePlaywrightProfileBinding(ownerId: string, rawProfile: string): PlaywrightProfileBinding;
 export declare function legacyBrowserProfileName(topic: string): string;
+/**
+ * Configure product-specific profile storage and browser launch glue.
+ * Call once during bootstrap, before any browser instance is started.
+ */
+export declare function configurePlaywrightManagerHost(overrides: Partial<PlaywrightManagerHost>): Readonly<PlaywrightManagerHost>;
+export declare function getPlaywrightManagerHost(): Readonly<PlaywrightManagerHost>;
+/** Restore Negotium's built-in browser host after all instances are stopped. */
+export declare function resetPlaywrightManagerHost(): void;
+export interface PlaywrightMaintenanceControl {
+    /** Stop one of the locked instances before mutating its profile directory. */
+    stopInstance(instanceKey: string): Promise<boolean>;
+}
 /** Serialize destructive profile maintenance with normal browser startup. */
-export declare function withPlaywrightInstanceMaintenance<T>(rawKeys: string[], operation: () => Promise<T>): Promise<T>;
+export declare function withPlaywrightInstanceMaintenance<T>(rawKeys: string[], operation: (control: PlaywrightMaintenanceControl) => Promise<T>): Promise<T>;
+/** Stop one managed instance under the same serialization used by startup and profile mutation. */
+export declare function stopPlaywrightInstance(instanceKey: string): Promise<boolean>;
+/** Run owner-aware named-profile maintenance under one lifecycle barrier. */
+export declare function withPlaywrightProfileMaintenance<T>(ownerId: string, rawProfile: string, operation: (binding: PlaywrightProfileBinding, control: PlaywrightMaintenanceControl) => Promise<T>): Promise<T>;
+/** Stop a named profile before deleting or replacing its host-managed data directory. */
+export declare function stopPlaywrightProfile(ownerId: string, rawProfile: string): Promise<boolean>;
 export declare function pinPlaywrightInstance(instanceKey: string): void;
 export declare function unpinPlaywrightInstance(instanceKey: string): void;
 export declare function getPlaywrightCapability(instanceKey: string): string | undefined;
-type PlaywrightExitHandler = (instanceKey: string, code: number | null) => void;
-export declare function onPlaywrightExit(handler: PlaywrightExitHandler): void;
+/** Resolve a live browser capability back to its owning user. */
+export declare function resolvePlaywrightCapabilityOwner(capability: string): string | undefined;
+/** Run the configured host's path-bounded orphan sweep against current live instances. */
+export declare function reapPlaywrightOrphans(): void;
+export interface PlaywrightFailure {
+    reason: "exit" | "process-error" | "unhealthy";
+    code?: number | null;
+    error?: string;
+}
+type PlaywrightFailureHandler = (instanceKey: string, failure: PlaywrightFailure) => void;
+export declare function onPlaywrightFailure(handler: PlaywrightFailureHandler): () => void;
 /**
  * Ensure a healthy browser MCP server is running for this topic's profile.
  * Topics assigned to the same profile reuse one process and data directory.

package/dist/types/packages/core/src/platform/playwright/public-runtime.d.ts

@@ -0,0 +1,4 @@
+export { isBrowserJanitorOwner, selectOrphanBrowserPids, } from "./browser-processes";
+export { closeBrowserOwnerTabs, configurePlaywrightManagerHost, ensureBrowserProfile, ensurePlaywright, getPlaywrightCapability, getPlaywrightManagerHost, killAllPlaywright, makeBrowserProfileInstanceKey, makeInstanceKey, onPlaywrightFailure, type PlaywrightChildEnvironmentContext, type PlaywrightFailure, type PlaywrightMaintenanceControl, type PlaywrightManagerHost, type PlaywrightProfileBinding, pinPlaywrightInstance, reapPlaywrightOrphans, resetPlaywrightManagerHost, resolvePlaywrightCapabilityOwner, resolvePlaywrightProfileBinding, resolvePlaywrightTopicBinding, resolveTopicProfileDir, stopPlaywrightInstance, stopPlaywrightProfile, unpinPlaywrightInstance, withPlaywrightInstanceMaintenance, withPlaywrightProfileMaintenance, } from "./manager";
+export { browserProcessMatchesExpectedProfile, extractUserDataDirArg, selectIdleEvictionKey, selectReusablePort, waitForChildProcessExit, waitForChildProcessSpawnError, } from "./manager-utils";
+export { probeMcpTransport, probePlaywrightMcpTransports, } from "./transport-probe";

package/dist/types/packages/core/src/platform/playwright/transport-probe.d.ts

@@ -0,0 +1,13 @@
+import type { FetchLike, Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+interface ProbeTransportOptions {
+    terminate?: () => Promise<void>;
+    timeoutMs?: number;
+}
+export declare function probeMcpTransport(transport: Transport, options?: ProbeTransportOptions): Promise<boolean>;
+/**
+ * Exercise both authenticated transports used by browser-enabled agents.
+ * A process-only response or partial SSE handshake is insufficient: each
+ * transport must initialize, complete tools/list, and close cleanly.
+ */
+export declare function probePlaywrightMcpTransports(port: number, capability: string, fetchImpl?: FetchLike): Promise<boolean>;
+export {};

package/dist/types/packages/core/src/prompts/builders.d.ts

@@ -31,9 +31,35 @@ export interface SessionSystemPromptOpts {
     /** True only when the current adapter can deliver files to its chat. */
     fileDeliveryTools?: boolean;
 }
-export declare function buildTopicSystemPrompt(opts: SessionSystemPromptOpts): string;
-export declare function buildChannelSystemPrompt(opts: SessionSystemPromptOpts): string;
-export declare function buildManagerSystemPrompt(opts: SessionSystemPromptOpts): string;
+export type SessionPromptKind = "topic" | "channel" | "manager";
+export type PromptSectionSlot = "after-runtime-tools" | "after-shared-tasks" | "before-session-communication" | "after-session-communication" | "before-topic-configuration" | "after-topic-configuration" | "after-system-prompt";
+export interface PromptSectionContext extends SessionSystemPromptOpts {
+    sessionKind: SessionPromptKind;
+}
+export interface PromptExtraSection {
+    id: string;
+    slot: PromptSectionSlot;
+    order?: number;
+    render(context: PromptSectionContext): string | null | undefined;
+}
+export interface PromptTemplateRequest {
+    kind: "topic-system" | "channel-system" | "manager-system" | "visual-design";
+    filename: string;
+    fallback: string;
+}
+export interface PromptBuilderHost {
+    readonly loadTemplate?: (request: PromptTemplateRequest) => string | null | undefined;
+    readonly extraSections?: readonly PromptExtraSection[];
+}
+export interface PromptBuilders {
+    buildTopicSystemPrompt(opts: SessionSystemPromptOpts): string;
+    buildChannelSystemPrompt(opts: SessionSystemPromptOpts): string;
+    buildManagerSystemPrompt(opts: SessionSystemPromptOpts): string;
+}
+export declare function createPromptBuilders(host?: PromptBuilderHost): PromptBuilders;
+export declare const buildTopicSystemPrompt: (opts: SessionSystemPromptOpts) => string;
+export declare const buildChannelSystemPrompt: (opts: SessionSystemPromptOpts) => string;
+export declare const buildManagerSystemPrompt: (opts: SessionSystemPromptOpts) => string;
 export declare function buildMemoryPromptSection(opts: {
     briefFile: string;
     wikiDir: string;

package/dist/types/packages/core/src/query/active-rooms.d.ts

@@ -104,6 +104,8 @@ export interface RoomQueryControl {
     sessionId?: string | null;
     abortController: AbortController;
     abortReason: AbortReason;
+    /** Specific failure surfaced when infrastructure aborts the turn. */
+    abortError?: string;
     /** Epoch ms when this turn claimed the room (stale-abort guard). */
     startedAt?: number;
     /**

package/dist/types/packages/core/src/query/public-runtime.d.ts

@@ -1,3 +1,4 @@
 export { type DeferredInject, DeferredInjectBatcher, type DeferredInjectBatcherOptions, InterSessionQueue, type PrepareInjectSession, wsAbortReason, } from "./active-rooms";
 export { createRoomQueryRegistry, isIsolatedTurnRoomId, isolatedTurnRoomId, isUserOrigin, type RoomQueryControlLike, type RoomQueryDecision, type RoomQueryRegistry, type RoomQueryRegistryHost, type RuntimeTurnLeaseLike, } from "./room-query-registry";
+export { clearQueryState, createQueryStateStore, type QueryStateStore, type QueryStateStoreLogger, type QueryStateStoreOptions, writeQueryState, } from "./state";
 export { AbortReason, type HandleAgentQueryOutcome, type HandleAgentQueryParams, } from "./types";

package/dist/types/packages/core/src/query/state.d.ts

@@ -1,4 +1,17 @@
 type QueryStateUserId = number | string;
+export interface QueryStateStoreLogger {
+    warn(context: Record<string, unknown>, message: string): void;
+}
+export interface QueryStateStoreOptions {
+    usersLogDir: string;
+    logger?: QueryStateStoreLogger;
+    sanitizeTopicId?: (topicId: string) => string;
+}
+export interface QueryStateStore {
+    write(userId: QueryStateUserId, topicId: string, topicName: string, task?: string): void;
+    clear(userId: QueryStateUserId, topicId: string, legacyTopicName?: string): void;
+}
+export declare function createQueryStateStore(options: QueryStateStoreOptions): QueryStateStore;
 export declare function writeQueryState(userId: QueryStateUserId, topicId: string, topicName: string, task?: string): void;
 export declare function clearQueryState(userId: QueryStateUserId, topicId: string, legacyTopicName?: string): void;
 export {};

package/dist/types/packages/core/src/query/types.d.ts

@@ -59,6 +59,7 @@ export interface HandleAgentQueryParams extends BaseQueryParams, OutputParams, I
 export declare enum AbortReason {
     None = "none",
     Internal = "internal",// replaced by a newer query on the same topic
-    External = "external"
+    External = "external",// /abort command or abort_session via session-inbox
+    Infrastructure = "infrastructure"
 }
 export {};

package/dist/types/packages/core/src/runtime/playwright-turn-abort.d.ts

@@ -0,0 +1,12 @@
+import { type PlaywrightFailure } from "../platform/playwright/manager";
+import { AbortReason } from "../query/types";
+export interface PlaywrightTurnControl {
+    topicId: string;
+    queryId: string;
+    abortController: AbortController;
+    abortReason: AbortReason;
+    abortError?: string;
+}
+export declare function trackPlaywrightTurn(instanceKey: string, control: PlaywrightTurnControl): void;
+export declare function untrackPlaywrightTurn(instanceKey: string, control: PlaywrightTurnControl): void;
+export declare function abortPlaywrightTurns(instanceKey: string, failure: PlaywrightFailure): number;

package/dist/types/packages/core/src/version.d.ts

@@ -1 +1 @@
-export declare const NEGOTIUM_VERSION = "0.1.37";
+export declare const NEGOTIUM_VERSION = "0.1.39";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "negotium",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "type": "module",
   "description": "Install the Negotium multi-agent runtime and CLI with one package",
   "license": "Apache-2.0",
@@ -78,6 +78,11 @@
       "import": "./dist/background-bash.js",
       "default": "./dist/background-bash.js"
     },
+    "./browser-runtime": {
+      "types": "./dist/types/packages/core/src/platform/playwright/public-runtime.d.ts",
+      "import": "./dist/browser-runtime.js",
+      "default": "./dist/browser-runtime.js"
+    },
     "./outbox": {
       "types": "./dist/types/packages/core/src/outbox/index.d.ts",
       "import": "./dist/outbox.js",