@capekai/core 1.0.0

package/src/core/stream-handlers.ts

@@ -0,0 +1,242 @@
+import type { TextPart, ToolPart, ReasoningPart, MessageEvent } from '@capekai/types';
+import { createPart, updatePart, getPart, persistStreamingPartSnapshots } from '../storage/runtime';
+import { parseToolInput } from './part-utils';
+import { randomUUID } from 'crypto';
+
+const STREAM_PART_PERSIST_INTERVAL_MS = 300;
+
+export interface StreamHandlerContext {
+  messageId: string;
+  sessionId: string;
+  toolParts: ToolPart[];
+  currentText: string;
+  currentTextPartId: string | null;
+  currentTextCreatedAt: number | null;
+  currentReasoning: string;
+  currentReasoningPartId: string | null;
+  currentReasoningCreatedAt: number | null;
+  yieldFn: (event: MessageEvent) => void;
+}
+
+interface StreamPersistenceState {
+  persistedText: string;
+  persistedReasoning: string;
+  lastTextPersistedAt: number;
+  lastReasoningPersistedAt: number;
+}
+
+export function createStreamHandlers(ctx: StreamHandlerContext) {
+  const persistence: StreamPersistenceState = {
+    persistedText: '',
+    persistedReasoning: '',
+    lastTextPersistedAt: 0,
+    lastReasoningPersistedAt: 0,
+  };
+
+  function shouldPersist(lastPersistedAt: number): boolean {
+    return Date.now() - lastPersistedAt >= STREAM_PART_PERSIST_INTERVAL_MS;
+  }
+
+  async function persistText(syncFts: boolean): Promise<void> {
+    if (!ctx.currentTextPartId || ctx.currentText === persistence.persistedText) return;
+    if (syncFts) {
+      // Final flush persists the complete text; message finalization performs explicit FTS sync.
+      await updatePart(ctx.currentTextPartId, { text: ctx.currentText }, { syncFts: false });
+      persistence.persistedText = ctx.currentText;
+      persistence.lastTextPersistedAt = Date.now();
+    } else {
+      // Intermediate snapshot: no read-before-write
+      await persistStreamingPartSnapshots([{
+        id: ctx.currentTextPartId,
+        messageId: ctx.messageId,
+        sessionId: ctx.sessionId,
+        type: 'text',
+        createdAt: ctx.currentTextCreatedAt ?? Date.now(),
+        text: ctx.currentText,
+      }]);
+      persistence.persistedText = ctx.currentText;
+      persistence.lastTextPersistedAt = Date.now();
+    }
+  }
+
+  async function persistReasoning(syncFts: boolean): Promise<void> {
+    if (!ctx.currentReasoningPartId || ctx.currentReasoning === persistence.persistedReasoning) return;
+    if (syncFts) {
+      await updatePart(ctx.currentReasoningPartId, { text: ctx.currentReasoning }, { syncFts: false });
+      persistence.persistedReasoning = ctx.currentReasoning;
+      persistence.lastReasoningPersistedAt = Date.now();
+    } else {
+      await persistStreamingPartSnapshots([{
+        id: ctx.currentReasoningPartId,
+        messageId: ctx.messageId,
+        sessionId: ctx.sessionId,
+        type: 'reasoning',
+        createdAt: ctx.currentReasoningCreatedAt ?? Date.now(),
+        text: ctx.currentReasoning,
+      }]);
+      persistence.persistedReasoning = ctx.currentReasoning;
+      persistence.lastReasoningPersistedAt = Date.now();
+    }
+  }
+
+  function resetTextState(): void {
+    ctx.currentTextPartId = null;
+    ctx.currentTextCreatedAt = null;
+    ctx.currentText = '';
+    persistence.persistedText = '';
+    persistence.lastTextPersistedAt = 0;
+  }
+
+  function resetReasoningState(): void {
+    ctx.currentReasoningPartId = null;
+    ctx.currentReasoningCreatedAt = null;
+    ctx.currentReasoning = '';
+    persistence.persistedReasoning = '';
+    persistence.lastReasoningPersistedAt = 0;
+  }
+
+  return {
+    async handleTextDelta(delta: { text: string | undefined }): Promise<void> {
+      const textContent = delta.text || '';
+      if (textContent) {
+        ctx.currentText += textContent;
+
+        if (ctx.currentTextPartId) {
+          ctx.yieldFn({ type: 'part.append', sessionId: ctx.sessionId, partId: ctx.currentTextPartId, field: 'text', delta: textContent });
+          if (shouldPersist(persistence.lastTextPersistedAt)) {
+            await persistText(false);
+          }
+        } else {
+          ctx.currentTextPartId = randomUUID();
+          ctx.currentTextCreatedAt = Date.now();
+          const textPart: TextPart = {
+            id: ctx.currentTextPartId,
+            messageId: ctx.messageId,
+            createdAt: ctx.currentTextCreatedAt,
+            type: 'text',
+            text: textContent,
+          };
+          ctx.yieldFn({ type: 'part.created', sessionId: ctx.sessionId, part: textPart });
+          await createPart(textPart, ctx.sessionId, { syncFts: false });
+          persistence.persistedText = textContent;
+          persistence.lastTextPersistedAt = Date.now();
+        }
+      }
+    },
+
+    async handleReasoningDelta(delta: { text: string | undefined }): Promise<void> {
+      const reasoningContent = delta.text || '';
+      if (reasoningContent) {
+        ctx.currentReasoning += reasoningContent;
+
+        if (ctx.currentReasoningPartId) {
+          ctx.yieldFn({ type: 'part.append', sessionId: ctx.sessionId, partId: ctx.currentReasoningPartId, field: 'reasoning', delta: reasoningContent });
+          if (shouldPersist(persistence.lastReasoningPersistedAt)) {
+            await persistReasoning(false);
+          }
+        } else {
+          ctx.currentReasoningPartId = randomUUID();
+          ctx.currentReasoningCreatedAt = Date.now();
+          const reasoningPart: ReasoningPart = {
+            id: ctx.currentReasoningPartId,
+            messageId: ctx.messageId,
+            createdAt: ctx.currentReasoningCreatedAt,
+            type: 'reasoning',
+            text: reasoningContent,
+          };
+          ctx.yieldFn({ type: 'part.created', sessionId: ctx.sessionId, part: reasoningPart });
+          await createPart(reasoningPart, ctx.sessionId, { syncFts: false });
+          persistence.persistedReasoning = reasoningContent;
+          persistence.lastReasoningPersistedAt = Date.now();
+        }
+      }
+    },
+
+    async handleToolCall(delta: { toolCallId: string; toolName: string; input: unknown }): Promise<void> {
+      await this.flushPending();
+
+      const toolPartId = randomUUID();
+      const toolPart: ToolPart = {
+        id: toolPartId,
+        messageId: ctx.messageId,
+        createdAt: Date.now(),
+        type: 'tool',
+        callId: delta.toolCallId,
+        name: delta.toolName,
+        state: {
+          status: 'pending',
+          input: parseToolInput(delta.input),
+        },
+      };
+      ctx.toolParts.push(toolPart);
+
+      ctx.yieldFn({ type: 'part.created', sessionId: ctx.sessionId, part: toolPart });
+      await createPart(toolPart, ctx.sessionId, { syncFts: false });
+
+      resetTextState();
+      resetReasoningState();
+    },
+
+    async handleToolResult(delta: { toolCallId: string; output: unknown }): Promise<void> {
+      const existingToolPart = ctx.toolParts.find((tp) => tp.callId === delta.toolCallId);
+
+      if (existingToolPart) {
+        const latestPart = await getPart(existingToolPart.id) as ToolPart | null;
+        const latestState = latestPart?.state;
+
+        let resultData: unknown;
+        if (typeof delta.output === 'string') {
+          try {
+            resultData = JSON.parse(delta.output);
+          } catch {
+            resultData = delta.output;
+          }
+        } else if (delta.output && typeof delta.output === 'object' && 'value' in delta.output) {
+          resultData = (delta.output as { value: unknown }).value;
+        } else {
+          resultData = delta.output;
+        }
+
+        const isErrorResult = !!(resultData && typeof resultData === 'object' && 'error' in resultData);
+
+        const existingChildSessionId = latestState && 'childSessionId' in latestState
+          ? latestState.childSessionId
+          : undefined;
+
+        const updatedToolPart: ToolPart = {
+          ...existingToolPart,
+          state: isErrorResult
+            ? {
+                status: 'error' as const,
+                input: existingToolPart.state.input,
+                error: String((resultData as { error: unknown }).error),
+                startedAt: Date.now(),
+                failedAt: Date.now(),
+                ...(existingChildSessionId && { childSessionId: existingChildSessionId }),
+              }
+            : {
+                status: 'completed' as const,
+                input: existingToolPart.state.input,
+                output: resultData,
+                startedAt: Date.now(),
+                completedAt: Date.now(),
+                ...(existingChildSessionId && { childSessionId: existingChildSessionId }),
+              },
+        };
+
+        const index = ctx.toolParts.indexOf(existingToolPart);
+        if (index !== -1) {
+          ctx.toolParts[index] = updatedToolPart;
+        }
+
+        ctx.yieldFn({ type: 'part.updated', sessionId: ctx.sessionId, part: updatedToolPart });
+        await updatePart(updatedToolPart.id, { state: updatedToolPart.state }, { syncFts: false });
+      }
+    },
+
+    async flushPending(): Promise<void> {
+      await persistText(true);
+      await persistReasoning(true);
+    },
+  };
+}

