@capekai/core 1.0.0

package/src/workflow/synthesizer.ts

@@ -0,0 +1,130 @@
+import type { BroadcastFn, BroadcastSessionFn } from '../runtime/host';
+import {
+  runOrchestratorSession,
+  type OrchestratorSessionOptions,
+  type OrchestratorSessionResult,
+} from './orchestrator-session';
+
+/** Workflow domain: leaf result synthesis. Moved byte-for-byte from
+ * `core/workflow-synthesizer.ts`; the unscoped export keeps the pre-C5
+ * module-accessor behavior, and the WithDeps variant runs against the
+ * injected orchestrator contract captured by the domain plugin. */
+
+/** Result from a single leaf agent execution. */
+export interface LeafResult {
+  index: number;
+  text: string;
+  structuredResult?: Record<string, unknown>;
+  error?: string;
+}
+
+/** Result from the synthesis phase. */
+export interface SynthesisResult {
+  text: string;
+  structuredResult?: Record<string, unknown>;
+}
+
+export interface SynthesizeResultsOptions {
+  originalPrompt: string;
+  leafResults: LeafResult[];
+  outputSchema?: Record<string, unknown>;
+  parentSessionId: string;
+  abortSignal?: AbortSignal;
+  broadcast?: BroadcastFn;
+  broadcastSessionCreated?: BroadcastSessionFn;
+  broadcastSessionUpdated?: BroadcastSessionFn;
+  runOrchestrator?: typeof runOrchestratorSession;
+}
+
+export interface SynthesizeResultsDeps {
+  orchestrator: { run(options: OrchestratorSessionOptions): Promise<OrchestratorSessionResult> };
+}
+
+/** Unscoped synthesis over the module orchestrator implementation. */
+export async function synthesizeResults(options: SynthesizeResultsOptions): Promise<SynthesisResult> {
+  return synthesizeResultsWithDeps(options, { orchestrator: { run: runOrchestratorSession } });
+}
+
+/** Composed synthesis over the injected orchestrator contract. */
+export async function synthesizeResultsWithDeps(
+  options: SynthesizeResultsOptions,
+  deps: SynthesizeResultsDeps,
+): Promise<SynthesisResult> {
+  console.log('[workflow:synthesize] Starting synthesis', {
+    parentSessionId: options.parentSessionId,
+    leafResultCount: options.leafResults.length,
+    hasOutputSchema: !!options.outputSchema,
+  });
+
+  const formattedResults = options.leafResults
+    .map((r) => {
+      const status = r.error ? '[FAILED]' : '[success]';
+      const parts: string[] = [`Sub-agent ${r.index + 1} ${status}:`];
+      if (r.error) {
+        parts.push(`  Error: ${r.error}`);
+      } else {
+        parts.push(`  Text: ${r.text || '(no text output)'}`);
+        if (r.structuredResult) {
+          parts.push(`  Structured: ${JSON.stringify(r.structuredResult)}`);
+        }
+      }
+      return parts.join('\n');
+    })
+    .join('\n\n');
+
+  let system = [
+    'You are a synthesis agent. You have been given the results of several parallel',
+    'sub-agents that were each working on part of a larger task.',
+    '',
+    'Your job:',
+    '1. Review all sub-agent results below.',
+    '2. Identify overlapping findings, contradictions, and gaps.',
+    '3. Produce a single consolidated answer that addresses the original task.',
+    '',
+    `Original task: ${options.originalPrompt}`,
+    '',
+    'Sub-agent results:',
+    formattedResults,
+  ].join('\n');
+
+  let userPrompt = 'Synthesize the sub-agent results into a final answer.';
+
+  // If structured output is requested, inject the schema into the prompt
+  // (same approach as agent.ts prompt-based structured output — works universally)
+  if (options.outputSchema) {
+    const schemaStr = JSON.stringify(options.outputSchema, null, 2);
+    system += '\n\n' + [
+      '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.',
+      '',
+      'JSON Schema:',
+      schemaStr,
+    ].join('\n');
+    userPrompt = 'Synthesize the sub-agent results into a final answer. Respond with ONLY valid JSON conforming to the schema.';
+  }
+
+  const result = await (options.runOrchestrator ?? deps.orchestrator.run)({
+    parentSessionId: options.parentSessionId,
+    title: `Synthesize: ${options.originalPrompt.slice(0, 50)}`,
+    agentName: 'synthesizer',
+    systemPrompt: system,
+    userPrompt,
+    maxTokens: 8192,
+    abortSignal: options.abortSignal,
+    broadcast: options.broadcast,
+    broadcastSessionCreated: options.broadcastSessionCreated,
+    broadcastSessionUpdated: options.broadcastSessionUpdated,
+  });
+
+  console.log('[workflow:synthesize] Orchestrator session returned', { textLength: result.text?.length });
+
+  if (options.outputSchema) {
+    if (result.json) {
+      console.log('[workflow:synthesize] Structured output parsed successfully');
+      return { text: result.text, structuredResult: result.json };
+    }
+    console.warn('[workflow:synthesize] Failed to parse structured output, returning raw text');
+  }
+
+  return { text: result.text };
+}

