negotium 0.1.38 → 0.1.39

package/dist/runtime/src/prompts/builders.ts

@@ -175,6 +175,44 @@ export interface SessionSystemPromptOpts {
   fileDeliveryTools?: boolean;
 }
 
+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;
+}
+
 interface RuntimeToolSectionOpts {
   agentKind: AgentKind;
   canSpawnSubagents?: boolean;
@@ -187,7 +225,15 @@ interface RuntimeToolSectionOpts {
   subagentReportMode?: SubagentReportMode;
 }
 
-function buildRuntimeToolSection(opts: RuntimeToolSectionOpts): string {
+interface RuntimeToolSectionExtensions {
+  render(slot: PromptSectionSlot): string[];
+  visualDesignGuide: string;
+}
+
+function buildRuntimeToolSection(
+  opts: RuntimeToolSectionOpts,
+  extensions: RuntimeToolSectionExtensions,
+): string {
   const {
     agentKind,
     canSpawnSubagents = false,
@@ -282,13 +328,16 @@ function buildRuntimeToolSection(opts: RuntimeToolSectionOpts): string {
           'Do not use provider built-in "AskUserQuestion"; it is disabled or unsupported in this headless chat runtime. Use the runtime ask_user_question tool instead.',
         ]),
     scheduleSelfToolLine,
-    ...(visualTools ? ["", visualDesignGuide()] : []),
+    ...(visualTools && extensions.visualDesignGuide ? ["", extensions.visualDesignGuide] : []),
+    ...extensions.render("after-runtime-tools"),
     "",
     "## Shared Tasks",
     taskToolLine,
     "Use this shared task store for plans, task progress, and checklist updates. It is visible across claude/codex/maestro turns and drives the live task panel.",
     nativeTaskPolicyLine,
+    ...extensions.render("after-shared-tasks"),
     ...fileDeliverySection,
+    ...extensions.render("before-session-communication"),
     "",
     "## Session Communication",
     ...(subagentParentTitle
@@ -313,6 +362,7 @@ function buildRuntimeToolSection(opts: RuntimeToolSectionOpts): string {
       : []),
     "Do not use session communication to make another topic perform destructive changes without the user's clear intent.",
     ...spawnSubagentSection,
+    ...extensions.render("after-session-communication"),
   ];
 
   const modelCatalog = SELECTABLE_MODELS.map(
@@ -343,69 +393,160 @@ function buildRuntimeToolSection(opts: RuntimeToolSectionOpts): string {
   if (agentKind !== "claude") {
     return [
       ...shared,
+      ...extensions.render("before-topic-configuration"),
       ...topicConfig,
+      ...extensions.render("after-topic-configuration"),
       "",
       "## Runtime Tool Limits",
       "If file delivery or topic configuration tools are not present in your available tools for this session, do not claim you used them. Tell the user this session does not expose that in-chat tool action.",
     ].join("\n");
   }
 
-  return [...shared, ...topicConfig].join("\n");
+  return [
+    ...shared,
+    ...extensions.render("before-topic-configuration"),
+    ...topicConfig,
+    ...extensions.render("after-topic-configuration"),
+  ].join("\n");
 }
 
-export function buildTopicSystemPrompt(opts: SessionSystemPromptOpts): string {
-  const uploadsDir = `${opts.workspaceCwd}/attachments`;
-  let prompt =
-    replaceVars(topicSystemPromptTemplate(), {
-      AI_LABEL: opts.aiLabel,
-      TOPIC_TITLE: opts.topicTitle,
-      WORKSPACE_CWD: opts.workspaceCwd,
-      UPLOADS_DIR: uploadsDir,
-    }) +
-    buildRuntimeToolSection({
-      agentKind: opts.agentKind,
-      canSpawnSubagents: opts.canSpawnSubagents,
-      canStageSubagents: opts.canStageSubagents,
-      visualTools: opts.visualTools,
-      fileDeliveryTools: opts.fileDeliveryTools,
-      currentModel: opts.currentModel,
-      currentEffort: opts.currentEffort,
-      subagentParentTitle: opts.subagentParentTitle,
-      subagentReportMode: opts.subagentReportMode,
-    });
-  if (opts.description?.trim()) {
-    prompt += `\n\n## Topic-Specific Instructions\n${opts.description.trim()}`;
+export function createPromptBuilders(host: PromptBuilderHost = {}): PromptBuilders {
+  const loadTemplate = host.loadTemplate;
+  const sections = (host.extraSections ?? []).map((section): PromptExtraSection => {
+    const render = section.render;
+    const snapshot: PromptExtraSection = {
+      id: section.id,
+      slot: section.slot,
+      ...(section.order === undefined ? {} : { order: section.order }),
+      render(context) {
+        return render.call(snapshot, context);
+      },
+    };
+    return Object.freeze(snapshot);
+  });
+  const ids = new Set<string>();
+  for (const section of sections) {
+    if (!section.id.trim()) throw new Error("prompt extra section id is required");
+    if (ids.has(section.id)) throw new Error(`duplicate prompt extra section id: ${section.id}`);
+    ids.add(section.id);
   }
-  return prompt;
-}
+  sections.sort((a, b) => (a.order ?? 0) - (b.order ?? 0) || a.id.localeCompare(b.id));
+
+  const templateCache = new Map<PromptTemplateRequest["kind"], string>();
+  const template = (request: PromptTemplateRequest): string => {
+    const cached = templateCache.get(request.kind);
+    if (cached !== undefined) return cached;
+    const loaded = loadTemplate?.(request);
+    const value =
+      loaded ??
+      (request.kind === "topic-system"
+        ? topicSystemPromptTemplate()
+        : request.kind === "channel-system"
+          ? channelSystemPromptTemplate()
+          : request.kind === "manager-system"
+            ? managerSystemPromptTemplate()
+            : visualDesignGuide());
+    templateCache.set(request.kind, value);
+    return value;
+  };
 
-export function buildChannelSystemPrompt(opts: SessionSystemPromptOpts): string {
-  const uploadsDir = `${opts.workspaceCwd}/attachments`;
-  return (
-    replaceVars(channelSystemPromptTemplate(), {
-      AI_LABEL: opts.aiLabel,
-      TOPIC_TITLE: opts.topicTitle,
-      WORKSPACE_CWD: opts.workspaceCwd,
-      UPLOADS_DIR: uploadsDir,
-    }) +
-    buildRuntimeToolSection({
-      agentKind: opts.agentKind,
-      canSpawnSubagents: false,
-      canStageSubagents: false,
-      visualTools: opts.visualTools,
-      fileDeliveryTools: opts.fileDeliveryTools,
-      currentModel: opts.currentModel,
-      currentEffort: opts.currentEffort,
-      subagentParentTitle: opts.subagentParentTitle,
-      subagentReportMode: opts.subagentReportMode,
-    })
-  );
-}
+  const build = (
+    sessionKind: SessionPromptKind,
+    opts: SessionSystemPromptOpts,
+    sessionTemplate: string,
+  ): string => {
+    const context = Object.freeze({ ...opts, sessionKind });
+    const render = (slot: PromptSectionSlot): string[] =>
+      sections
+        .filter((section) => section.slot === slot)
+        .map((section) => section.render(context)?.trim())
+        .filter((section): section is string => Boolean(section))
+        .flatMap((section) => ["", section]);
+    const uploadsDir = `${opts.workspaceCwd}/attachments`;
+    let prompt =
+      replaceVars(sessionTemplate, {
+        AI_LABEL: opts.aiLabel,
+        TOPIC_TITLE: opts.topicTitle,
+        WORKSPACE_CWD: opts.workspaceCwd,
+        UPLOADS_DIR: uploadsDir,
+      }) +
+      buildRuntimeToolSection(
+        {
+          agentKind: opts.agentKind,
+          canSpawnSubagents: sessionKind === "channel" ? false : opts.canSpawnSubagents,
+          canStageSubagents: sessionKind === "channel" ? false : opts.canStageSubagents,
+          visualTools: opts.visualTools,
+          fileDeliveryTools: opts.fileDeliveryTools,
+          currentModel: opts.currentModel,
+          currentEffort: opts.currentEffort,
+          subagentParentTitle: opts.subagentParentTitle,
+          subagentReportMode: opts.subagentReportMode,
+        },
+        {
+          render,
+          visualDesignGuide: template({
+            kind: "visual-design",
+            filename: "visual-design.md",
+            fallback: "",
+          }),
+        },
+      );
+    if (sessionKind !== "channel" && opts.description?.trim()) {
+      prompt += `\n\n## Topic-Specific Instructions\n${opts.description.trim()}`;
+    }
+    if (sessionKind === "manager") {
+      prompt += `\n\n${template({
+        kind: "manager-system",
+        filename: "manager-system.md",
+        fallback: FALLBACK_MANAGER_SYSTEM_PROMPT_TEMPLATE,
+      })}`;
+    }
+    return `${prompt}${render("after-system-prompt").join("\n")}`;
+  };
 
-export function buildManagerSystemPrompt(opts: SessionSystemPromptOpts): string {
-  return `${buildTopicSystemPrompt(opts)}\n\n${managerSystemPromptTemplate()}`;
+  return Object.freeze({
+    buildTopicSystemPrompt(opts: SessionSystemPromptOpts) {
+      return build(
+        "topic",
+        opts,
+        template({
+          kind: "topic-system",
+          filename: "topic-system.md",
+          fallback: FALLBACK_TOPIC_SYSTEM_PROMPT_TEMPLATE,
+        }),
+      );
+    },
+    buildChannelSystemPrompt(opts: SessionSystemPromptOpts) {
+      return build(
+        "channel",
+        opts,
+        template({
+          kind: "channel-system",
+          filename: "channel-system.md",
+          fallback: FALLBACK_CHANNEL_SYSTEM_PROMPT_TEMPLATE,
+        }),
+      );
+    },
+    buildManagerSystemPrompt(opts: SessionSystemPromptOpts) {
+      return build(
+        "manager",
+        opts,
+        template({
+          kind: "topic-system",
+          filename: "topic-system.md",
+          fallback: FALLBACK_TOPIC_SYSTEM_PROMPT_TEMPLATE,
+        }),
+      );
+    },
+  });
 }
 
+const defaultPromptBuilders = createPromptBuilders();
+
+export const buildTopicSystemPrompt = defaultPromptBuilders.buildTopicSystemPrompt;
+export const buildChannelSystemPrompt = defaultPromptBuilders.buildChannelSystemPrompt;
+export const buildManagerSystemPrompt = defaultPromptBuilders.buildManagerSystemPrompt;
+
 export function buildMemoryPromptSection(opts: {
   briefFile: string;
   wikiDir: string;

package/dist/runtime/src/query/public-runtime.ts

@@ -17,6 +17,14 @@ export {
   type RoomQueryRegistryHost,
   type RuntimeTurnLeaseLike,
 } from "./room-query-registry";
+export {
+  clearQueryState,
+  createQueryStateStore,
+  type QueryStateStore,
+  type QueryStateStoreLogger,
+  type QueryStateStoreOptions,
+  writeQueryState,
+} from "./state";
 export {
   AbortReason,
   type HandleAgentQueryOutcome,

package/dist/runtime/src/query/state.ts

@@ -7,38 +7,86 @@ import type { QueryState } from "#types";
 
 type QueryStateUserId = number | string;
 
-function queryStateDirPath(userId: QueryStateUserId): string {
-  return join(USERS_LOG_DIR, String(userId), "active-queries");
+export interface QueryStateStoreLogger {
+  warn(context: Record<string, unknown>, message: string): void;
 }
 
-function queryStateFile(userId: QueryStateUserId, topicId: string): string {
-  return join(queryStateDirPath(userId), `${sanitizeId(topicId)}.json`);
+export interface QueryStateStoreOptions {
+  usersLogDir: string;
+  logger?: QueryStateStoreLogger;
+  sanitizeTopicId?: (topicId: string) => string;
 }
 
-function legacyQueryStateFile(
-  userId: QueryStateUserId,
-  topicName: string | undefined,
-): string | null {
-  if (!topicName || topicName === "." || topicName === ".." || basename(topicName) !== topicName) {
-    return null;
-  }
-  return join(queryStateDirPath(userId), `${topicName}.json`);
+export interface QueryStateStore {
+  write(userId: QueryStateUserId, topicId: string, topicName: string, task?: string): void;
+  clear(userId: QueryStateUserId, topicId: string, legacyTopicName?: string): void;
 }
 
+export function createQueryStateStore(options: QueryStateStoreOptions): QueryStateStore {
+  const sanitize = options.sanitizeTopicId ?? sanitizeId;
+  const queryStateDirPath = (userId: QueryStateUserId): string =>
+    join(options.usersLogDir, String(userId), "active-queries");
+  const queryStateFile = (userId: QueryStateUserId, topicId: string): string =>
+    join(queryStateDirPath(userId), `${sanitize(topicId)}.json`);
+  const legacyQueryStateFile = (
+    userId: QueryStateUserId,
+    topicName: string | undefined,
+  ): string | null => {
+    if (
+      !topicName ||
+      topicName === "." ||
+      topicName === ".." ||
+      basename(topicName) !== topicName
+    ) {
+      return null;
+    }
+    return join(queryStateDirPath(userId), `${topicName}.json`);
+  };
+
+  return {
+    write(userId, topicId, topicName, task) {
+      const dir = queryStateDirPath(userId);
+      mkdirSync(dir, { recursive: true });
+      const state: QueryState = { topicId, topicName, since: new Date().toISOString() };
+      if (task) state.task = [...task.replace(/\n+/g, " ").trim()].slice(0, 100).join("");
+      const target = queryStateFile(userId, topicId);
+      const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+      writeFileSync(tmp, JSON.stringify(state));
+      renameSync(tmp, target);
+    },
+    clear(userId, topicId, legacyTopicName) {
+      const paths = [
+        queryStateFile(userId, topicId),
+        legacyQueryStateFile(userId, legacyTopicName),
+      ].filter((path): path is string => Boolean(path));
+      for (const path of new Set(paths)) {
+        try {
+          unlinkSync(path);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
+            options.logger?.warn(
+              { err: error, userId, topicId, path },
+              "Failed to clear query state file",
+            );
+          }
+        }
+      }
+    },
+  };
+}
+
+const defaultQueryStateStore = createQueryStateStore({
+  usersLogDir: USERS_LOG_DIR,
+  logger,
+});
+
 export function writeQueryState(
   userId: QueryStateUserId,
   topicId: string,
   topicName: string,
   task?: string,
 ) {
-  const dir = queryStateDirPath(userId);
-  mkdirSync(dir, { recursive: true });
-  const state: QueryState = { topicId, topicName, since: new Date().toISOString() };
-  if (task) state.task = [...task.replace(/\n+/g, " ").trim()].slice(0, 100).join("");
-  const target = queryStateFile(userId, topicId);
-  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
-  writeFileSync(tmp, JSON.stringify(state));
-  renameSync(tmp, target);
+  defaultQueryStateStore.write(userId, topicId, topicName, task);
 }
 
 export function clearQueryState(
@@ -46,17 +94,5 @@ export function clearQueryState(
   topicId: string,
   legacyTopicName?: string,
 ) {
-  const paths = [
-    queryStateFile(userId, topicId),
-    legacyQueryStateFile(userId, legacyTopicName),
-  ].filter((path): path is string => Boolean(path));
-  for (const path of new Set(paths)) {
-    try {
-      unlinkSync(path);
-    } catch (e) {
-      if ((e as NodeJS.ErrnoException)?.code !== "ENOENT") {
-        logger.warn({ err: e, userId, topicId, path }, "Failed to clear query state file");
-      }
-    }
-  }
+  defaultQueryStateStore.clear(userId, topicId, legacyTopicName);
 }

package/dist/runtime/src/version.ts

@@ -1 +1 @@
-export const NEGOTIUM_VERSION = "0.1.38";
+export const NEGOTIUM_VERSION = "0.1.39";

package/dist/types/packages/core/src/agents/api-topic-agent-switch.d.ts

@@ -0,0 +1,38 @@
+import { type TopicConfig } from "../storage/api-topic-config";
+import type { AgentKind, EffortLevel } from "../types";
+export type ApiTopicSwitchOutcome = {
+    kind: "fresh";
+    agent: AgentKind;
+    reason: "no-history" | "bridge-failed";
+} | {
+    kind: "bridged";
+    agent: AgentKind;
+    bridgedSessionId: string;
+    rolloutPath: string;
+};
+export type ApiTopicSwitchResult = {
+    ok: true;
+    outcome: ApiTopicSwitchOutcome;
+} | {
+    ok: false;
+    error: string;
+};
+export interface SwitchApiTopicAgentOptions {
+    topicId: string;
+    topicTitle: string;
+    userId: string;
+    fromAgent?: AgentKind;
+    agent: AgentKind;
+    cwd: string;
+    config: TopicConfig;
+    /** Topic base values used when config has no explicit override. */
+    defaultModel?: string;
+    defaultEffort?: EffortLevel;
+    reason: string;
+}
+/**
+ * API-topic equivalent of `switchTopicAgent`: all web/MCP agent changes must
+ * pass through this path so the synthetic SDK rollout, unified-log manifest,
+ * and durable topic session stay in sync.
+ */
+export declare function switchApiTopicAgent(opts: SwitchApiTopicAgentOptions): ApiTopicSwitchResult;

package/dist/types/packages/core/src/agents/archiver.d.ts

@@ -1,6 +1,6 @@
-import type { AgentKind } from "../types";
-import type { BackgroundSessionDto } from "../types/api";
-export declare function listActiveMemoryArchiverSessions(userId: string): BackgroundSessionDto[];
+import { type AgentDef } from "../prompts/builders";
+import type { AgentKind, AgentQueryOptions, UnifiedEvent } from "../types";
+import type { BackgroundSessionDto, MessageDto } from "../types/api";
 export interface RunArchiverTurnParams {
     /** Stringified user id (route layer hands us strings). */
     userId: string;
@@ -23,17 +23,53 @@ export interface RunArchiverTurnParams {
     /** Called once when an accepted background turn settles. */
     onSettled?: (success: boolean) => void;
 }
-/**
- * Fire a background wiki-archiver turn for a deleted topic or active idle
- * snapshot.
- *
- * Reads the forensic archive file produced by `archiveTopicMessages` and
- * distils it into the **shared** wiki (summaries / articles / topic brief /
- * indexes / skills) via the wiki MCP, which the turn launches in topic-id mode
- * so its writes land in the same root normal forum turns query.
- *
- * Fire-and-forget: the async generator is drained on a detached promise so the
- * caller's HTTP response returns immediately. Every failure is best-effort and
- * logged only — a broken archiver must never block or fail a topic deletion.
- */
+export interface ArchiverStorageHost {
+    getWikiDir(): string;
+    fileExists(path: string): boolean;
+    listDirectory(path: string): string[];
+    readTextFile(path: string): string;
+    fileSize(path: string): number;
+    fileModifiedAt(path: string): number;
+    getGeneralTopicId(userId: string): string;
+    getTopicBrief(topicId: string): {
+        briefMd: string;
+    } | null;
+    setTopicBrief(topicId: string, fields: {
+        briefMd: string;
+        latestSummaryMd?: string;
+        summaryDate?: string;
+    }): void;
+}
+export interface ArchiverMessagingHost {
+    appendMessage(message: MessageDto): void;
+    broadcastMessage(topicId: string, message: MessageDto): void;
+}
+export interface ArchiverConfigHost {
+    readonly workspaceDir: string;
+    readonly completedSessionRetentionMs: number;
+    loadAgentDefinition(): AgentDef;
+    sanitizeTopicName(topicTitle: string): string;
+    createId(): string;
+    now(): Date;
+    schedule(callback: () => void, delayMs: number): unknown;
+    cancelScheduled(handle: unknown): void;
+    unrefScheduled?(handle: unknown): void;
+    info(context: Record<string, unknown>, message: string): void;
+    warn(context: Record<string, unknown>, message: string): void;
+}
+export interface ArchiverAgentRuntimeHost {
+    run(options: AgentQueryOptions): AsyncIterable<UnifiedEvent>;
+}
+export interface ArchiverHost {
+    storage: ArchiverStorageHost;
+    messaging: ArchiverMessagingHost;
+    config: ArchiverConfigHost;
+    agentRuntime: ArchiverAgentRuntimeHost;
+}
+export interface ArchiverRuntime {
+    runArchiverTurn(params: RunArchiverTurnParams): boolean;
+    listActiveMemoryArchiverSessions(userId: string): BackgroundSessionDto[];
+}
+export declare function createArchiverRuntime(host: ArchiverHost): ArchiverRuntime;
 export declare function runArchiverTurn(params: RunArchiverTurnParams): boolean;
+export declare function listActiveMemoryArchiverSessions(userId: string): BackgroundSessionDto[];

package/dist/types/packages/core/src/agents/mcp-tools/ask-user.d.ts

@@ -1,6 +1,8 @@
 import { type SharedMcpTool } from "./common";
+import { type AskUserGateCardUpdate, type ClaimAskUserGateResult, type PrepareAskUserGateResult } from "../../storage/ask-user-gates";
+import { type RuntimeProcessLease, type RuntimeProcessLeaseHandle } from "../../storage/runtime-process-leases";
 import type { AgentKind } from "../../types";
-import type { MessageDto } from "../../types/api";
+import type { MessageDto, TopicDto } from "../../types/api";
 export type AskUserChoice = {
     label: string;
     description?: string;
@@ -20,8 +22,70 @@ export type AnswerAskUserQuestionResult = {
     ok: false;
     error: string;
 };
-export declare function startAskUserQuestionGateOwner(): void;
-export declare function stopAskUserQuestionGateOwner(): void;
+export interface AskUserRuntimeHost {
+    messaging: {
+        persistence: {
+            getMessage(topicId: string, messageId: string): MessageDto | null | undefined;
+            appendMessage(message: MessageDto): void;
+        };
+        publication: {
+            publishMessage(topicId: string, message: MessageDto): void;
+            publishCardUpdate(update: AskUserGateCardUpdate): void;
+        };
+    };
+    topics: {
+        getTopic(topicId: string): Pick<TopicDto, "participants"> | null | undefined;
+        getConfig(topicId: string): {
+            model?: string;
+        } | undefined;
+    };
+    durability: {
+        gates: {
+            prepare(args: {
+                gateId: string;
+                topicId: string;
+                queryId?: string;
+                idempotencyKey: string;
+                bodyHash: string;
+                messageId: string;
+                ownerId: string;
+                now: string;
+            }): PrepareAskUserGateResult;
+            claimAndSelect(args: {
+                topicId: string;
+                messageId: string;
+                label: string;
+                userId: string;
+                ownerId: string;
+                source: string;
+                now: string;
+            }): ClaimAskUserGateResult;
+            cancel(topicId: string, messageId: string, ownerId: string, now: string): AskUserGateCardUpdate | null;
+            quarantine(gateId: string, ownerId: string, now: string): AskUserGateCardUpdate | null;
+            quarantineForeign(liveOwnerIds: ReadonlySet<string>, now: string): AskUserGateCardUpdate[];
+        };
+        processLeases: {
+            acquire(role: string, ownerId: string): RuntimeProcessLeaseHandle | null;
+            list(rolePrefix: string): RuntimeProcessLease[];
+            isAlive(lease: RuntimeProcessLease): boolean;
+            removeDead(rolePrefix: string): void;
+        };
+    };
+    runtime: {
+        ownerId: string;
+        createId(): string;
+        now(): string;
+    };
+}
+export interface AskUserRuntime {
+    startGateOwner(): void;
+    stopGateOwner(): void;
+    reconcilePendingGates(): number;
+    hasPendingQuestion(topicId: string, messageId: string): boolean;
+    answerPendingQuestion(topicId: string, messageId: string, label: string, userId: string): AnswerAskUserQuestionResult;
+    cancelPendingQuestions(topicId: string, queryId: string): void;
+    createToolDefinition(ctx: AskUserToolContext): SharedMcpTool;
+}
 export declare function normalizeAskUserChoices(value: unknown): AskUserChoice[];
 export declare function normalizeAskUserQuestionInput(input: {
     question?: unknown;
@@ -32,8 +96,15 @@ export declare function normalizeAskUserQuestionInput(input: {
 } | {
     error: string;
 };
-export declare function hasPendingAskUserQuestion(topicId: string, messageId: string): boolean;
+/**
+ * Create an isolated ask-user lifecycle over host-provided messaging, topic,
+ * durability, and runtime services.
+ */
+export declare function createAskUserRuntime(host: AskUserRuntimeHost): AskUserRuntime;
+export declare function startAskUserQuestionGateOwner(): void;
+export declare function stopAskUserQuestionGateOwner(): void;
 export declare function reconcilePendingAskUserQuestionGates(): number;
+export declare function hasPendingAskUserQuestion(topicId: string, messageId: string): boolean;
 /**
  * Host-neutral answer path for runtime ask cards. Web, terminal, Telegram, and
  * future adapters should call this rather than reimplementing pending-map and

package/dist/types/packages/core/src/agents/mcp-tools/self-config.d.ts

@@ -0,0 +1,17 @@
+import { type SharedMcpTool } from "./common";
+import { SELF_CONFIG_MCP_KEY, type SelfConfigContext, type SelfConfigCore, type SelfConfigHost, type SelfConfigProductConfig } from "../self-config-core";
+export type { SelfConfigContext };
+export { SELF_CONFIG_MCP_KEY };
+export declare const SELF_CONFIG_DERIVED_TOPIC_LIMIT = 5;
+export interface SelfConfigRuntime {
+    readonly core: SelfConfigCore;
+    readonly mcpKey: string;
+    createToolDefinitions(ctx: SelfConfigContext | (() => SelfConfigContext)): SharedMcpTool[];
+}
+export interface SelfConfigRuntimeOptions {
+    host: SelfConfigHost;
+    product?: Partial<SelfConfigProductConfig>;
+}
+export declare function createSelfConfigRuntime(options: SelfConfigRuntimeOptions): SelfConfigRuntime;
+export declare function createSelfConfigToolDefinitionsForCore(core: SelfConfigCore, ctx: SelfConfigContext | (() => SelfConfigContext)): SharedMcpTool[];
+export declare function createSelfConfigToolDefinitions(ctx: SelfConfigContext | (() => SelfConfigContext)): SharedMcpTool[];