negotium 0.1.7 → 0.1.9

package/dist/runtime/src/agents/maestro-provider.ts

@@ -0,0 +1,206 @@
+/**
+ * Maestro agent provider — thin local adapter over `maestro-agent-sdk`.
+ *
+ * Mirrors the pattern of claude-provider.ts / codex-provider.ts so that
+ * agents/index.ts can import all three providers from sibling `@/agents/*`
+ * paths rather than mixing package and local imports. The wrapper layer is
+ * the natural extension point for Otium-specific overrides — anything
+ * we want every maestro call to inherit gets stamped here before reaching
+ * the SDK.
+ *
+ * v0.1.19 host overrides:
+ *   - `enableBackgroundBash: false` — the SDK's Claude-Code-style triad
+ *     (`Bash(run_in_background:true)` + `BashOutput` + `KillBash`) is OFF.
+ *     It was briefly always-on, but in this headless setup a background
+ *     bash's completion never triggers a new model turn — the process runs
+ *     in the bot but nobody polls it once the turn ends. Topics use
+ *     `mcp__background-bash__background_bash_run` instead, which injects a
+ *     session-inbox tell entry on exit so the loop actually closes.
+ *
+ * v0.1.21 host overrides:
+ *   - `maxTokens: 32_768` — global default for the per-API-call output
+ *     ceiling. Pre-v0.1.21 the SDK silently fell back to 4096, which
+ *     truncated long-form generation mid-string and broke Write/Edit
+ *     tool input JSON for multi-K file bodies (see the v0.1.21
+ *     changelog for the bug write-up). 32K is the Otium-wide
+ *     default because:
+ *       - long-form legal reports (슈퍼로이어, 기일보고) routinely
+ *         exceed 4K and have been the load-bearing failure surface;
+ *       - 32K is generous enough that ~99% of realistic single-turn
+ *         outputs fit without truncation;
+ *       - keeps cost / latency bounded relative to the SDK's own
+ *         model-catalog defaults (deepseek-pro 64K, deepseek-flash 32K)
+ *         which can be expensive for accidental long outputs.
+ *     Callers that need more (or less) override per-call via
+ *     `AgentQueryOptions.maxTokens` — the caller-supplied value wins
+ *     because `...opts` spreads AFTER the defaults below.
+ *
+ * v0.1.22 host overrides:
+ *   - `enableToolSearch: true` — deferred-tool / ToolSearch pattern is ON.
+ *     The pattern adds a round-trip every time a new tool is first reached
+ *     for (turn N: model calls `ToolSearch` → turn N+1: model calls the
+ *     actual tool), but that extra round-trip is now cheap relative to the
+ *     reminder-token savings across Otium's MCP server count, so the
+ *     tradeoff flipped in favor of deferral. Stamped as a literal `true`
+ *     (not omitted) so a code-reader sees the decision instead of guessing
+ *     intent. Caller-supplied `enableToolSearch: false` still wins because
+ *     `...opts` spreads AFTER this default; a future dispatcher / topic
+ *     config can flip it per topic if a specific topic's MCP server count
+ *     ever makes deferral not worth it.
+ *
+ * v0.1.42 host overrides:
+ *   - `disallowedTools` removes provider-native AskUserQuestion, Agent, and
+ *     Task* tools from the schema/catalog. Otium owns those surfaces via
+ *     runtime ask_user_question/spawn_subagent and the shared task MCP server
+ *     so state survives agent switches.
+ *
+ * If a future override becomes per-call (cwd-aware, topic-aware, etc.)
+ * we lift the static spread into a per-call wrapper. For now the
+ * overrides are uniform across every maestro turn, so a single
+ * Object.assign keeps the surface trivial.
+ */
+
+import "#platform/maestro-bootstrap-env";
+import type { HookRegistration, McpResolver } from "maestro-agent-sdk";
+import { maestroProvider as sdkMaestroProvider, setMcpResolver } from "maestro-agent-sdk";
+import {
+  hostedMcpServers,
+  redactHostedSecrets,
+  referencesHostedSecretStorage,
+  shouldRedirectHostedVaultTool,
+} from "#agents/execution-host";
+import { VAULT_BROKER_REDIRECT_ERROR } from "#agents/vault-tool-policy";
+import type { AgentQueryOptions, UnifiedEvent } from "#types";
+
+/**
+ * Default per-API-call max output tokens for every Otium maestro turn.
+ * See the file-level docstring for the rationale; callers override per call
+ * via `AgentQueryOptions.maxTokens`.
+ */
+const MAESTRO_DEFAULT_MAX_TOKENS = 32_768;
+const PROVIDER_ASK_USER_TOOL = "AskUserQuestion";
+const PROVIDER_SUBAGENT_TOOL = "Agent";
+const MAESTRO_NATIVE_TASK_TOOLS = [
+  "TaskCreate",
+  "TaskUpdate",
+  "TaskList",
+  "TaskGet",
+  "TaskOutput",
+  "TaskStop",
+] as const;
+const MAESTRO_PROVIDER_OWNED_TOOL_SET = new Set<string>([
+  PROVIDER_ASK_USER_TOOL,
+  PROVIDER_SUBAGENT_TOOL,
+  ...MAESTRO_NATIVE_TASK_TOOLS,
+]);
+const DEFAULT_MAESTRO_DISALLOWED_TOOLS = [
+  PROVIDER_ASK_USER_TOOL,
+  PROVIDER_SUBAGENT_TOOL,
+  ...MAESTRO_NATIVE_TASK_TOOLS,
+] as const;
+
+export function buildMaestroDisallowedTools(
+  callerDisallowedTools: readonly string[] = [],
+): readonly string[] {
+  return [...new Set([...DEFAULT_MAESTRO_DISALLOWED_TOOLS, ...callerDisallowedTools])];
+}
+
+/**
+ * Build per-call tool hooks:
+ *
+ * Pre hook — two responsibilities in one pass:
+ *   1. Block direct vault.db filesystem access (security guard).
+ *   2. Block direct placeholder substitution and redirect the model to the
+ *      Vault MCP credential broker, where expanded input stays outside the
+ *      provider process.
+ *
+ * Post hook — scrub raw/common encoded secret forms before tool output is sent
+ * back to the model. HTTP credentials should still prefer vault_http_request,
+ * whose broker never exposes the expanded request to the provider at all.
+ */
+function buildVaultHook(userId: string): HookRegistration {
+  return {
+    name: "vault-guard",
+    pre({ toolName, input }) {
+      if (referencesHostedSecretStorage(input)) {
+        return { decision: "block", error: "Runtime secret storage access is not permitted" };
+      }
+
+      // Detect key references from metadata only. No Vault value is decrypted
+      // or injected into the provider/tool registry on this path.
+      if (shouldRedirectHostedVaultTool(userId, toolName, input)) {
+        return { decision: "block", error: VAULT_BROKER_REDIRECT_ERROR };
+      }
+      return { decision: "allow" };
+    },
+    post({ output }) {
+      const redacted = redactHostedSecrets(userId, output);
+      return redacted === output ? {} : { output: redacted };
+    },
+  };
+}
+
+export function buildMaestroToolHooks(userId: string): HookRegistration[] {
+  return [buildVaultHook(userId), buildProviderOwnedToolBlockHook()];
+}
+
+function providerOwnedToolRedirect(toolName: string): string {
+  if (toolName === PROVIDER_ASK_USER_TOOL) {
+    return "Use the runtime ask_user_question MCP tool instead.";
+  }
+  if (toolName === PROVIDER_SUBAGENT_TOOL) {
+    return "Use the runtime spawn_subagent MCP tool instead.";
+  }
+  return (
+    "Use the shared task MCP tools instead " +
+    "(mcp__task__task_create / task_update / task_list / task_get / task_delete)."
+  );
+}
+
+function buildProviderOwnedToolBlockHook(): HookRegistration {
+  return {
+    name: "provider-owned-tool-redirect",
+    pre({ toolName }) {
+      if (!MAESTRO_PROVIDER_OWNED_TOOL_SET.has(toolName)) return { decision: "allow" };
+      return {
+        decision: "block",
+        error: `${toolName} is disabled in this environment. ${providerOwnedToolRedirect(toolName)}`,
+      };
+    },
+  };
+}
+
+export function maestroProvider(opts: AgentQueryOptions): AsyncGenerator<UnifiedEvent> {
+  // Dispatcher guarantees agent === "maestro" before routing here; throw early
+  // so routing bugs surface at the call site rather than silently overwriting.
+  if (opts.agent !== undefined && opts.agent !== "maestro") {
+    throw new Error(`maestroProvider: unexpected agent "${opts.agent}", expected "maestro"`);
+  }
+  const userId = opts.userId ?? "";
+  // The SDK deliberately ships with an empty MCP resolver. Keep this wiring in
+  // the provider adapter rather than every host bootstrap so a new Negotium
+  // channel cannot accidentally run Maestro with zero runtime/wiki/task MCPs.
+  setMcpResolver(hostedMcpServers as McpResolver);
+  const callerDisallowedTools = opts.disallowedTools ?? [];
+  const callerToolHooks = (opts as { toolHooks?: HookRegistration[] }).toolHooks ?? [];
+  // maestro-agent-sdk's type does not yet include Otium's "cron" sessionType;
+  // keep the runtime value intact so the host MCP resolver can choose cron scope.
+  const sdkOpts = {
+    // Built-in background bash (Bash/BashOutput/KillBash triad) is disabled
+    // because its completion never triggers a new model turn in this headless
+    // setup — the bash runs in the bot process but when the turn ends nobody
+    // polls it. Use mcp__background-bash__background_bash_run instead, which
+    // injects a session-inbox tell entry on exit so the loop closes properly.
+    enableBackgroundBash: false,
+    maxTokens: MAESTRO_DEFAULT_MAX_TOKENS,
+    enableToolSearch: true,
+    ...opts,
+    // v0.1.39: SDK AgentQueryOptions.agent is narrowed to "maestro" only.
+    // Otium's AgentKind is wider ("claude"|"codex"|"maestro"), so stamp
+    // the literal to satisfy the SDK type.
+    agent: "maestro",
+    disallowedTools: buildMaestroDisallowedTools(callerDisallowedTools),
+    toolHooks: [...buildMaestroToolHooks(userId), ...callerToolHooks],
+  } as unknown as Parameters<typeof sdkMaestroProvider>[0];
+  return sdkMaestroProvider(sdkOpts);
+}