package/src/workspace/contracts.ts

@@ -0,0 +1,135 @@
+/**
+ * C6 workspace policy contracts.
+ *
+ * The agent-scoped workspace policy owns containment and path
+ * classification. Two surfaces are unified here:
+ *
+ * - The tool-runtime capability surface previously living in
+ *   `tools/workspace-capability.ts` (`isLexicallyContained` plus the
+ *   capability built over a `WorkspaceCapabilityHost`: tilde/absolute/
+ *   relative resolution, effective-root and additional-root containment,
+ *   sensitive and blocked classification, environment overlay, and
+ *   additional-root mutation through the host).
+ * - The server file-access surface previously living in the Jean2 workspace
+ *   domain (`expandPath`, `resolvePath`, `isPathWithinWorkspace`,
+ *   `isPathInside`, `isInsideUnselectedAdditionalRoot`,
+ *   `resolveCandidatePath`, `resolveRootForQuery`, `selectEditableRoot`).
+ *
+ * The host interface keeps filesystem I/O on the host side: capability
+ * construction only classifies paths and delegates mutations and
+ * environment reads to the host. The Jean2 server fulfills the policy
+ * through the inward-facing `WorkspacePathPolicyPort` adapter
+ * (`adapters/capek/workspace-paths.ts`).
+ */
+
+/** Host supplied by the Jean2 workspace adapter or the facade bindings.
+ * Filesystem I/O stays behind this interface; the policy never performs
+ * I/O itself. */
+export interface WorkspaceCapabilityHost {
+  root?: string;
+  additionalRoots?: string[];
+  allowedRoots?: string[];
+  tempDir: string;
+  getEnvironmentValue?: (key: string) => string | undefined;
+  addAdditionalRoot?: (path: string) => boolean | Promise<boolean>;
+  removeAdditionalRoot?: (path: string) => boolean | Promise<boolean>;
+}
+
+export interface WorkspaceCapability {
+  effectiveRoot: string;
+  additionalRoots: string[];
+  allowedRoots: string[];
+  tempDir: string;
+  resolvePath(path: string): string;
+  isWithinWorkspace(path: string): boolean;
+  isSensitivePath(path: string): boolean;
+  isBlockedPath(path: string): boolean;
+  getEnvironmentValue(key: string): string | undefined;
+  addWorkspacePath(path: string): Promise<boolean>;
+  removeWorkspacePath(path: string): Promise<boolean>;
+}
+
+/** Structural workspace shape used by the server-side root functions. */
+export interface WorkspaceLike {
+  path: string;
+  additionalPaths: string[];
+}
+
+/** Composition-time provider options. The defaults reproduce the exact
+ * pre-C6 constants; a custom provider may swap the blocked-path list, the
+ * sensitive pattern list, or the home directory without the consumers
+ * changing. */
+export interface WorkspacePolicyOptions {
+  blockedPaths: readonly string[];
+  sensitivePatterns: readonly string[];
+  homeDir: string;
+}
+
+/**
+ * Pure path classification policy. Every function is deterministic over its
+ * inputs and the frozen options; none performs filesystem I/O. The
+ * mandatory containment and sensitive/blocked denial invariants are part of
+ * the default provider and are not options (a custom provider replacing
+ * them takes over the invariant, exactly like the other C6 policies).
+ */
+export interface WorkspacePolicy {
+  /** Expands `~` to the frozen home directory and resolves. */
+  expandPath(inputPath: string): string;
+  /** Server-style resolution: tilde joins the frozen home, absolute inputs
+   * resolve verbatim, relative inputs anchor to the workspace path. */
+  resolvePathFor(path: string, workspacePath: string): string;
+  /** Relative-based containment over the workspace root and additional
+   * roots; separator-aware so `/main-other` never matches `/main`. */
+  isPathWithinWorkspace(
+    targetPath: string,
+    workspacePath: string,
+    additionalPaths?: string[],
+  ): boolean;
+  /** Separator-aware containment so `/foo` does not match `/foobar`. */
+  isPathInside(child: string, parent: string): boolean;
+  /** Whether the candidate lies inside an additional root other than the
+   * selected one. */
+  isInsideUnselectedAdditionalRoot(
+    candidate: string,
+    selectedRoot: string,
+    additionalPaths: string[],
+  ): boolean;
+  /** Resolves the client-supplied path against the selected root; absolute
+   * inputs resolve verbatim, relative inputs anchor to the root, and
+   * Windows backslashes normalize to forward slashes. */
+  resolveCandidatePath(root: string, inputPath: string): string;
+  /** Resolves an optional `root` query to an allowed root, falling back to
+   * the main workspace root when missing or invalid. */
+  resolveRootForQuery(
+    workspace: WorkspaceLike,
+    rootQuery?: string,
+  ): { root: string; isMain: boolean };
+  /** Editable-file root selection: an explicit root must exactly match the
+   * main root or one additional root, otherwise `valid` is false (the
+   * caller rejects with the exact 'Invalid workspace root' error). */
+  selectEditableRoot(
+    workspace: WorkspaceLike,
+    rootQuery?: string,
+  ): { root: string; valid: boolean };
+  /** Tool-runtime lexical containment: resolved path equals the root or
+   * starts with `root + sep`. */
+  isLexicallyContained(path: string, root: string): boolean;
+  /** Case-insensitive sensitive-pattern classification. */
+  isSensitivePath(path: string): boolean;
+  /** Blocked-path classification over the frozen blocked list (resolved
+   * input, case-sensitive). */
+  isBlockedPath(path: string): boolean;
+}
+
+/**
+ * The combined agent-scoped workspace service: the pure policy plus the
+ * tool-runtime capability construction over a host.
+ */
+export interface WorkspaceService extends WorkspacePolicy {
+  readonly id: string;
+  /** Frozen composition-time options. */
+  readonly options: Readonly<WorkspacePolicyOptions>;
+  /** Builds the tool-runtime capability over a host using this service's
+   * policy decisions. */
+  createCapability(host: WorkspaceCapabilityHost): WorkspaceCapability;
+}

