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

package/package.json

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

package/src/arc/agent-runner.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { generateText } from 'ai';
+import { generateText, generateObject } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
 import type { AgentMessage, ToolCallAction } from '../agent/types';
 import { getTextContent } from '../agent/types';
@@ -193,6 +193,11 @@ export interface AgentRunnerConfig {
   seed?: AgentMessage[];
   inbox?: AsyncIterable<AgentMessage>;
   onActivity?: (activity: Activity) => void;
+  /** Allowed tool names for executor-level validation (defense-in-depth). */
+  allowedToolNames?: string[];
+  /** Zod schema for structured output. When set, the terminal step uses generateObject instead of generateText. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  outputSchema?: import('zod').ZodObject<any>;
 
   // Runtime extras
   hookRunner?: HookRunner;
@@ -211,6 +216,8 @@ export interface AgentRunResult {
   messages: AgentMessage[];
   output: string;
   steps: number;
+  /** Structured output from generateObject when outputSchema is set. */
+  structuredOutput?: Record<string, unknown>;
 }
 
 export class AgentRunner {
@@ -270,6 +277,24 @@ export class AgentRunner {
       if (toolCalls.length === 0) {
         const text = result.text?.trim() ?? 'Done.';
         messages.push({ role: 'assistant', content: text });
+
+        // Structured output: use generateObject on terminal step when schema is set
+        if (config.outputSchema) {
+          try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const structured = await (generateObject as any)({
+              model: anthropic(config.model),
+              schema: config.outputSchema,
+              messages: toModelMessages(messages),
+              system: [{ role: 'system' as const, content: config.systemPrompt }],
+              abortSignal: config.signal,
+            });
+            return { messages, output: text, steps: step + 1, structuredOutput: structured.object };
+          } catch {
+            // Structured extraction failed — fall back to text output
+          }
+        }
+
         return { messages, output: text, steps: step + 1 };
       }
 
@@ -293,6 +318,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 +409,13 @@ 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[];
+  /** Zod schema for structured output on the terminal step. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  outputSchema?: import('zod').ZodObject<any>;
+  /** Few-shot demo messages prepended before context episodes. */
+  demoMessages?: AgentMessage[];
 
   // Runtime extras
   hookRunner?: HookRunner;
@@ -421,7 +469,10 @@ export function createProcess(
   void (async () => {
     try {
       process.status = 'running';
-      const seed = await seedPromise;
+      const seed = [
+        ...(config.demoMessages ?? []),
+        ...(await seedPromise),
+      ];
 
       // Build system prompt: base + optional skill instructions
       let systemPrompt = config.processSystemPrompt ?? PROCESS_SYSTEM_PROMPT;
@@ -454,6 +505,8 @@ export function createProcess(
             'askUser',
             'tellUser',
             'downloadRawFile',
+            'allowedToolNames',
+            'outputSchema',
           ]),
         }),
         timeoutPromise(config.processTimeout),
@@ -462,7 +515,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 +524,14 @@ export function createProcess(
         model,
         parentEpisodeIds: request.contextEpisodeIds ?? [],
         success: true,
-      });
+      };
+
+      const { episode, trace, artifacts } = compressor.compress(compressInput);
+
+      // Attach structured output from generateObject if present
+      if (result.structuredOutput) {
+        episode.structuredOutput = result.structuredOutput;
+      }
 
       await config.episodeStore.addEpisode(episode);
       await config.episodeStore.addTrace(trace);