package/dist/runtime/src/agents/maestro-registry.ts

@@ -0,0 +1,31 @@
+/**
+ * Maestro agent registry — local re-export of `maestro-agent-sdk` with
+ * a project-specific default-model override.
+ *
+ * Mirrors the pattern of claude-registry.ts / codex-registry.ts so that
+ * agents/registry.ts can resolve all three AgentRegistry instances from
+ * sibling `@/agents/*` paths, keeping the import topology consistent.
+ *
+ * maestro-agent-sdk v0.1.39 is DeepSeek-only — the Anthropic and Codex
+ * providers were removed. The SDK's own default is `deepseek-pro`, which
+ * matches this override. The override is kept explicit so the intent is
+ * clear if the upstream default ever changes; users can still switch to
+ * `deepseek-flash` per-topic via `/model deepseek-flash`.
+ */
+import "#platform/maestro-bootstrap-env";
+import {
+  setConversationReader,
+  maestroRegistry as upstreamMaestroRegistry,
+} from "maestro-agent-sdk";
+import type { AgentRegistry } from "#agents/contracts";
+import { readConversation } from "#storage/conversations";
+
+// The SDK intentionally defaults its conversation reader to `() => []` so it
+// can stay storage-agnostic. Wire Negotium's unified log into it once at module
+// load; otherwise Maestro forkSession() creates a valid but empty rollout.
+setConversationReader(readConversation as Parameters<typeof setConversationReader>[0]);
+
+export const maestroRegistry: AgentRegistry = {
+  ...(upstreamMaestroRegistry as AgentRegistry),
+  defaultModel: "deepseek-pro",
+};