package/src/workspace/policy.ts

@@ -0,0 +1,327 @@
+/**
+ * C6 workspace policy default provider and scoped service.
+ *
+ * `createWorkspaceService` reproduces the exact pre-C6 behavior: the
+ * tool-runtime capability policy from `tools/workspace-capability.ts` and
+ * the server file-access policy from the Jean2 workspace domain, unified
+ * over frozen composition-time options (blocked paths, sensitive patterns,
+ * home directory). The mandatory containment and sensitive/blocked
+ * classification invariants are part of the default provider.
+ *
+ * Scope ownership: a composed agent scope gets its own service instance.
+ * Consumers that run outside a composed scope (the current Jean2 server
+ * path) fall back to one lazily created process-default service with the
+ * exact default options, until C8 retires the compat surface.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { homedir } from 'os';
+import { isAbsolute, join, relative, resolve, sep } from 'path';
+import { SENSITIVE_FILE_PATTERNS } from '@capekai/types';
+import type {
+  WorkspaceCapability,
+  WorkspaceCapabilityHost,
+  WorkspaceLike,
+  WorkspacePolicyOptions,
+  WorkspaceService,
+} from './contracts';
+
+export const BLOCKED_PATHS = [
+  '/etc/', '/usr/', '/bin/', '/sbin/', '/boot/', '/dev/',
+  '/proc/', '/sys/', '/root/',
+];
+
+export interface WorkspaceServiceCreateOptions {
+  id?: string;
+  /** Frozen composition-time options. When omitted (the process-default
+   * fallback), the exact pre-C6 defaults apply: the current blocked and
+   * sensitive constants and the process home directory. */
+  options?: WorkspacePolicyOptions;
+}
+
+function defaultOptions(): WorkspacePolicyOptions {
+  return {
+    blockedPaths: BLOCKED_PATHS,
+    sensitivePatterns: SENSITIVE_FILE_PATTERNS,
+    homeDir: homedir(),
+  };
+}
+
+// ── Mandatory containment runtime (C6 step 6) ───────────────────────────
+// The tool-runtime capability is constructed HERE, not by provider methods:
+// a custom provider supplies only frozen options (blocked paths, sensitive
+// patterns, home directory). Containment, lexical checks, and the
+// capability algorithms are non-overridable runtime evidence.
+
+export function isLexicallyContained(path: string, root: string): boolean {
+  const resolvedPath = resolve(path);
+  const resolvedRoot = resolve(root);
+  return resolvedPath === resolvedRoot
+    || resolvedPath.startsWith(resolvedRoot.endsWith(sep) ? resolvedRoot : `${resolvedRoot}${sep}`);
+}
+
+function isSensitiveWith(patterns: readonly string[], candidate: string): boolean {
+  const lower = candidate.toLowerCase();
+  return patterns.some((pattern) => lower.includes(pattern));
+}
+
+function isBlockedWith(blockedPaths: readonly string[], candidate: string): boolean {
+  const resolvedPath = resolve(candidate);
+  return blockedPaths.some((blockedPath) => resolvedPath.startsWith(blockedPath));
+}
+
+export function createWorkspaceCapabilityWithOptions(
+  host: WorkspaceCapabilityHost,
+  options: WorkspacePolicyOptions,
+): WorkspaceCapability {
+  const effectiveRoot = resolve(host.root || process.cwd());
+  const additionalRoots = (host.additionalRoots ?? []).map((path) => resolve(path));
+  const allowedRoots = (host.allowedRoots ?? []).map((path) => resolve(path));
+
+  function resolvePath(path: string): string {
+    if (path === '~' || path.startsWith('~/')) {
+      return join(options.homeDir, path.slice(1));
+    }
+    if (isAbsolute(path)) {
+      return resolve(path);
+    }
+    return resolve(effectiveRoot, path);
+  }
+
+  return {
+    effectiveRoot,
+    additionalRoots,
+    allowedRoots,
+    tempDir: host.tempDir,
+    resolvePath,
+    isWithinWorkspace(path: string): boolean {
+      const resolvedPath = resolvePath(path);
+      return [effectiveRoot, ...additionalRoots]
+        .some((root) => isLexicallyContained(resolvedPath, root));
+    },
+    isSensitivePath(path: string): boolean {
+      return isSensitiveWith(options.sensitivePatterns, path);
+    },
+    isBlockedPath(path: string): boolean {
+      const resolvedPath = resolvePath(path);
+      return isBlockedWith(options.blockedPaths, resolvedPath);
+    },
+    getEnvironmentValue(key: string): string | undefined {
+      return host.getEnvironmentValue?.(key) ?? process.env[key];
+    },
+    async addWorkspacePath(path: string): Promise<boolean> {
+      if (!host.addAdditionalRoot) return false;
+      return host.addAdditionalRoot(resolve(path));
+    },
+    async removeWorkspacePath(path: string): Promise<boolean> {
+      if (!host.removeAdditionalRoot) return false;
+      return host.removeAdditionalRoot(resolve(path));
+    },
+  };
+}
+
+/** The C6 default provider wrapping the exact pre-C6 behavior. */
+export function createWorkspaceService(
+  createOptions: WorkspaceServiceCreateOptions = {},
+): WorkspaceService {
+  const id = createOptions.id ?? 'workspace.default';
+  const options = createOptions.options ?? defaultOptions();
+
+  const service: WorkspaceService = {
+    id,
+    options,
+
+    expandPath(inputPath: string): string {
+      let expanded = inputPath;
+      if (expanded.startsWith('~/') || expanded === '~') {
+        expanded = join(options.homeDir, expanded.slice(1));
+      }
+      return resolve(expanded);
+    },
+
+    resolvePathFor(path: string, workspacePath: string): string {
+      if (path.startsWith('~/') || path === '~') {
+        return join(options.homeDir, path.slice(1));
+      }
+      if (isAbsolute(path)) {
+        return resolve(path);
+      }
+      return resolve(workspacePath, path);
+    },
+
+    isPathWithinWorkspace(
+      targetPath: string,
+      workspacePath: string,
+      additionalPaths: string[] = [],
+    ): boolean {
+      const resolvedPath = service.resolvePathFor(targetPath, workspacePath);
+      const allAllowed = [resolve(workspacePath), ...additionalPaths.map((p) => resolve(p))];
+      return allAllowed.some((allowed) => {
+        const relativePath = relative(allowed, resolvedPath);
+        return relativePath === ''
+          || (relativePath !== '..' && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath));
+      });
+    },
+
+    isPathInside(child: string, parent: string): boolean {
+      if (child === parent) return true;
+      if (parent === sep) return true;
+      return child.startsWith(parent + sep);
+    },
+
+    isInsideUnselectedAdditionalRoot(
+      candidate: string,
+      selectedRoot: string,
+      additionalPaths: string[],
+    ): boolean {
+      return additionalPaths.some((path) => {
+        const additionalRoot = resolve(path);
+        return additionalRoot !== selectedRoot && service.isPathInside(candidate, additionalRoot);
+      });
+    },
+
+    resolveCandidatePath(root: string, inputPath: string): string {
+      const normalized = inputPath.replace(/\\/g, '/');
+      return isAbsolute(normalized) ? resolve(normalized) : resolve(join(root, normalized));
+    },
+
+    resolveRootForQuery(
+      workspace: WorkspaceLike,
+      rootQuery?: string,
+    ): { root: string; isMain: boolean } {
+      const main = resolve(workspace.path);
+      if (!rootQuery) return { root: main, isMain: true };
+      const resolvedRoot = resolve(rootQuery);
+      if (resolvedRoot === main) return { root: main, isMain: true };
+      for (const p of workspace.additionalPaths) {
+        if (resolve(p) === resolvedRoot) return { root: resolvedRoot, isMain: false };
+      }
+      return { root: main, isMain: true };
+    },
+
+    selectEditableRoot(
+      workspace: WorkspaceLike,
+      rootQuery?: string,
+    ): { root: string; valid: boolean } {
+      const mainRoot = resolve(workspace.path);
+      if (!rootQuery) return { root: mainRoot, valid: true };
+
+      const requestedRoot = resolve(rootQuery);
+      const allowedRoots = [mainRoot, ...workspace.additionalPaths.map((path) => resolve(path))];
+      if (!allowedRoots.includes(requestedRoot)) {
+        return { root: mainRoot, valid: false };
+      }
+
+      return { root: requestedRoot, valid: true };
+    },
+
+    isLexicallyContained,
+
+    isSensitivePath(path: string): boolean {
+      const lower = path.toLowerCase();
+      return options.sensitivePatterns.some((pattern) => lower.includes(pattern));
+    },
+
+    isBlockedPath(path: string): boolean {
+      const resolvedPath = resolve(path);
+      return options.blockedPaths.some((blockedPath) => resolvedPath.startsWith(blockedPath));
+    },
+
+    createCapability: (host: WorkspaceCapabilityHost): WorkspaceCapability =>
+      createWorkspaceCapabilityWithOptions(host, options),
+  };
+
+  return service;
+}
+
+const scopedService = new AsyncLocalStorage<WorkspaceService>();
+let processDefaultService: WorkspaceService | undefined;
+
+/** Resolves the service seeded for the active agent scope, falling back to
+ * one lazily created process-default service for consumers that run outside
+ * a composed scope (the current Jean2 server path). The process default
+ * carries the exact pre-C6 option defaults. */
+export function getWorkspaceService(): WorkspaceService {
+  return scopedService.getStore()
+    ?? (processDefaultService ??= createWorkspaceService({ id: 'workspace.process-default' }));
+}
+
+/** Builds the tool-runtime capability over the active workspace policy. */
+export function createWorkspaceCapability(host: WorkspaceCapabilityHost): WorkspaceCapability {
+  return createWorkspaceCapabilityWithOptions(host, getWorkspaceService().options);
+}
+
+/** Seeds a service for the callback duration. `enterAgentScope` seeds the
+ * composed agent scope's service here. */
+export function withWorkspaceService<T>(service: WorkspaceService, callback: () => T): T {
+  return scopedService.run(service, callback);
+}
+
+/** Test-only reset of the lazily created process default. Exported from this
+ * module only; no package subpath re-exports it. */
+export function resetDefaultWorkspaceServiceForTests(): void {
+  processDefaultService = undefined;
+}
+
+// ── Compatibility free functions over the scoped service ────────────────
+// The exact pre-C6 names from the Jean2 workspace domain, exported through
+// the compat barrel so the server `WorkspacePathPolicyPort` adapter keeps
+// one ownership of the algorithms.
+
+/** Expands `~` to the active service's frozen home directory and resolves. */
+export function expandPath(inputPath: string): string {
+  return getWorkspaceService().expandPath(inputPath);
+}
+
+/** Server-style resolution over the active service. */
+export function resolvePath(path: string, workspacePath: string): string {
+  return getWorkspaceService().resolvePathFor(path, workspacePath);
+}
+
+export function isPathWithinWorkspace(
+  targetPath: string,
+  workspacePath: string,
+  additionalPaths: string[] = [],
+): boolean {
+  return getWorkspaceService().isPathWithinWorkspace(targetPath, workspacePath, additionalPaths);
+}
+
+export function isPathInside(child: string, parent: string): boolean {
+  return getWorkspaceService().isPathInside(child, parent);
+}
+
+export function isInsideUnselectedAdditionalRoot(
+  candidate: string,
+  selectedRoot: string,
+  additionalPaths: string[],
+): boolean {
+  return getWorkspaceService().isInsideUnselectedAdditionalRoot(
+    candidate,
+    selectedRoot,
+    additionalPaths,
+  );
+}
+
+export function resolveCandidatePath(root: string, inputPath: string): string {
+  return getWorkspaceService().resolveCandidatePath(root, inputPath);
+}
+
+export function resolveRootForQuery(
+  workspace: WorkspaceLike,
+  rootQuery?: string,
+): { root: string; isMain: boolean } {
+  return getWorkspaceService().resolveRootForQuery(workspace, rootQuery);
+}
+
+export function selectEditableRoot(
+  workspace: WorkspaceLike,
+  rootQuery?: string,
+): { root: string; valid: boolean } {
+  return getWorkspaceService().selectEditableRoot(workspace, rootQuery);
+}
+
+export type {
+  WorkspacePolicy,
+  WorkspacePolicyOptions,
+  WorkspaceService,
+} from './contracts';