@flowcodex/core 0.3.0

package/src/execution/tool-executor.ts

@@ -0,0 +1,276 @@
+import type { ToolContext } from '../types/tool.js';
+import type { Tool } from '../types/tool.js';
+import type { Context } from '../types/context.js';
+import type { ToolUse, ToolResult } from '../types/context.js';
+import type { ToolRegistry } from './tool-registry.js';
+import type { ConfirmAwaiter, PermissionPolicy } from '../security/permission-policy.js';
+import { createToolOutputSerializer } from './output-serializer.js';
+import type { OutputSerializer } from './output-serializer.js';
+import { validateAgainstSchema } from './schema-validator.js';
+import { toErrorMessage } from '../utils/error.js';
+import { DefaultSecretScrubber } from '../infrastructure/secret-scrubber.js';
+
+export type ToolExecutorStrategy = 'parallel' | 'sequential' | 'smart';
+
+export interface ToolExecutorOptions {
+  perIterationOutputCapBytes?: number | undefined;
+  maxToolTimeoutMs?: number | undefined;
+  policy?: PermissionPolicy | undefined;
+  confirmAwaiter?: ConfirmAwaiter | undefined;
+  toolStreaming?: boolean | undefined;
+}
+
+export interface ToolBatchResult {
+  results: ToolResult[];
+  remainingBudget: number;
+}
+
+const DEFAULT_MAX_TIMEOUT = 300_000;
+const DEFAULT_CAP = 100_000;
+
+export class ToolExecutor {
+  private serializer: OutputSerializer;
+  private scrubber = new DefaultSecretScrubber();
+  private maxToolTimeoutMs: number;
+  private cap: number;
+  private policy?: PermissionPolicy | undefined;
+  private confirmAwaiter?: ConfirmAwaiter | undefined;
+  private toolStreamingEnabled: boolean;
+
+  constructor(
+    private registry: ToolRegistry,
+    opts: ToolExecutorOptions = {},
+  ) {
+    this.cap = opts.perIterationOutputCapBytes ?? DEFAULT_CAP;
+    this.serializer = createToolOutputSerializer({ perIterationOutputCapBytes: this.cap });
+    this.maxToolTimeoutMs = opts.maxToolTimeoutMs ?? DEFAULT_MAX_TIMEOUT;
+    this.policy = opts.policy;
+    this.confirmAwaiter = opts.confirmAwaiter;
+    this.toolStreamingEnabled = opts.toolStreaming ?? false;
+  }
+
+  async executeBatch(
+    toolUses: readonly ToolUse[],
+    ctx: Context,
+    strategy: ToolExecutorStrategy = 'smart',
+  ): Promise<ToolBatchResult> {
+    const budget = { remaining: this.cap };
+    const indexed = toolUses.map((use, i) => ({ use, i }));
+
+    const runOne = (use: ToolUse): Promise<ToolResult> => this.executeTool(use, ctx, budget);
+
+    if (strategy === 'sequential') {
+      const out: Array<{ i: number; r: ToolResult }> = [];
+      for (const { use, i } of indexed) {
+        out.push({ i, r: await runOne(use) });
+      }
+      out.sort((a, b) => a.i - b.i);
+      return { results: out.map((o) => o.r), remainingBudget: budget.remaining };
+    }
+
+    if (strategy === 'parallel') {
+      const proms = indexed.map(async ({ use, i }) => ({ i, r: await runOne(use) }));
+      const out = await Promise.all(proms);
+      out.sort((a, b) => a.i - b.i);
+      return { results: out.map((o) => o.r), remainingBudget: budget.remaining };
+    }
+
+    const ro: Array<{ use: ToolUse; i: number }> = [];
+    const mut: Array<{ use: ToolUse; i: number }> = [];
+    for (const item of indexed) {
+      const tool = this.registry.get(item.use.name);
+      if (tool && !tool.mutating) {
+        ro.push(item);
+      } else {
+        mut.push(item);
+      }
+    }
+
+    const roResults = await Promise.all(ro.map(async ({ use, i }) => ({ i, r: await runOne(use) })));
+    const mutResults: Array<{ i: number; r: ToolResult }> = [];
+    for (const { use, i } of mut) {
+      mutResults.push({ i, r: await runOne(use) });
+    }
+
+    const all = [...roResults, ...mutResults];
+    all.sort((a, b) => a.i - b.i);
+    return { results: all.map((o) => o.r), remainingBudget: budget.remaining };
+  }
+
+  private async executeTool(
+    use: ToolUse,
+    ctx: Context,
+    budget: { remaining: number },
+  ): Promise<ToolResult> {
+    const tool = this.registry.get(use.name);
+
+    if (!tool) {
+      const available = this.registry.list().map((t) => t.name).join(', ');
+      return this.makeErrorResult(use.id, use.name, `Tool "${use.name}" is not registered. Available tools: ${available}`, budget);
+    }
+
+    const validation = validateAgainstSchema(use.input, tool.inputSchema);
+    if (!validation.ok) {
+      const errorDetails = validation.errors
+        .map((e) => `  - ${e.path}: ${e.message}`)
+        .join('\n');
+      return this.makeErrorResult(
+        use.id,
+        tool.name,
+        `Invalid arguments for tool "${tool.name}".\n\nValidation errors:\n${errorDetails}`,
+        budget,
+      );
+    }
+
+    if (this.policy) {
+      const toolCtxForPolicy: ToolContext = {
+        projectRoot: ctx.projectRoot,
+        workingDir: ctx.workingDir,
+        signal: ctx.signal,
+        registerAbortHook: (fn) => ctx.registerAbortHook(fn),
+        recordRead: (p, m) => ctx.recordRead(p, m),
+        hasRead: (p) => ctx.hasRead(p),
+        lastReadMtime: (p) => ctx.readFiles.get(p),
+      };
+      const decision = await this.policy.evaluate(tool, use.input, toolCtxForPolicy);
+      if (decision.permission === 'deny') {
+        return this.makeErrorResult(use.id, tool.name, `Tool "${tool.name}" denied: ${decision.reason ?? 'denied by policy'}`, budget);
+      }
+      if (decision.permission === 'confirm') {
+        const reply = await this.confirmAwaiter?.(tool, use.input, use.id, suggestPattern(tool, use.input));
+        if (!this.confirmAwaiter) {
+          return this.makeErrorResult(use.id, tool.name, `Tool "${tool.name}" requires confirmation (non-interactive mode).`, budget);
+        }
+        if (reply === 'no') {
+          return this.makeErrorResult(use.id, tool.name, `Tool "${tool.name}" denied by user.`, budget);
+        }
+        if (reply === 'deny') {
+          return this.makeErrorResult(use.id, tool.name, `Tool "${tool.name}" denied.`, budget);
+        }
+        // 'yes' | 'always' → proceed; persistence handled by the awaiter via policy.
+      }
+    }
+
+    const toolCtx: ToolContext = {
+      projectRoot: ctx.projectRoot,
+      workingDir: ctx.workingDir,
+      signal: ctx.signal,
+      registerAbortHook: (fn) => ctx.registerAbortHook(fn),
+      recordRead: (p, m) => ctx.recordRead(p, m),
+      hasRead: (p) => ctx.hasRead(p),
+      lastReadMtime: (p) => ctx.readFiles.get(p),
+    };
+
+    const timeoutMs = Math.min(tool.timeoutMs ?? this.maxToolTimeoutMs, this.maxToolTimeoutMs);
+    const innerController = new AbortController();
+    const timer = setTimeout(() => innerController.abort(new Error('Tool timeout')), timeoutMs);
+
+    const onParentAbort = (): void => innerController.abort(ctx.signal.reason);
+    if (ctx.signal.aborted) {
+      innerController.abort(ctx.signal.reason);
+    } else {
+      ctx.signal.addEventListener('abort', onParentAbort, { once: true });
+    }
+
+    try {
+      let output: unknown;
+      if (this.toolStreamingEnabled && typeof tool.executeStream === 'function') {
+        output = await this.runStreamedTool(tool, use.input, toolCtx, innerController.signal, use.id);
+      } else {
+        output = await tool.execute(use.input, toolCtx, { signal: innerController.signal });
+      }
+      const serialized = this.serializer.serialize(output);
+      const { text, newBudget } = this.serializer.enforceCap(serialized, budget.remaining);
+      budget.remaining = newBudget;
+      const scrubbed = this.scrubber.scrub(text);
+      return { toolUseId: use.id, block: { type: 'tool_result', tool_use_id: use.id, content: scrubbed } };
+    } catch (err) {
+      if (ctx.signal.aborted) {
+        return this.makeErrorResult(use.id, tool.name, `Tool "${tool.name}" was aborted.`, budget);
+      }
+
+      const isTimeout = innerController.signal.aborted && !ctx.signal.aborted;
+      const rawMsg = isTimeout
+        ? `timed out after ${timeoutMs}ms`
+        : toErrorMessage(err);
+      const scrubbedMsg = this.scrubber.scrub(rawMsg);
+      return this.makeErrorResult(use.id, tool.name, `Tool "${tool.name}" threw: ${scrubbedMsg}`, budget);
+    } finally {
+      if (tool.cleanup) {
+        try {
+          await tool.cleanup(use.input, toolCtx);
+        } catch {
+          // best-effort: cleanup errors never mask the real result
+        }
+      }
+      clearTimeout(timer);
+      ctx.signal.removeEventListener('abort', onParentAbort);
+    }
+  }
+
+  private async runStreamedTool<I>(
+    tool: Tool<I, unknown>,
+    input: I,
+    toolCtx: ToolContext,
+    signal: AbortSignal,
+    _toolUseId: string,
+  ): Promise<unknown> {
+    const iter = tool.executeStream!(input, toolCtx, { signal });
+    let finalOutput: unknown | undefined;
+
+    try {
+      for await (const ev of iter) {
+        if (ev.type === 'final') {
+          finalOutput = ev.output;
+          continue;
+        }
+        // partial_output and other events are accumulated for the final result;
+        // live progress emission via EventBus is deferred to v0.4 TUI.
+      }
+      if (finalOutput === undefined) {
+        throw new Error(`tool "${tool.name}" executeStream completed without a 'final' event`);
+      }
+      return finalOutput;
+    } finally {
+      // best-effort: close the async iterator so the tool's own cleanup runs.
+      // AsyncIterable doesn't expose .return() in the type, but AsyncGenerator
+      // implementations do — the cast is safe for our use (bash.executeStream).
+      try {
+        await (iter as { return?: () => Promise<{ done: boolean; value: unknown }> }).return?.();
+      } catch {
+        // swallow
+      }
+    }
+  }
+
+  private makeErrorResult(
+    toolUseId: string,
+    _toolName: string,
+    message: string,
+    budget: { remaining: number },
+  ): ToolResult {
+    const { text, newBudget } = this.serializer.enforceCap(message, budget.remaining);
+    budget.remaining = newBudget;
+    return {
+      toolUseId,
+      block: { type: 'tool_result', tool_use_id: toolUseId, content: text, is_error: true },
+    };
+  }
+}
+
+export function suggestPattern(tool: Tool, input: unknown): string {
+  const subjectKey = tool.subjectKey;
+  if (!subjectKey) return '*';
+  const v = (input as Record<string, unknown> | null)?.[subjectKey];
+  if (typeof v !== 'string' || v === '') return '*';
+  if (tool.name === 'bash') {
+    const firstToken = v.trim().split(/\s+/)[0];
+    return firstToken ? `${firstToken} *` : '*';
+  }
+  if (subjectKey === 'path') {
+    const sep = v.lastIndexOf('/');
+    const dir = sep > 0 ? v.slice(0, sep) : '';
+    return dir ? `${dir}/**` : '*';
+  }
+  return '*';
+}