package/src/core/structured-output.ts

@@ -0,0 +1,68 @@
+import type { ResponseFormat } from '@capekai/types';
+
+/**
+ * Builds a system-prompt instruction that tells the model to respond with JSON
+ * conforming to the given schema. Used for providers that strip the schema
+ * from `response_format` (e.g. GLM/Zhipu, MiniMax) — they only send
+ * `{ type: "json_object" }` to the API, so the model needs the schema inline.
+ */
+export function buildSchemaPromptInstruction(responseFormat: ResponseFormat): string {
+  const schemaStr = JSON.stringify(responseFormat.schema, null, 2);
+  return [
+    `You must respond with ONLY valid JSON that conforms to the following JSON Schema.`,
+    `Do not include any text before or after the JSON object. Do not wrap it in markdown code fences.`,
+    `Response format name: ${responseFormat.name}`,
+    ...(responseFormat.description ? [`Description: ${responseFormat.description}`] : []),
+    '',
+    'JSON Schema:',
+    schemaStr,
+  ].join('\n');
+}
+
+/**
+ * Attempts to extract a JSON object from the raw text output of a model.
+ * Handles common LLM quirks:
+ * - Leading/trailing whitespace
+ * - Markdown code fences (```json ... ```)
+ * - Preamble text before the JSON (finds first `{` and last `}`)
+ */
+export function extractJsonFromText(text: string): Record<string, unknown> | null {
+  if (!text || !text.trim()) {
+    return null;
+  }
+
+  let cleaned = text.trim();
+
+  // Strip markdown code fences if present
+  const fenceMatch = cleaned.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+  if (fenceMatch) {
+    cleaned = fenceMatch[1].trim();
+  }
+
+  // If the whole thing is valid JSON, use it directly
+  try {
+    const parsed = JSON.parse(cleaned);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    // Fall through to brace-matching
+  }
+
+  // Find the outermost JSON object via first `{` and last `}`
+  const firstBrace = cleaned.indexOf('{');
+  const lastBrace = cleaned.lastIndexOf('}');
+  if (firstBrace !== -1 && lastBrace !== -1 && lastBrace > firstBrace) {
+    const jsonStr = cleaned.slice(firstBrace, lastBrace + 1);
+    try {
+      const parsed = JSON.parse(jsonStr);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>;
+      }
+    } catch {
+      // Not valid JSON
+    }
+  }
+
+  return null;
+}

