@bluecopa/harness 0.1.0-snapshot.33 → 0.1.0-snapshot.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluecopa/harness",
-  "version": "0.1.0-snapshot.33",
+  "version": "0.1.0-snapshot.34",
   "description": "Provider-agnostic TypeScript agent framework",
   "license": "UNLICENSED",
   "scripts": {

package/src/arc/agent-runner.ts

@@ -193,6 +193,8 @@ export interface AgentRunnerConfig {
   seed?: AgentMessage[];
   inbox?: AsyncIterable<AgentMessage>;
   onActivity?: (activity: Activity) => void;
+  /** Allowed tool names for executor-level validation (defense-in-depth). */
+  allowedToolNames?: string[];
 
   // Runtime extras
   hookRunner?: HookRunner;
@@ -293,6 +295,22 @@ export class AgentRunner {
           toolCallId: tc.toolCallId,
         };
 
+        // Layer 2: executor-level tool validation (defense-in-depth)
+        if (config.allowedToolNames && !config.allowedToolNames.includes(tc.toolName)) {
+          const resultText = `ERROR: Tool "${tc.toolName}" is not available in this profile.`;
+          messages.push({
+            role: 'tool',
+            content: resultText,
+            toolResults: [{
+              toolCallId: tc.toolCallId,
+              toolName: tc.toolName,
+              result: resultText,
+              isError: true,
+            }],
+          });
+          continue;
+        }
+
         config.onActivity?.({
           type: 'tool_start',
           name: tc.toolName,
@@ -368,6 +386,8 @@ export interface CreateProcessConfig {
   processSystemPrompt?: string;
   /** Async skill instructions to prepend to system prompt (resolved during process startup). */
   skillPromptPromise?: Promise<string | null>;
+  /** Allowed tool names for executor-level validation (defense-in-depth against hallucinated tool calls). */
+  allowedToolNames?: string[];
 
   // Runtime extras
   hookRunner?: HookRunner;
@@ -454,6 +474,7 @@ export function createProcess(
             'askUser',
             'tellUser',
             'downloadRawFile',
+            'allowedToolNames',
           ]),
         }),
         timeoutPromise(config.processTimeout),
@@ -462,7 +483,7 @@ export function createProcess(
       const durationMs = Date.now() - startTime;
       const nextIndex = await getNextEpisodeIndex(config.episodeStore, config.taskId);
 
-      const { episode, trace, artifacts } = compressor.compress({
+      const compressInput = {
         taskId: config.taskId,
         sessionId: config.sessionId,
         index: nextIndex,
@@ -471,7 +492,9 @@ export function createProcess(
         model,
         parentEpisodeIds: request.contextEpisodeIds ?? [],
         success: true,
-      });
+      };
+
+      const { episode, trace, artifacts } = compressor.compress(compressInput);
 
       await config.episodeStore.addEpisode(episode);
       await config.episodeStore.addTrace(trace);
@@ -490,18 +513,10 @@ export function createProcess(
       outbox.push({ type: 'episode', episode });
       outbox.push({ type: 'done', result: processResult });
 
+      // Async LLM upgrade for long episodes
       if (episode.steps > 10) {
         const upgradeAc = new AbortController();
-        void compressor.compressLLM({
-          taskId: config.taskId,
-          sessionId: config.sessionId,
-          index: nextIndex,
-          threadAction: request.action,
-          messages: result.messages,
-          model,
-          parentEpisodeIds: request.contextEpisodeIds ?? [],
-          success: true,
-        }, upgradeAc.signal).then(async (upgraded) => {
+        void compressor.compressLLM(compressInput, upgradeAc.signal).then(async (upgraded) => {
           episode.summary = upgraded.episode.summary;
           await config.episodeStore.addEpisode(episode);
         }).catch(() => { /* template summary remains */ });

package/src/arc/arc-loop.ts

@@ -17,6 +17,7 @@ import type {
   Turn,
   TraceEvent,
 } from './types';
+import { isProfileDeclaration } from './types';
 import type { ResiliencePolicy, ExecutionContext } from './resilience/types';
 import { toModelMessages, estimateTokens } from './message-convert';
 import { orchestratorTools } from './tools';
@@ -27,9 +28,9 @@ import { createProcess, firstEvent } from './agent-runner';
 import { EpisodeCompressor } from './episode-compressor';
 import { runConsolidation } from './consolidation';
 import { pickDefined } from './utils';
-import { SkillRouter } from '../skills/skill-router';
-import { loadSkillFromFile } from '../skills/skill-loader';
-import type { SkillSummary } from '../skills/skill-types';
+import type { SkillResolver } from './skill-resolver';
+import { DefaultSkillResolver } from './skill-resolver';
+import { resolveProfile } from './profile-builder';
 
 // ── Default orchestrator prompt ──
 
@@ -81,9 +82,7 @@ export class ArcLoop {
   /** Maps normalized action text → process ID for dedup. */
   private readonly actionIndex = new Map<string, string>();
   private readonly processListeners: Promise<void>[] = [];
-  private readonly skillRouter: SkillRouter | undefined;
-  private skillSummaries: SkillSummary[] | null = null;
-  private skillSummariesPromise: Promise<SkillSummary[]> | null = null;
+  private readonly skillResolver: SkillResolver | undefined;
 
   constructor(config: ArcLoopConfig) {
     this.config = config;
@@ -124,14 +123,10 @@ export class ArcLoop {
     this.resilience = config.resilience;
     this.traceWriter = (config as ArcLoopConfig & { traceWriter?: (event: TraceEvent) => void }).traceWriter;
 
-    if (config.skillIndexPath) {
-      this.skillRouter = new SkillRouter();
-      // Lazy-load skill summaries on first dispatch
-      this.skillSummariesPromise = import('node:fs/promises')
-        .then(fs => fs.readFile(config.skillIndexPath!, 'utf-8'))
-        .then(raw => JSON.parse(raw) as SkillSummary[])
-        .catch(() => []);
-    }
+    this.skillResolver = config.skillResolver
+      ?? (config.skillIndexPath
+        ? new DefaultSkillResolver({ skillIndexPath: config.skillIndexPath })
+        : undefined);
   }
 
   private trace(kind: TraceEvent['kind']): void {
@@ -546,18 +541,28 @@ export class ArcLoop {
   // ── Process dispatch ──
 
   private dispatch(request: ProcessRequest, parentSignal: AbortSignal): Process {
-    const profile = request.profile
+    const profileConfig = request.profile
       ? this.config.processProfiles?.[request.profile]
       : undefined;
+
+    // Resolve ProfileDeclaration → ProcessProfile (legacy profiles pass through)
+    const globalTools = (this.config.processTools ?? builtinTools) as Record<string, import('./arc-types').AnyTool>;
+    const profile = profileConfig
+      ? resolveProfile(profileConfig, globalTools)
+      : undefined;
+
     const defaultModel = resolveModel(
       profile?.model ?? 'medium',
       this.modelMap,
       this.modelMap.medium,
     );
 
-    // Resolve skill instructions only when skills are configured
-    const skillPromptPromise = this.skillRouter
-      ? this.resolveSkillPrompt(request.action)
+    // Resolve skill instructions, constrained to profile's allowed skills (if declared)
+    const profileSkills = profileConfig && isProfileDeclaration(profileConfig)
+      ? profileConfig.skills
+      : undefined;
+    const skillPromptPromise = this.skillResolver
+      ? this.skillResolver.resolve(request.action, profileSkills).then(r => r?.systemPrompt ?? null)
       : undefined;
 
     const proc = createProcess(request, {
@@ -570,8 +575,9 @@ export class ArcLoop {
       processMaxSteps: profile?.maxSteps ?? this.config.processMaxSteps ?? 20,
       processTimeout: this.config.processTimeout ?? 120_000,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      processTools: (profile?.tools ?? this.config.processTools ?? builtinTools) as any,
+      processTools: (profile?.tools ?? globalTools) as any,
       processSystemPrompt: profile?.systemPrompt ?? this.config.processSystemPrompt,
+      allowedToolNames: profile?.allowedToolNames,
       skillPromptPromise,
       parentSignal,
       ...pickDefined(this.config, [
@@ -587,35 +593,6 @@ export class ArcLoop {
     return proc;
   }
 
-  /** Resolve skill instructions for a process action. Returns null if no skill matched. */
-  private async resolveSkillPrompt(action: string): Promise<string | null> {
-    if (!this.skillRouter || !this.skillSummariesPromise) return null;
-
-    // Ensure summaries are loaded
-    if (!this.skillSummaries) {
-      this.skillSummaries = await this.skillSummariesPromise;
-    }
-    if (this.skillSummaries.length === 0) return null;
-
-    // Fast match only (keyword + alias, no LLM call)
-    const matched = await this.skillRouter.selectSkill(action, this.skillSummaries);
-    if (matched) {
-      console.log(`[skill-router] Matched skill "${matched.name}" for action: "${action.slice(0, 80)}..."`);
-    } else {
-      console.log(`[skill-router] No match for action: "${action.slice(0, 80)}..."`);
-    }
-    if (!matched) return null;
-
-    try {
-      const skill = await loadSkillFromFile(matched.path);
-      console.log(`[skill-router] Loaded skill "${matched.name}" (${skill.instructions?.length ?? 0} chars)`);
-      return skill.instructions || null;
-    } catch (err) {
-      console.error(`[skill-router] Failed to load skill "${matched.name}":`, err);
-      return null;
-    }
-  }
-
   private traceProcessRunning(procId: string): void {
     if (!this.tracedRunning.has(procId)) {
       this.tracedRunning.add(procId);

package/src/arc/profile-builder.ts

@@ -0,0 +1,142 @@
+/**
+ * Profile builder — generates prompts and resolves tools from ProfileDeclarations.
+ *
+ * The core idea: profiles declare WHAT (signature, tools, background).
+ * This module generates the HOW (system prompts, tool objects).
+ */
+
+import type { AnyTool } from './arc-types';
+import type { ProfileDeclaration, ProcessProfile, ProfileConfig } from './types';
+import { isProfileDeclaration } from './types';
+
+// ── Thread prompt generation ────────────────────────────────────
+
+/**
+ * Generate a thread system prompt from a ProfileDeclaration.
+ *
+ * The prompt tells the thread:
+ * - What it is (name)
+ * - What it produces (signature)
+ * - What tools it has (enforced, not suggested)
+ * - Domain knowledge (background)
+ */
+export function buildProfilePrompt(decl: ProfileDeclaration): string {
+  const [input, output] = decl.signature.split('->').map(s => s.trim());
+  const lines = [
+    `You are a ${decl.name} thread.`,
+    `Your task: take ${input} and produce ${output}.`,
+    '',
+    `## Available tools`,
+    `You have access to: ${decl.tools.join(', ')}`,
+    'Use ONLY these tools. You cannot use any other tools.',
+    'If you have Skill Instructions below, follow them for delivery method and style.',
+  ];
+
+  if (decl.background) {
+    lines.push('', '## Background', decl.background);
+  }
+
+  return lines.join('\n');
+}
+
+// ── Orchestrator prompt generation ──────────────────────────────
+
+/**
+ * Generate an orchestrator system prompt from a set of profile declarations.
+ *
+ * The orchestrator sees profile names, signatures, and tool counts —
+ * enough to route correctly. No tool names, no delivery methods.
+ *
+ * @param profiles - The registered profiles
+ * @param preamble - Optional strategy preamble (phasing, rules, context).
+ *                   Composed with the auto-generated profile catalog.
+ */
+export function buildOrchestratorPrompt(
+  profiles: Record<string, ProfileConfig>,
+  preamble?: string,
+): string {
+  const profileList = Object.entries(profiles)
+    .map(([name, p]) => {
+      if (isProfileDeclaration(p)) {
+        return `- **${name}** — ${p.signature} (tools: ${p.tools.length}, ${p.model || 'medium'})`;
+      }
+      // Legacy ProcessProfile — show name only
+      return `- **${name}**`;
+    })
+    .join('\n');
+
+  const sections = [
+    'You are an orchestrator. Dispatch Thread calls to accomplish tasks.',
+    '',
+    '## Profiles',
+    profileList,
+    '',
+    '## Thread actions',
+    'Describe WHAT to create, not HOW. 2-5 sentences. Threads have tools and skill instructions — they know delivery methods.',
+    'ALWAYS set the profile parameter on every Thread call.',
+  ];
+
+  if (preamble) {
+    // Insert preamble after the identity line
+    sections.splice(1, 0, '', preamble);
+  }
+
+  return sections.join('\n');
+}
+
+// ── Tool resolution ─────────────────────────────────────────────
+
+/**
+ * Resolve tool names to tool objects from the global tool registry.
+ * Returns only the tools listed in the declaration.
+ */
+export function resolveProfileTools(
+  toolNames: string[],
+  globalTools: Record<string, AnyTool>,
+): Record<string, AnyTool> {
+  const resolved: Record<string, AnyTool> = {};
+  for (const name of toolNames) {
+    if (globalTools[name]) {
+      resolved[name] = globalTools[name];
+    }
+  }
+  return resolved;
+}
+
+// ── ProfileDeclaration → ProcessProfile conversion ──────────────
+
+/**
+ * Build a runtime ProcessProfile from a ProfileDeclaration.
+ * Generates the system prompt and resolves tool objects.
+ */
+export function buildProcessProfile(
+  decl: ProfileDeclaration,
+  globalTools: Record<string, AnyTool>,
+): ProcessProfile {
+  const profile: ProcessProfile = {
+    systemPrompt: buildProfilePrompt(decl),
+    tools: resolveProfileTools(decl.tools, globalTools),
+    allowedToolNames: decl.tools,
+  };
+  if (decl.model) profile.model = decl.model;
+  if (decl.maxSteps) profile.maxSteps = decl.maxSteps;
+  return profile;
+}
+
+/**
+ * Resolve a ProfileConfig (declaration or legacy) into a ProcessProfile.
+ * Declarations are built; legacy profiles are passed through.
+ */
+export function resolveProfile(
+  config: ProfileConfig,
+  globalTools: Record<string, AnyTool>,
+): ProcessProfile {
+  if (isProfileDeclaration(config)) {
+    return buildProcessProfile(config, globalTools);
+  }
+  // Backfill allowedToolNames for legacy profiles when tools are defined
+  if (config.tools && !config.allowedToolNames) {
+    return { ...config, allowedToolNames: Object.keys(config.tools) };
+  }
+  return config;
+}

package/src/arc/skill-resolver.ts

@@ -0,0 +1,78 @@
+/**
+ * SkillResolver — pluggable interface for resolving skill instructions from action text.
+ *
+ * Extracted from ArcLoop to satisfy DIP + SRP:
+ * - ArcLoop depends on the interface, not on SkillRouter/file loader directly
+ * - Tests can mock skill resolution without filesystem
+ * - Alternative implementations (remote registries) plug in without touching ArcLoop
+ */
+
+import { SkillRouter } from '../skills/skill-router';
+import { loadSkillFromFile } from '../skills/skill-loader';
+import type { SkillSummary } from '../skills/skill-types';
+
+// ── Interface ──
+
+export interface ResolvedSkill {
+  name: string;
+  systemPrompt: string;
+}
+
+export interface SkillResolver {
+  resolve(action: string, profileSkills?: string[]): Promise<ResolvedSkill | null>;
+}
+
+// ── Default implementation ──
+
+export interface DefaultSkillResolverConfig {
+  /** Path to skills-index.json */
+  skillIndexPath: string;
+  /** Optional SkillRouter config (aliases, model, etc.) */
+  routerConfig?: ConstructorParameters<typeof SkillRouter>[0];
+}
+
+export class DefaultSkillResolver implements SkillResolver {
+  private readonly router: SkillRouter;
+  private readonly summariesPromise: Promise<SkillSummary[]>;
+  private summaries: SkillSummary[] | null = null;
+
+  constructor(config: DefaultSkillResolverConfig) {
+    this.router = new SkillRouter(config.routerConfig);
+    this.summariesPromise = import('node:fs/promises')
+      .then(fs => fs.readFile(config.skillIndexPath, 'utf-8'))
+      .then(raw => JSON.parse(raw) as SkillSummary[])
+      .catch(() => []);
+  }
+
+  async resolve(action: string, profileSkills?: string[]): Promise<ResolvedSkill | null> {
+    if (!this.summaries) {
+      this.summaries = await this.summariesPromise;
+    }
+    if (this.summaries.length === 0) return null;
+
+    // If profile restricts skills, filter summaries to that set
+    const candidates = profileSkills
+      ? this.summaries.filter(s => profileSkills.includes(s.name))
+      : this.summaries;
+
+    if (candidates.length === 0) return null;
+
+    const matched = await this.router.selectSkill(action, candidates);
+    if (matched) {
+      console.log(`[skill-resolver] Matched skill "${matched.name}" for action: "${action.slice(0, 80)}..."`);
+    } else {
+      console.log(`[skill-resolver] No match for action: "${action.slice(0, 80)}..."`);
+    }
+    if (!matched) return null;
+
+    try {
+      const skill = await loadSkillFromFile(matched.path);
+      console.log(`[skill-resolver] Loaded skill "${matched.name}" (${skill.instructions?.length ?? 0} chars)`);
+      if (!skill.instructions) return null;
+      return { name: matched.name, systemPrompt: skill.instructions };
+    } catch (err) {
+      console.error(`[skill-resolver] Failed to load skill "${matched.name}":`, err);
+      return null;
+    }
+  }
+}

package/src/arc/types.ts

@@ -41,14 +41,13 @@ export interface EpisodeArtifact {
 // ── ArcLoop v2 Config ──
 
 export interface ArcLoopConfig {
+  // Orchestrator
   /** Orchestrator model (default: 'claude-opus-4-6'). Accepts a model ID or tier name. */
   model?: string;
   /** Model tier mapping. Override to use different models for fast/medium/strong. */
   modelMap?: Record<import('./arc-types').ModelTier, string>;
   /** Anthropic API key */
   apiKey?: string;
-
-  // Orchestrator
   /** Custom orchestrator system prompt */
   systemPrompt?: string;
   /** Max orchestrator turns before stopping (default: 30) */
@@ -57,6 +56,8 @@ export interface ArcLoopConfig {
   extraOrchestratorTools?: Record<string, import('./arc-types').AnyTool>;
   /** Handler for extra orchestrator tools. Return an AgentAction (typically FinalAction with directive). */
   onOrchestratorTool?: (name: string, args: Record<string, unknown>) => Promise<import('../agent/types').AgentAction>;
+  /** Optional resilience policy applied to LLM calls (retry, circuit breaker, timeout, etc.). */
+  resilience?: import('./resilience/types').ResiliencePolicy;
 
   // Processes
   /** Per-process timeout in ms (default: 120_000) */
@@ -65,8 +66,10 @@ export interface ArcLoopConfig {
   processMaxSteps?: number;
   /** Default system prompt for all processes (overrides the built-in default) */
   processSystemPrompt?: string;
-  /** Named process profiles. The orchestrator selects a profile via the Thread tool's `profile` param. */
-  processProfiles?: Record<string, ProcessProfile>;
+  /** Named process profiles. Accepts ProfileDeclaration (new, declarative) or ProcessProfile (legacy). */
+  processProfiles?: Record<string, ProfileConfig>;
+  /** Tools available inside processes (default: builtinTools) */
+  processTools?: Record<string, import('./arc-types').AnyTool>;
 
   // Context
   /** Context window size in tokens (default: 200_000) */
@@ -74,10 +77,6 @@ export interface ArcLoopConfig {
   /** Tokens reserved for output (default: 20_000) */
   outputReserve?: number;
 
-  // Memory
-  /** Enable auto-memory detection and promotion (default: true) */
-  autoMemory?: boolean;
-
   // Stores (required)
   episodeStore: import('./arc-types').EpisodeStore;
   sessionMemoStore: import('./arc-types').SessionMemoStore;
@@ -87,10 +86,16 @@ export interface ArcLoopConfig {
   taskId: string;
   sessionId: string;
 
+  // Memory
+  /** Enable auto-memory detection and promotion (default: true) */
+  autoMemory?: boolean;
+
+  // Dependency injection
+  /** Pre-built SkillResolver instance. If omitted, one is created from skillIndexPath (if provided). */
+  skillResolver?: import('./skill-resolver').SkillResolver;
+
   // Tools & providers
   toolProvider: import('../interfaces/tool-provider').ToolProvider;
-  /** Tools available inside processes (default: builtinTools) */
-  processTools?: Record<string, import('./arc-types').AnyTool>;
   /** Tool provider for skill-matched processes (sandbox) */
   skillToolProvider?: import('../interfaces/tool-provider').ToolProvider;
   /** Local directory to sync sandbox output artifacts to (default: './outputs') */
@@ -104,9 +109,6 @@ export interface ArcLoopConfig {
   hookRunner?: import('../hooks/hook-runner').HookRunner;
   permissionManager?: import('../permissions/permission-manager').PermissionManager;
   executeToolAction?: (action: import('../agent/types').ToolCallAction) => Promise<import('../interfaces/tool-provider').ToolResult | null>;
-
-  /** Optional resilience policy applied to LLM calls (retry, circuit breaker, timeout, etc.). */
-  resilience?: import('./resilience/types').ResiliencePolicy;
 }
 
 // ── Process types ──
@@ -156,7 +158,38 @@ export interface ProcessRequest {
   profile?: string;
 }
 
-/** A named process profile — provides defaults for system prompt, tools, model, and step limit. */
+/**
+ * ProfileDeclaration — typed, declarative profile definition.
+ *
+ * Replaces hand-written system prompts with structured declarations.
+ * The system generates prompts from the declaration and enforces tool constraints.
+ *
+ * @example
+ *   const visual: ProfileDeclaration = {
+ *     name: 'visual',
+ *     signature: 'description -> compiledArtifact',
+ *     tools: ['CompileJsx', 'Read', 'ListFiles'],
+ *     skills: ['visual-explainer'],
+ *   };
+ */
+export interface ProfileDeclaration {
+  /** Profile name (matches the Thread tool's profile parameter). */
+  name: string;
+  /** Typed signature: "input -> output". Describes what this profile produces. */
+  signature: string;
+  /** Tool names this profile can use. Only these tools are available — enforced at schema + executor level. */
+  tools: string[];
+  /** Domain knowledge injected into system prompt (skill content, color systems, etc.). */
+  background?: string;
+  /** Default model tier. */
+  model?: import('./arc-types').ModelTier;
+  /** Max LLM steps. */
+  maxSteps?: number;
+  /** Skill names this profile can use. SkillRouter is constrained to this set. Omit for all skills. */
+  skills?: string[];
+}
+
+/** A named process profile — runtime form with resolved prompt and tools. */
 export interface ProcessProfile {
   /** System prompt for processes using this profile. */
   systemPrompt: string;
@@ -166,6 +199,16 @@ export interface ProcessProfile {
   model?: import('./arc-types').ModelTier;
   /** Max steps for this profile (Thread tool's explicit maxSteps overrides this). */
   maxSteps?: number;
+  /** Allowed tool names for executor-level validation (populated from ProfileDeclaration.tools). */
+  allowedToolNames?: string[];
+}
+
+/** A profile config can be either a declaration (new) or a raw ProcessProfile (backward compat). */
+export type ProfileConfig = ProfileDeclaration | ProcessProfile;
+
+/** Type guard: check if a profile config is a declaration. */
+export function isProfileDeclaration(p: ProfileConfig): p is ProfileDeclaration {
+  return 'signature' in p && typeof (p as ProfileDeclaration).signature === 'string';
 }
 
 export type Activity =