package/src/execution/tool-registry.ts

@@ -0,0 +1,104 @@
+import type { Tool } from '../types/tool.js';
+
+export interface RegistryEntry {
+  tool: Tool;
+  owner: string;
+  estDefTokens: number;
+}
+
+export class ToolRegistry {
+  private tools = new Map<string, RegistryEntry>();
+
+  register(tool: Tool, owner: string): void {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool "${tool.name}" is already registered`);
+    }
+    this.tools.set(tool.name, {
+      tool,
+      owner,
+      estDefTokens: Math.ceil(JSON.stringify(tool.inputSchema).length / 3.5),
+    });
+  }
+
+  tryRegister(tool: Tool, owner: string): boolean {
+    if (this.tools.has(tool.name)) return false;
+    this.register(tool, owner);
+    return true;
+  }
+
+  registerAll(tools: readonly Tool[], owner: string): void {
+    for (const tool of tools) {
+      this.tryRegister(tool, owner);
+    }
+  }
+
+  registerDefault(tool: Tool, owner: string): void {
+    if (this.tools.has(tool.name)) return;
+    this.register(tool, owner);
+  }
+
+  override(name: string, tool: Tool, owner: string): void {
+    const existing = this.tools.get(name);
+    if (!existing) {
+      throw new Error(`Tool "${name}" is not registered; cannot override`);
+    }
+    if (tool.name !== name) {
+      throw new Error(`Override tool name "${tool.name}" does not match registry key "${name}"`);
+    }
+    this.tools.set(name, {
+      tool,
+      owner,
+      estDefTokens: Math.ceil(JSON.stringify(tool.inputSchema).length / 3.5),
+    });
+  }
+
+  get(name: string): Tool | undefined {
+    return this.tools.get(name)?.tool;
+  }
+
+  list(): Tool[] {
+    return [...this.tools.values()].map((e) => e.tool);
+  }
+
+  listWithOwner(): Array<{ tool: Tool; owner: string }> {
+    return [...this.tools.values()].map((e) => ({ tool: e.tool, owner: e.owner }));
+  }
+
+  ownerOf(name: string): string | undefined {
+    return this.tools.get(name)?.owner;
+  }
+
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  get totalEstDefTokens(): number {
+    let total = 0;
+    for (const entry of this.tools.values()) {
+      total += entry.estDefTokens;
+    }
+    return total;
+  }
+
+  filter(predicate: (tool: Tool) => boolean): { total: number; kept: number } {
+    const total = this.tools.size;
+    for (const [name, entry] of [...this.tools]) {
+      if (!predicate(entry.tool)) {
+        this.tools.delete(name);
+      }
+    }
+    return { total, kept: this.tools.size };
+  }
+
+  clone(): ToolRegistry {
+    const copy = new ToolRegistry();
+    for (const [name, entry] of this.tools) {
+      copy.tools.set(name, { ...entry });
+    }
+    return copy;
+  }
+
+  get size(): number {
+    return this.tools.size;
+  }
+}

package/src/index.ts

@@ -0,0 +1,215 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const pkgPath = fileURLToPath(new URL('../../../package.json', import.meta.url));
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version: string; name: string };
+
+export const FLOWCODEX_VERSION = pkg.version;
+export const FLOWCODEX_NAME = 'flowcodex' as const;
+
+export { toErrorMessage } from './utils/error.js';
+export {
+  atomicWrite,
+  isBinaryBuffer,
+  detectNewlineStyle,
+  normalizeToLf,
+  toStyle,
+  compileGlob,
+  unifiedDiff,
+  stripAnsi,
+} from './utils/fs.js';
+export type { NewlineStyle, DiffOptions } from './utils/fs.js';
+export {
+  FlowCodexError,
+  ToolError,
+  ConfigError,
+  PluginError,
+  AgentError,
+  PermissionError,
+  SessionError,
+  FsError,
+  toFlowCodexError,
+  isFlowCodexError,
+  isToolError,
+  isConfigError,
+  isPluginError,
+  isSessionError,
+  isAgentError,
+  isPermissionError,
+  isFsError,
+  ERROR_CODES,
+} from './types/errors.js';
+export type { ErrorCode, ErrorSubsystem, ErrorSeverity } from './types/errors.js';
+
+export { Container, token, Pipeline, RunController, TOKENS, EventBus, ScopedEventBus } from './kernel/index.js';
+export type {
+  Token,
+  Factory,
+  Decorator,
+  BindOptions,
+  NextFn,
+  MiddlewareHandler,
+  Middleware,
+  ReadonlyPipeline,
+  PipelineErrorHandler,
+  PipelineErrorEvent,
+  PipelineErrorPolicy,
+  PipelineOptions,
+  RunControllerOptions,
+  EventMap,
+  EventName,
+  Listener,
+  EventLogger,
+} from './kernel/index.js';
+
+export {
+  DefaultPathResolver,
+  safeResolve,
+  safeResolveReal,
+  DefaultRetryPolicy,
+  parseRetryAfter,
+  NoopTracer,
+  NoopSpan,
+  DefaultTokenCounter,
+  DefaultSecretScrubber,
+  DefaultCatalogParser,
+  classifyFamily,
+  createProvider,
+  setProviderConstructors,
+  resolveFamily,
+} from './infrastructure/index.js';
+export type {
+  PathResolver,
+  RetryPolicy,
+  ProviderError as InfraProviderError,
+  Tracer,
+  Span,
+  TokenCounter,
+  Usage,
+  ModelPricing,
+  SecretScrubber,
+  CatalogParser,
+  CatalogEntry,
+  ModelInfo,
+  WireFamily as CatalogWireFamily,
+  ProviderConstructors,
+  ProviderConfigEntry,
+  CreateProviderOptions,
+  FlowCodexLikeConfig,
+} from './infrastructure/index.js';
+export { AgentContext } from './agent/context.js';
+
+export type { ContextInit } from './agent/context.js';
+export { DefaultConversationState } from './agent/conversation-state.js';
+export type { ConversationState } from './agent/conversation-state.js';
+export { DefaultSystemPromptBuilder, IDENTITY_PROMPT } from './agent/system-prompt-builder.js';
+export type { SystemPromptBuilder, SystemPromptBuildContext } from './agent/system-prompt-builder.js';
+export { HybridCompactor, MODE_CONFIGS, ACTIVE_MODE, FLOOR_PRESERVE_K, NOOP_RETRY_DELTA_TOKENS, repairToolUseAdjacency } from './execution/compactor.js';
+export type { CompactionMode, ModeConfig, CompactionInput, CompactionResult, Compactor, RepairResult } from './execution/compactor.js';
+export type { TextBlock, CacheControl } from './types/blocks.js';
+export { runProviderWithRetry } from './agent/provider-runner.js';
+export type { RunProviderOptions, FallbackEntry } from './agent/provider-runner.js';
+export { runAgentLoop } from './agent/agent-loop.js';
+export type { AgentLoopOptions } from './agent/agent-loop.js';
+
+export {
+  ToolRegistry,
+  createToolOutputSerializer,
+  validateAgainstSchema,
+  ToolExecutor,
+} from './execution/index.js';
+export type {
+  OutputSerializer,
+  SerializerOptions,
+  CapResult,
+  SchemaValidationResult,
+  SchemaValidationError,
+  ToolExecutorStrategy,
+  ToolExecutorOptions,
+  ToolBatchResult,
+} from './execution/index.js';
+
+export { ulid, ulidTime, isUlid } from './utils/ulid.js';
+
+export { isPrivateIp, safeFetch } from './utils/ssrf-guard.js';
+export type { SafeFetchOptions } from './utils/ssrf-guard.js';
+
+export { PROVIDER_PRESETS } from './infrastructure/provider-presets.js';
+export type { CompatibilityQuirks } from './infrastructure/provider-presets.js';
+
+export { DefaultPermissionPolicy, matchGlob } from './security/permission-policy.js';
+export type {
+  PermissionSource,
+  PermissionDecision,
+  TrustRule,
+  TrustFile,
+  PermissionPolicy,
+  ConfirmAwaiter,
+  DefaultPermissionPolicyOptions,
+} from './security/permission-policy.js';
+
+
+export {
+  DefaultSecretVault,
+  ENCRYPTED_PREFIX,
+  restrictFilePermissions,
+  isSecretField,
+  DefaultSessionStore,
+  generateSessionId,
+  projectHash,
+  flowcodexHome,
+  sessionsDir,
+  recordsDir,
+  reconstructMessages,
+  keyFilePath,
+  configFilePath,
+  authFilePath,
+  DefaultAuditLog,
+  stableStringify,
+  DefaultAuthService,
+} from './session/index.js';
+export type {
+  SessionEvent,
+  SessionSummary,
+  AuditEntry,
+  VerifyResult,
+  SessionStore,
+  SecretVault,
+  AuditLog,
+  SecretVaultOptions,
+  SessionStoreOptions,
+  AuditLogOptions,
+  ApiKeyEntry,
+  AuthEntry,
+  AuthProviderStatus,
+  AuthService,
+  AuthServiceOptions,
+} from './session/index.js';
+
+export { fetchLatestVersion, compareVersions, checkForUpdate, type VersionInfo } from './utils/version-check.js';
+
+export { resizeImageBuffer, type ResizeOptions, type ResizeResult } from './utils/image-resize.js';
+
+export type {
+  ContentBlock,
+  Role,
+  Message,
+  ModelId,
+  ModelRef,
+  ToolUse,
+  ToolResult,
+  Budget,
+  AgentStatus,
+  RunResult,
+  Context,
+  Usage as ProviderUsage,
+  LLMRequest,
+  LLMResponse,
+  LLMEvent,
+  Provider,
+  Tool,
+  ToolStreamEvent,
+  Permission,
+  RiskTier,
+  ToolContext,
+} from './types/index.js';