package/src/core/tool-builders/agent-tools.ts

@@ -0,0 +1,71 @@
+import { tool, jsonSchema } from 'ai';
+import {
+  getContributedDomainToolPayloads,
+  getDomainToolFallback,
+  mergeDomainToolVisualization,
+  type DomainToolPayload,
+} from '../../runtime/domain-tool-source';
+import type { ToolMap } from './types';
+
+/**
+ * C5 memory and skills domain tools (agent phase). The pre-C5 builder
+ * imported the memory and skills implementations directly; it now consumes
+ * the agent-scoped domain payloads through the generic
+ * contributed-domain-tool seam (`agent_memory`, `agent_skill_manage`), with
+ * the explicitly installed fallbacks covering the unscoped path. The agent
+ * directory gate stays here: agent tools build only when an agent directory
+ * exists for the session preconfig.
+ */
+export interface AgentToolsOptions {
+  agentDir: string;
+}
+
+export async function buildAgentTools(options: AgentToolsOptions): Promise<ToolMap> {
+  const { agentDir } = options;
+  const tools: ToolMap = {};
+
+  const scopedDomainPayloads = getContributedDomainToolPayloads();
+  const domainPayload = (name: string): DomainToolPayload | null =>
+    scopedDomainPayloads === null
+      ? getDomainToolFallback(name)
+      : scopedDomainPayloads.get(name) ?? null;
+
+  const agentMemoryPayload = domainPayload('agent_memory');
+  if (agentMemoryPayload) {
+    tools['agent_memory'] = tool({
+      description: agentMemoryPayload.description,
+      inputSchema: jsonSchema(agentMemoryPayload.inputSchema),
+      execute: async (args: Record<string, unknown>) =>
+        agentMemoryPayload.execute(args, {
+          workspaceId: '',
+          sessionId: '',
+          ask: async () => {
+            throw new Error('Cannot ask user: no broadcast channel available');
+          },
+          agentDir,
+        }).then((result) => mergeDomainToolVisualization(agentMemoryPayload, args, result)),
+    });
+  }
+
+  const agentSkillManagePayload = domainPayload('agent_skill_manage');
+  const agentSkillManageDefinition = await agentSkillManagePayload?.resolveDefinition?.('', {
+    agentDir,
+  });
+  if (agentSkillManagePayload && agentSkillManageDefinition) {
+    tools['agent_skill_manage'] = tool({
+      description: agentSkillManageDefinition.description,
+      inputSchema: jsonSchema(agentSkillManageDefinition.inputSchema),
+      execute: async (args: Record<string, unknown>) =>
+        agentSkillManagePayload.execute(args, {
+          workspaceId: '',
+          sessionId: '',
+          ask: async () => {
+            throw new Error('Cannot ask user: no broadcast channel available');
+          },
+          agentDir,
+        }).then((result) => mergeDomainToolVisualization(agentSkillManagePayload, args, result)),
+    });
+  }
+
+  return tools;
+}