package/dist/runtime/src/agents/mcp-tools/ask-user.ts

@@ -0,0 +1,280 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { errorResult, type SharedMcpTool, textResult } from "#agents/mcp-tools/common";
+import { WsHub } from "#bus";
+import {
+  appendApiMessage,
+  getApiMessage,
+  updateApiMessageAskUserQuestion,
+} from "#storage/api-messages";
+import { getApiTopicConfig } from "#storage/api-topic-config";
+import { getTopic } from "#storage/api-topics";
+import type { AgentKind } from "#types";
+import type { MessageDto } from "#types/api";
+
+const MAX_QUESTION_CHARS = 2000;
+const MAX_CHOICE_LABEL_CHARS = 128;
+const MAX_CHOICE_DESCRIPTION_CHARS = 500;
+const MAX_CHOICES = 12;
+
+export type AskUserChoice = { label: string; description?: string };
+
+export interface AskUserToolContext {
+  userId: string;
+  topicId: string;
+  queryId?: string;
+  agent: AgentKind;
+  model?: string;
+}
+
+export type ClaimedAskUserAnswer = {
+  choice: AskUserChoice;
+  queryId?: string;
+  resolve: (userId: string) => void;
+};
+
+export type AnswerAskUserQuestionResult =
+  | { ok: true; queryId?: string; answerMessage: MessageDto }
+  | { ok: false; error: string };
+
+type PendingAsk = {
+  topicId: string;
+  queryId?: string;
+  messageId: string;
+  question: string;
+  choices: AskUserChoice[];
+  resolve: (answer: AskUserChoice & { userId: string }) => void;
+};
+
+const pendingAsks = new Map<string, PendingAsk>();
+
+function normalizeAskText(value: unknown, maxChars: number): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (!normalized) return undefined;
+  return normalized.length > maxChars
+    ? `${normalized.slice(0, maxChars).trimEnd()}...`
+    : normalized;
+}
+
+export function normalizeAskUserChoices(value: unknown): AskUserChoice[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((choice) => {
+      if (!choice || typeof choice !== "object") return null;
+      const record = choice as Record<string, unknown>;
+      const label = normalizeAskText(record.label, MAX_CHOICE_LABEL_CHARS);
+      if (!label) return null;
+      const description = normalizeAskText(record.description, MAX_CHOICE_DESCRIPTION_CHARS);
+      return {
+        label,
+        ...(description ? { description } : {}),
+      };
+    })
+    .filter((choice): choice is AskUserChoice => choice !== null)
+    .slice(0, MAX_CHOICES);
+}
+
+export function normalizeAskUserQuestionInput(input: {
+  question?: unknown;
+  choices?: unknown;
+}): { question: string; choices: AskUserChoice[] } | { error: string } {
+  const question = normalizeAskText(input.question, MAX_QUESTION_CHARS);
+  if (!question) return { error: "question is required" };
+  const choices = normalizeAskUserChoices(input.choices);
+  if (choices.length === 0) return { error: "at least one choice is required" };
+  return { question, choices };
+}
+
+export function hasPendingAskUserQuestion(topicId: string, messageId: string): boolean {
+  const pending = pendingAsks.get(messageId);
+  return Boolean(pending && pending.topicId === topicId);
+}
+
+export function claimPendingAskUserQuestion(
+  topicId: string,
+  messageId: string,
+  label: string,
+): ClaimedAskUserAnswer | null {
+  const pending = pendingAsks.get(messageId);
+  if (!pending || pending.topicId !== topicId) return null;
+  const choice = pending.choices.find((item) => item.label === label);
+  if (!choice) return null;
+  pendingAsks.delete(messageId);
+  return {
+    choice,
+    queryId: pending.queryId,
+    resolve: (userId: string) => pending.resolve({ ...choice, userId }),
+  };
+}
+
+/**
+ * Host-neutral answer path for runtime ask cards. Web, terminal, Telegram, and
+ * future adapters should call this rather than reimplementing pending-map and
+ * persistence ordering. A successful call resumes the blocked MCP tool in the
+ * same provider turn.
+ */
+export function answerPendingAskUserQuestion(
+  topicId: string,
+  messageId: string,
+  label: string,
+  userId: string,
+): AnswerAskUserQuestionResult {
+  const topic = getTopic(topicId);
+  if (!topic?.participants.some((participant) => participant.userId === userId)) {
+    return { ok: false, error: "User is not a member of this topic." };
+  }
+  const existing = getApiMessage(topicId, messageId);
+  const ask = existing?.kind === "ask_user_question" ? existing.askUserQuestion : undefined;
+  if (!existing || existing.deleted || !ask) {
+    return { ok: false, error: "Ask card not found." };
+  }
+  if (ask.expired || ask.selectedLabel) {
+    return { ok: false, error: "This question is no longer awaiting an answer." };
+  }
+  if (!ask.choices.some((choice) => choice.label === label)) {
+    return { ok: false, error: "Invalid choice." };
+  }
+
+  const claimed = claimPendingAskUserQuestion(topicId, messageId, label);
+  if (!claimed) return { ok: false, error: "This question is no longer awaiting an answer." };
+
+  try {
+    const editedAt = new Date().toISOString();
+    const nextAsk = { ...ask, selectedLabel: label };
+    const updated = updateApiMessageAskUserQuestion(topicId, messageId, nextAsk, editedAt);
+    if (!updated) {
+      claimed.resolve("");
+      return { ok: false, error: "Ask card not found." };
+    }
+    WsHub.get().broadcastMessageUpdated(topicId, messageId, {
+      askUserQuestion: nextAsk,
+      editedAt,
+    });
+
+    const answerMessage: MessageDto = {
+      id: randomUUID(),
+      topicId,
+      authorId: userId,
+      text: label,
+      parentId: messageId,
+      createdAt: new Date().toISOString(),
+    };
+    appendApiMessage(answerMessage);
+    WsHub.get().broadcastMessage(topicId, answerMessage);
+    claimed.resolve(userId);
+    return { ok: true, queryId: claimed.queryId, answerMessage };
+  } catch (error) {
+    claimed.resolve("");
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export function cancelPendingAskUserQuestions(topicId: string, queryId: string): void {
+  for (const [messageId, pending] of pendingAsks) {
+    if (pending.topicId === topicId && pending.queryId === queryId) {
+      pendingAsks.delete(messageId);
+      const editedAt = new Date().toISOString();
+      const expiredAsk = {
+        question: pending.question,
+        choices: pending.choices,
+        expired: true,
+      } satisfies NonNullable<MessageDto["askUserQuestion"]>;
+      const updated = updateApiMessageAskUserQuestion(topicId, messageId, expiredAsk, editedAt);
+      if (updated) {
+        WsHub.get().broadcastMessageUpdated(topicId, messageId, {
+          askUserQuestion: expiredAsk,
+          editedAt,
+        });
+      }
+      pending.resolve({
+        label: "No answer",
+        description: "The AI turn ended before the user answered.",
+        userId: "",
+      });
+    }
+  }
+}
+
+function appendAskMessage(
+  ctx: AskUserToolContext,
+  question: string,
+  choices: AskUserChoice[],
+): MessageDto {
+  const cfg = getApiTopicConfig(ctx.topicId);
+  const msg: MessageDto = {
+    id: `ask-${ctx.queryId ?? "runtime"}-${randomUUID()}`,
+    topicId: ctx.topicId,
+    authorId: "ai",
+    text: question,
+    queryId: ctx.queryId,
+    agentType: ctx.agent,
+    model: ctx.model ?? cfg?.model ?? "unknown",
+    kind: "ask_user_question",
+    askUserQuestion: { question, choices },
+    createdAt: new Date().toISOString(),
+  };
+  appendApiMessage(msg);
+  return msg;
+}
+
+async function askUserQuestion(
+  ctx: AskUserToolContext,
+  input: { question?: unknown; choices?: unknown },
+) {
+  const topic = getTopic(ctx.topicId);
+  if (!topic) return errorResult(`Error: topic '${ctx.topicId}' not found.`);
+  if (!topic.participants.some((p: { userId: string }) => p.userId === ctx.userId)) {
+    return errorResult("Error: user is not a member of this topic.");
+  }
+
+  const normalized = normalizeAskUserQuestionInput(input);
+  if ("error" in normalized) return errorResult(`Error: ${normalized.error}.`);
+
+  const { question, choices } = normalized;
+  const msg = appendAskMessage(ctx, question, choices);
+
+  const answer = await new Promise<AskUserChoice & { userId: string }>((resolve) => {
+    pendingAsks.set(msg.id, {
+      topicId: ctx.topicId,
+      queryId: ctx.queryId,
+      messageId: msg.id,
+      question,
+      choices,
+      resolve,
+    });
+    WsHub.get().broadcastMessage(ctx.topicId, msg);
+  });
+
+  if (!answer.userId) {
+    return errorResult("The AI turn ended before the user answered.");
+  }
+  const description = answer.description ? `\nDescription: ${answer.description}` : "";
+  return textResult(
+    `User selected: ${answer.label}${description}\nContinue from this selection and finish the current turn.`,
+  );
+}
+
+export function createAskUserToolDefinition(ctx: AskUserToolContext): SharedMcpTool {
+  return {
+    name: "ask_user_question",
+    description:
+      "Ask the user a blocking multiple-choice question in the chat and wait for their selection. Use this instead of provider built-in AskUserQuestion. Use only when you cannot proceed safely without the user's choice.",
+    schema: {
+      question: z.string().describe("The concise question to show to the user."),
+      choices: z
+        .array(
+          z.object({
+            label: z.string().describe("Choice label shown on the button."),
+            description: z.string().optional().describe("Optional one-sentence consequence."),
+          }),
+        )
+        .min(1)
+        .max(MAX_CHOICES)
+        .describe("Choices the user can select."),
+    },
+    async handler(input) {
+      return askUserQuestion(ctx, input);
+    },
+  };
+}

package/dist/runtime/src/agents/mcp-tools/common.ts

@@ -0,0 +1,21 @@
+export type McpTextContent = { type: "text"; text: string };
+
+export type McpToolResult = {
+  content: McpTextContent[];
+  isError?: true;
+};
+
+export type SharedMcpTool = {
+  name: string;
+  description: string;
+  schema: Record<string, unknown>;
+  handler: (input: any) => McpToolResult | Promise<McpToolResult>;
+};
+
+export function textResult(text: string): McpToolResult {
+  return { content: [{ type: "text", text }] };
+}
+
+export function errorResult(text: string): McpToolResult {
+  return { content: [{ type: "text", text }], isError: true };
+}