@@ -490,18 +550,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,11 @@ 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,
+      outputSchema: profile?.outputSchema,
+      demoMessages: profile?.demoMessages,
       skillPromptPromise,
       parentSignal,
       ...pickDefined(this.config, [
@@ -587,35 +595,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/arc-types.ts

@@ -18,6 +18,8 @@ export interface Episode {
   success: boolean;
   createdAt: number;
   parentEpisodeIds: string[];
+  /** Typed output from generateObject when profile has a typed signature. */
+  structuredOutput?: Record<string, unknown>;
 }
 
 export interface EpisodeTrace {

package/src/arc/profile-builder.ts

@@ -0,0 +1,157 @@
+/**
+ * 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';
+import { parseSignature, signatureToSchema, isTypedSignature } from './sig';
+
+// ── 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;
+  // Generate output schema from typed signatures (e.g., 'question:string -> evidence:string[]')
+  if (isTypedSignature(decl.signature)) {
+    const parsed = parseSignature(decl.signature);
+    if (parsed.outputs.length > 0) {
+      profile.outputSchema = signatureToSchema(parsed);
+    }
+  }
+  // Render demos as user/assistant message pairs
+  if (decl.demos && decl.demos.length > 0) {
+    profile.demoMessages = decl.demos.flatMap(demo => [
+      { role: 'user' as const, content: Object.entries(demo.input).map(([k, v]) => `${k}: ${v}`).join('\n') },
+      { role: 'assistant' as const, content: JSON.stringify(demo.output) },
+    ]);
+  }
+  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/sig.ts

@@ -0,0 +1,120 @@
+/**
+ * DSPy-style signature parsing and schema generation.
+ *
+ * Parses signature strings like "question:string -> evidence:string[], confidence:number"
+ * into typed field definitions, and generates Zod schemas for structured output.
+ */
+
+import { z } from 'zod';
+
+// ── Types ──
+
+export interface SignatureField {
+  name: string;
+  type: 'string' | 'number' | 'boolean';
+  isArray: boolean;
+  isOptional: boolean;
+  description?: string;
+}
+
+export interface ParsedSignature {
+  inputs: SignatureField[];
+  outputs: SignatureField[];
+}
+
+// ── Parser ──
+
+const FIELD_RE = /^(\w+)(?::(\w+)(\[\])?)(\?)?(?:\s*\(([^)]+)\))?$/;
+
+function parseField(raw: string): SignatureField {
+  const trimmed = raw.trim();
+  const match = trimmed.match(FIELD_RE);
+
+  if (!match) {
+    // Bare field name — default to string
+    const name = trimmed.replace(/\?$/, '');
+    return {
+      name,
+      type: 'string',
+      isArray: false,
+      isOptional: trimmed.endsWith('?'),
+    };
+  }
+
+  const [, name, typeStr, arrayMark, optionalMark, desc] = match;
+  const type = (['string', 'number', 'boolean'].includes(typeStr!) ? typeStr : 'string') as SignatureField['type'];
+
+  const field: SignatureField = {
+    name: name!,
+    type,
+    isArray: arrayMark === '[]',
+    isOptional: optionalMark === '?',
+  };
+  if (desc) field.description = desc.trim();
+  return field;
+}
+
+/**
+ * Parse a signature string into typed input/output fields.
+ *
+ * @example
+ *   parseSignature('question:string -> evidence:string[], confidence:number')
+ *   // { inputs: [{ name: 'question', type: 'string', ... }],
+ *   //   outputs: [{ name: 'evidence', type: 'string', isArray: true, ... },
+ *   //             { name: 'confidence', type: 'number', ... }] }
+ *
+ *   parseSignature('query -> findings')
+ *   // All fields default to type 'string', isArray false
+ */
+export function parseSignature(sig: string): ParsedSignature {
+  const arrowIdx = sig.indexOf('->');
+  if (arrowIdx < 0) {
+    // No arrow — treat entire string as a single input, single output
+    const parts = sig.split(',').map(s => s.trim()).filter(Boolean);
+    return {
+      inputs: parts.length > 0 ? [parseField(parts[0]!)] : [],
+      outputs: parts.length > 1 ? [parseField(parts[1]!)] : [{ name: 'result', type: 'string', isArray: false, isOptional: false }],
+    };
+  }
+
+  const inputStr = sig.slice(0, arrowIdx).trim();
+  const outputStr = sig.slice(arrowIdx + 2).trim();
+
+  const inputs = inputStr.split(',').map(s => s.trim()).filter(Boolean).map(parseField);
+  const outputs = outputStr.split(',').map(s => s.trim()).filter(Boolean).map(parseField);
+
+  return { inputs, outputs };
+}
+
+// ── Schema generation ──
+
+/**
+ * Convert a parsed signature's output fields into a Zod schema.
+ * Used with ai-sdk's generateObject() for structured output extraction.
+ */
+export function signatureToSchema(sig: ParsedSignature): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  const shape: Record<string, z.ZodTypeAny> = {};
+
+  for (const field of sig.outputs) {
+    let base: z.ZodTypeAny;
+    switch (field.type) {
+      case 'number': base = z.number(); break;
+      case 'boolean': base = z.boolean(); break;
+      default: base = z.string(); break;
+    }
+    if (field.isArray) base = z.array(base);
+    if (field.description) base = base.describe(field.description);
+    if (field.isOptional) base = base.optional();
+    shape[field.name] = base;
+  }
+
+  return z.object(shape);
+}
+
+/**
+ * Check if a signature string has typed fields (contains ':').
+ * Untyped signatures like 'query -> findings' are treated as cosmetic labels.
+ */
+export function isTypedSignature(sig: string): boolean {
+  return sig.includes(':');
+}

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/stores/rxdb-setup.ts

@@ -22,6 +22,7 @@ const episodeSchema: RxJsonSchema<Episode> = {
     success: { type: 'boolean' },
     createdAt: { type: 'integer' },
     parentEpisodeIds: { type: 'array', items: { type: 'string' } },
+    structuredOutput: { type: 'object' },
   },
   required: ['id', 'taskId', 'sessionId', 'index', 'threadAction', 'summary', 'model', 'steps', 'success', 'createdAt'],
   indexes: ['taskId', 'sessionId', 'createdAt'],

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,43 @@ 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[];
+  /** Few-shot demonstration examples. Rendered as user/assistant message pairs in the prompt. */
+  demos?: Array<{
+    input: Record<string, string>;
+    output: Record<string, unknown>;
+  }>;
+}
+
+/** 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 +204,21 @@ 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[];
+  /** Zod schema for structured output on the terminal step (generated from typed signatures). */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  outputSchema?: import('zod').ZodObject<any>;
+  /** Few-shot demo messages rendered before the task prompt. */
+  demoMessages?: import('../agent/types').AgentMessage[];
+}
+
+/** 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 =