package/src/core/tool-builders/external-tools.ts

@@ -0,0 +1,179 @@
+import { tool, jsonSchema } from 'ai';
+import { getTool } from '../../tools/registry';
+import { executeTool } from '../../tools/executor';
+import { createLlmApi } from '../../tools/llm-api';
+import { createWorkspaceCapability } from '../../workspace/policy';
+import {
+  createAskApi,
+  rejectPendingAsksByToolCallId,
+  type AskBroadcastFn,
+} from '../../permission/ask-user-api';
+import { getToolWorkspaceHost } from '../../runtime/host-dependencies';
+import { transitionToolToRunningByCallId } from '../../storage/runtime';
+import { interruptManager } from '../interrupt';
+import {
+  getContributedDomainToolPayloads,
+  getDomainToolFallback,
+  mergeDomainToolVisualization,
+  type DomainToolPayload,
+} from '../../runtime/domain-tool-source';
+import { isToolAllowedInContext, type ToolExecutionScope } from '../tool-capabilities';
+import type { ToolMap } from './types';
+import type { BroadcastFn } from '../../runtime/host-dependencies';
+
+export interface ExternalToolsOptions {
+  toolNames: string[];
+  canSpawnSubagents?: boolean | string[] | null;
+  allowSelfAsSubagent?: boolean;
+  broadcastFn?: AskBroadcastFn;
+  broadcast: BroadcastFn;
+  sessionId: string;
+  workspaceId: string | undefined;
+  workspacePath: string | undefined;
+  rootSessionId: string;
+  executionScopes: ReadonlySet<ToolExecutionScope>;
+  modelId?: string;
+  providerId?: string;
+  additionalPaths?: string[];
+}
+
+export async function buildExternalTools(options: ExternalToolsOptions): Promise<ToolMap> {
+  const {
+    toolNames,
+    canSpawnSubagents,
+    allowSelfAsSubagent,
+    broadcastFn,
+    broadcast,
+    sessionId,
+    workspaceId,
+    workspacePath,
+    rootSessionId,
+    executionScopes,
+    modelId,
+    providerId,
+    additionalPaths,
+  } = options;
+
+  const tools: ToolMap = {};
+
+  const canSpawn = canSpawnSubagents === true
+    || (Array.isArray(canSpawnSubagents) && canSpawnSubagents.length > 0);
+  const allowedSubagentIds = Array.isArray(canSpawnSubagents) ? canSpawnSubagents : undefined;
+
+  // The task tool is owned by the C5 subagent domain plugin. Composed scopes
+  // provide its payload through the generic contributed-domain-tool seam;
+  // the unscoped path uses the explicitly installed legacy fallback. The
+  // domain owns the depth gate (isEnabled); the preconfig spawn policy and
+  // the 'task'-name guard stay here because they arrive per build.
+  const scopedDomainPayloads = getContributedDomainToolPayloads();
+  const taskPayload: DomainToolPayload | null = scopedDomainPayloads === null
+    ? getDomainToolFallback('task')
+    : scopedDomainPayloads.get('task') ?? null;
+  const shouldIncludeTask = taskPayload !== null
+    && !toolNames.includes('task')
+    && canSpawn
+    && await taskPayload.isEnabled?.(workspaceId ?? '', sessionId) === true;
+
+  // Phase 1a: registry tools in toolNames order, exactly as pre-C5.
+  for (const name of toolNames) {
+    const loadedTool = await getTool(name);
+    if (!loadedTool) continue;
+
+    const { definition } = loadedTool;
+
+    if (!isToolAllowedInContext(definition.capabilities, executionScopes)) {
+      continue;
+    }
+
+    tools[name] = tool({
+      description: definition.description,
+      inputSchema: jsonSchema(definition.inputSchema),
+      execute: async (args: Record<string, unknown>, { toolCallId }: { toolCallId: string }) => {
+        const toolAbortController = interruptManager.registerToolExecution(sessionId, toolCallId);
+
+        try {
+          const llmFactory = () => createLlmApi(modelId, providerId, sessionId);
+          const askFactory = (tcId: string) =>
+            broadcastFn
+              ? createAskApi(sessionId, tcId, definition.name, broadcastFn, workspaceId, rootSessionId)
+              : (() => { throw new Error('Cannot ask user: no broadcast channel available (broadcastFn not provided)'); }) as import('@capekai/tool').AskApi;
+
+          const workspace = createWorkspaceCapability(getToolWorkspaceHost({
+            workspaceId,
+            workspacePath,
+            additionalPaths,
+            sessionId,
+          }));
+          const result = await executeTool({
+            tool: loadedTool,
+            args,
+            workspace,
+            sessionId,
+            workspaceId,
+            toolCallId,
+            abortSignal: toolAbortController.signal,
+            timeout: definition.timeout,
+            createLlmApi: llmFactory,
+            createAskApi: askFactory,
+          });
+
+          if (!result.success) {
+            return { error: result.error ?? 'Tool execution failed' };
+          }
+
+          if (result.visualization && result.result && typeof result.result === 'object') {
+            return { ...result.result as Record<string, unknown>, _visualization: result.visualization };
+          }
+
+          return result.result;
+        } finally {
+          interruptManager.unregisterToolExecution(sessionId, toolCallId);
+          await rejectPendingAsksByToolCallId(toolCallId);
+        }
+      },
+    });
+  }
+
+  // Phase 1b: the task tool after the registry tools, preserving the exact
+  // pre-C5 build order. The dynamic description and schema come from the
+  // payload's per-build resolver (composed deps or the legacy fallback).
+  if (shouldIncludeTask && taskPayload) {
+    const taskDefinition = await taskPayload.resolveDefinition?.(sessionId, {
+      canSpawnSubagents,
+      allowSelfAsSubagent,
+    });
+    if (taskDefinition) {
+      tools['task'] = tool({
+        description: taskDefinition.description,
+        inputSchema: jsonSchema(taskDefinition.inputSchema),
+        execute: async (args: Record<string, unknown>, { toolCallId }: { toolCallId: string }) => {
+          const toolAbortController = interruptManager.registerToolExecution(sessionId, toolCallId);
+
+          try {
+            return await taskPayload.execute(args, {
+              workspaceId: workspaceId ?? '',
+              sessionId,
+              ask: async () => {
+                throw new Error('Cannot ask user: no broadcast channel available (broadcastFn not provided)');
+              },
+              workspacePath,
+              abortSignal: toolAbortController.signal,
+              onSessionCreated: async (childSessionId: string) => {
+                const updatedPart = await transitionToolToRunningByCallId(sessionId, toolCallId, childSessionId);
+                if (updatedPart) {
+                  broadcast({ kind: 'part', action: 'updated', sessionId, part: updatedPart });
+                }
+              },
+              allowedSubagentIds,
+              broadcast,
+            }).then((result) => mergeDomainToolVisualization(taskPayload, args, result));
+          } finally {
+            interruptManager.unregisterToolExecution(sessionId, toolCallId);
+          }
+        },
+      });
+    }
+  }
+
+  return tools;
+}

package/src/core/tool-builders/types.ts

@@ -0,0 +1,16 @@
+import type { Tool } from 'ai';
+import type { AskBroadcastFn } from '../../permission/ask-user-api';
+
+export interface ToolBuildContext {
+  sessionId: string;
+  workspaceId: string | undefined;
+  workspacePath: string | undefined;
+  rootSessionId: string;
+  modelId?: string;
+  providerId?: string;
+  broadcastFn?: AskBroadcastFn;
+  additionalPaths?: string[];
+  agentId?: string | null;
+}
+
+export type ToolMap = Record<string, Tool>;