@bluecopa/harness 0.1.0-snapshot.98 → 1.0.0

package/src/providers/skill-sandbox-provider.ts

@@ -0,0 +1,46 @@
+import type { SandboxFileBlob, SandboxProvider, SandboxExecOptions, SandboxExecResult } from '../interfaces/sandbox-provider';
+import { ControlPlaneE2BExecutor } from './control-plane-e2b-executor';
+
+export class SkillSandboxProvider implements SandboxProvider {
+  constructor(private readonly executor: ControlPlaneE2BExecutor) {}
+
+  static fromEnv(): SkillSandboxProvider {
+    return new SkillSandboxProvider(ControlPlaneE2BExecutor.fromEnv());
+  }
+
+  async initialize(): Promise<void> {
+    await this.executor.initialize();
+  }
+
+  async destroy(): Promise<void> {
+    await this.executor.destroy();
+  }
+
+  async exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult> {
+    const result = await this.executor.bash(command, {
+      cwd: options?.cwd,
+      timeout: options?.timeoutMs
+    });
+    return {
+      exitCode: result.success ? 0 : 1,
+      stdout: result.output ?? '',
+      stderr: result.error ?? ''
+    };
+  }
+
+  async readSandboxFile(path: string): Promise<SandboxFileBlob> {
+    const bytes = await this.executor.readFileBytes(path);
+    return {
+      data: bytes,
+      filename: path.split('/').pop() ?? path
+    };
+  }
+
+  async writeSandboxFile(path: string, content: SandboxFileBlob): Promise<void> {
+    const text = Buffer.from(content.data).toString('utf8');
+    const result = await this.executor.writeFile(path, text);
+    if (!result.success) {
+      throw new Error(result.error ?? `write failed for ${path}`);
+    }
+  }
+}

package/src/sessions/file-session-store.ts

@@ -0,0 +1,61 @@
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import type { AgentSession, SessionFilter, SessionStore } from '../interfaces/session-store';
+
+export class FileSessionStore implements SessionStore {
+  constructor(private readonly baseDir: string) {}
+
+  private pathFor(id: string): string {
+    return join(this.baseDir, `${id}.json`);
+  }
+
+  async save(session: AgentSession): Promise<void> {
+    await mkdir(this.baseDir, { recursive: true });
+    await writeFile(this.pathFor(session.id), JSON.stringify(session, null, 2), 'utf8');
+  }
+
+  async get(id: string): Promise<AgentSession | null> {
+    try {
+      const raw = await readFile(this.pathFor(id), 'utf8');
+      return JSON.parse(raw) as AgentSession;
+    } catch {
+      return null;
+    }
+  }
+
+  async list(filter?: SessionFilter): Promise<AgentSession[]> {
+    await mkdir(this.baseDir, { recursive: true });
+    const files = await readdir(this.baseDir);
+    const sessions = (
+      await Promise.all(
+        files
+          .filter((file) => file.endsWith('.json'))
+          .map(async (file) => {
+            const raw = await readFile(join(this.baseDir, file), 'utf8');
+            return JSON.parse(raw) as AgentSession;
+          })
+      )
+    ).filter(Boolean);
+
+    let items = sessions;
+    if (filter?.status) {
+      items = items.filter((s) => s.status === filter.status);
+    }
+    if (filter?.scoredOnly) {
+      items = items.filter((s) => s.score !== undefined);
+    }
+    if (filter?.limit) {
+      items = items.slice(0, filter.limit);
+    }
+    return items;
+  }
+
+  async delete(id: string): Promise<void> {
+    await rm(this.pathFor(id), { force: true });
+  }
+
+  async count(filter?: SessionFilter): Promise<number> {
+    return (await this.list(filter)).length;
+  }
+}

package/src/sessions/in-memory-session-store.ts

@@ -0,0 +1,39 @@
+import type { AgentSession, SessionFilter, SessionStore } from '../interfaces/session-store';
+
+export class InMemorySessionStore implements SessionStore {
+  private readonly sessions = new Map<string, AgentSession>();
+
+  async save(session: AgentSession): Promise<void> {
+    this.sessions.set(session.id, session);
+  }
+
+  async get(id: string): Promise<AgentSession | null> {
+    return this.sessions.get(id) ?? null;
+  }
+
+  async list(filter?: SessionFilter): Promise<AgentSession[]> {
+    let items = [...this.sessions.values()];
+
+    if (filter?.status) {
+      items = items.filter((s) => s.status === filter.status);
+    }
+
+    if (filter?.scoredOnly) {
+      items = items.filter((s) => s.score !== undefined);
+    }
+
+    if (filter?.limit) {
+      items = items.slice(0, filter.limit);
+    }
+
+    return items;
+  }
+
+  async delete(id: string): Promise<void> {
+    this.sessions.delete(id);
+  }
+
+  async count(filter?: SessionFilter): Promise<number> {
+    return (await this.list(filter)).length;
+  }
+}

package/src/sessions/session-manager.ts

@@ -0,0 +1,44 @@
+import { randomUUID } from 'node:crypto';
+
+import type { AgentSession, Message, SessionStore } from '../interfaces/session-store';
+
+export class SessionManager {
+  constructor(private readonly store: SessionStore) {}
+
+  async create(initialPrompt: string): Promise<AgentSession> {
+    const now = new Date();
+    const session: AgentSession = {
+      id: randomUUID(),
+      createdAt: now,
+      updatedAt: now,
+      messages: [{ role: 'user', content: initialPrompt }],
+      metadata: {},
+      status: 'running'
+    };
+    await this.store.save(session);
+    return session;
+  }
+
+  async appendMessage(sessionId: string, message: Message): Promise<AgentSession> {
+    const session = await this.store.get(sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    const updated: AgentSession = {
+      ...session,
+      updatedAt: new Date(),
+      messages: [...session.messages, message]
+    };
+    await this.store.save(updated);
+    return updated;
+  }
+
+  async checkpoint(session: AgentSession): Promise<void> {
+    await this.store.save({ ...session, updatedAt: new Date() });
+  }
+
+  async resume(sessionId: string): Promise<AgentSession | null> {
+    return this.store.get(sessionId);
+  }
+}

package/src/skills/skill-loader.ts

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+
+import type { SkillDefinition } from './skill-types';
+
+function parseFrontmatter(raw: string): { meta: Record<string, string>; body: string } {
+  if (!raw.startsWith('---\n')) {
+    return { meta: {}, body: raw };
+  }
+
+  const end = raw.indexOf('\n---\n', 4);
+  if (end === -1) {
+    return { meta: {}, body: raw };
+  }
+
+  const header = raw.slice(4, end).split('\n');
+  const meta: Record<string, string> = {};
+  for (const line of header) {
+    const idx = line.indexOf(':');
+    if (idx <= 0) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim().replace(/^"|"$/g, '');
+    meta[key] = value;
+  }
+
+  return {
+    meta,
+    body: raw.slice(end + 5).trim()
+  };
+}
+
+export async function loadSkillFromFile(path: string): Promise<SkillDefinition> {
+  const raw = await readFile(path, 'utf8');
+  const parsed = parseFrontmatter(raw);
+  const pythonDeps = parsed.meta.python_deps
+    ? parsed.meta.python_deps.split(',').map((item) => item.trim()).filter(Boolean)
+    : [];
+  const npmDeps = parsed.meta.npm_deps
+    ? parsed.meta.npm_deps.split(',').map((item) => item.trim()).filter(Boolean)
+    : [];
+
+  return {
+    name: parsed.meta.name ?? path.split('/').slice(-2, -1)[0] ?? 'unknown-skill',
+    description: parsed.meta.description ?? 'No description provided',
+    path,
+    contextMode: parsed.meta.context === 'fork' ? 'fork' : 'inline',
+    dependencies: {
+      python: pythonDeps,
+      npm: npmDeps
+    },
+    instructions: parsed.body
+  };
+}

package/src/skills/skill-manager.ts

@@ -0,0 +1,175 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import type { SandboxProvider } from '../interfaces/sandbox-provider';
+import type { HarnessTelemetry } from '../observability/otel';
+import { SkillSandboxProvider } from '../providers/skill-sandbox-provider';
+import { traceStep } from '../observability/tracing';
+import type { SkillDefinition, SkillInvokeResult, SkillSummary } from './skill-types';
+import { loadSkillFromFile } from './skill-loader';
+
+export class SkillManager {
+  private readonly summaries = new Map<string, SkillSummary>();
+  private readonly fullSkills = new Map<string, SkillDefinition>();
+  private readonly installState = new Map<string, 'ready' | 'degraded' | 'installing'>();
+
+  constructor(
+    private readonly sandbox: SandboxProvider = SkillSandboxProvider.fromEnv(),
+    private readonly telemetry?: HarnessTelemetry
+  ) {}
+
+  registerSummary(skill: SkillSummary): void {
+    this.summaries.set(skill.name, skill);
+  }
+
+  getSkillSummaryForPrompt(): SkillSummary[] {
+    return [...this.summaries.values()];
+  }
+
+  async discover(skillIndexPath: string): Promise<SkillSummary[]> {
+    const raw = await readFile(skillIndexPath, 'utf8');
+    const entries = JSON.parse(raw) as Array<{ name: string; description: string; path: string }>;
+    for (const entry of entries) {
+      this.registerSummary(entry);
+    }
+    return this.getSkillSummaryForPrompt();
+  }
+
+  private assertSafeSkillPath(path: string): void {
+    if (path.includes('..')) {
+      throw new Error('unsafe skill path');
+    }
+  }
+
+  private extractShellBlocks(instructions: string): string[] {
+    const blocks: string[] = [];
+    const regex = /```(?:bash|sh|shell)\n([\s\S]*?)```/g;
+    let match: RegExpExecArray | null;
+    while ((match = regex.exec(instructions)) !== null) {
+      const code = (match[1] ?? '').trim();
+      if (code.length > 0) {
+        blocks.push(code);
+      }
+    }
+    return blocks;
+  }
+
+  async invoke(
+    name: string,
+    options?: { mode?: 'execute' | 'instructions_only' }
+  ): Promise<SkillInvokeResult> {
+    return traceStep(this.telemetry, 'skill.exec', { skill: name }, async () => {
+      const summary = this.summaries.get(name);
+      if (!summary) {
+        throw new Error(`unknown skill: ${name}`);
+      }
+
+      this.assertSafeSkillPath(summary.path);
+
+      let full = this.fullSkills.get(name);
+      if (!full) {
+        full = await loadSkillFromFile(resolve(summary.path));
+        this.fullSkills.set(name, full);
+      }
+
+      const mode = options?.mode ?? 'execute';
+      if (mode === 'instructions_only') {
+        return {
+          skill: summary,
+          instructions: full.instructions ?? '',
+          execution: {
+            attempted: false,
+            success: true,
+            output: 'instructions_only mode',
+            commandsRun: 0
+          }
+        };
+      }
+
+      const shellBlocks = this.extractShellBlocks(full.instructions ?? '');
+      if (shellBlocks.length === 0) {
+        return {
+          skill: summary,
+          instructions: full.instructions ?? '',
+          execution: {
+            attempted: false,
+            success: true,
+            output: 'no executable shell blocks found',
+            commandsRun: 0
+          }
+        };
+      }
+
+      if (this.getInstallState(name) === 'unknown') {
+        await this.installDependencies(name);
+      }
+
+      let aggregateStdout = '';
+      for (const block of shellBlocks) {
+        const result = await this.sandbox.exec(block);
+        aggregateStdout += result.stdout;
+        if (result.exitCode !== 0) {
+          return {
+            skill: summary,
+            instructions: full.instructions ?? '',
+            execution: {
+              attempted: true,
+              success: false,
+              output: aggregateStdout,
+              error: result.stderr || 'skill block failed',
+              commandsRun: shellBlocks.length
+            }
+          };
+        }
+      }
+
+      return {
+        skill: summary,
+        instructions: full.instructions ?? '',
+        execution: {
+          attempted: true,
+          success: true,
+          output: aggregateStdout,
+          commandsRun: shellBlocks.length
+        }
+      };
+    });
+  }
+
+  async installDependencies(name: string): Promise<void> {
+    const skill = this.fullSkills.get(name);
+    if (!skill) {
+      throw new Error(`skill must be invoked before install: ${name}`);
+    }
+
+    this.installState.set(name, 'installing');
+
+    try {
+      const pythonDeps = skill.dependencies?.python ?? [];
+      const npmDeps = skill.dependencies?.npm ?? [];
+
+      for (const dep of pythonDeps) {
+        const result = await this.sandbox.exec(`pip install ${dep}`);
+        if (result.exitCode !== 0) {
+          throw new Error(result.stderr || `pip install failed for ${dep}`);
+        }
+      }
+
+      for (const dep of npmDeps) {
+        const result = await this.sandbox.exec(`npm install ${dep}`);
+        if (result.exitCode !== 0) {
+          throw new Error(result.stderr || `npm install failed for ${dep}`);
+        }
+      }
+
+      this.installState.set(name, 'ready');
+    } catch (error) {
+      this.installState.set(name, 'degraded');
+      throw error;
+    }
+  }
+
+  getInstallState(name: string): 'ready' | 'degraded' | 'installing' | 'unknown' {
+    return this.installState.get(name) ?? 'unknown';
+  }
+}

package/src/skills/skill-router.ts

@@ -0,0 +1,99 @@
+import { generateObject } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+import { z } from 'zod';
+
+import type { SkillSummary } from './skill-types';
+
+const routeSchema = z.object({
+  skillName: z.string().nullable(),
+  confidence: z.number().min(0).max(1),
+  rationale: z.string()
+});
+
+export interface SkillRouterConfig {
+  model?: string;
+  minConfidence?: number;
+  aliases?: Record<string, string[]>;
+}
+
+const DEFAULT_ALIASES: Record<string, string[]> = {
+  xlsx: ['excel', 'spreadsheet', 'workbook', 'csv'],
+  docx: ['word', 'document', 'doc'],
+  pptx: ['powerpoint', 'slides', 'presentation']
+};
+
+export class SkillRouter {
+  private readonly model: string;
+  private readonly minConfidence: number;
+  private readonly aliases: Record<string, string[]>;
+
+  constructor(config: SkillRouterConfig = {}) {
+    this.model = config.model ?? process.env.HARNESS_SKILL_ROUTER_MODEL ?? 'claude-3-5-haiku-latest';
+    this.minConfidence = config.minConfidence ?? Number(process.env.HARNESS_SKILL_ROUTER_THRESHOLD ?? '0.55');
+    this.aliases = {
+      ...DEFAULT_ALIASES,
+      ...(config.aliases ?? {})
+    };
+  }
+
+  async selectSkill(prompt: string, summaries: SkillSummary[]): Promise<SkillSummary | null> {
+    if (summaries.length === 0) return null;
+    const lower = prompt.toLowerCase();
+
+    const direct = summaries.find((skill) => this.containsToken(lower, skill.name.toLowerCase()));
+    if (direct) return direct;
+
+    for (const summary of summaries) {
+      const aliasList = this.aliases[summary.name.toLowerCase()] ?? [];
+      if (aliasList.some((alias) => this.containsToken(lower, alias.toLowerCase()))) {
+        return summary;
+      }
+    }
+
+    if (!process.env.ANTHROPIC_API_KEY) {
+      return null;
+    }
+
+    try {
+      const skillList = summaries
+        .map((s) => `- ${s.name}: ${s.description}`)
+        .join('\n');
+
+      const { object } = await generateObject({
+        model: anthropic(this.model),
+        schema: routeSchema,
+        system: [
+          'You are a skill router.',
+          'Pick at most one skill name from the provided list.',
+          'Only choose a skill when it clearly helps with the user request.',
+          'If nothing clearly matches, return null skillName and low confidence.'
+        ].join(' '),
+        prompt: [
+          'User request:',
+          prompt,
+          '',
+          'Available skills:',
+          skillList,
+          '',
+          'Return one object with skillName, confidence, rationale.'
+        ].join('\n')
+      });
+
+      if (!object.skillName || object.confidence < this.minConfidence) {
+        return null;
+      }
+
+      return summaries.find((s) => s.name === object.skillName) ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  private containsToken(haystack: string, needle: string): boolean {
+    if (!needle) return false;
+    const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp(`\\b${escaped}\\b`, 'i');
+    return regex.test(haystack);
+  }
+}
+

package/src/skills/skill-types.ts

@@ -0,0 +1,26 @@
+export interface SkillSummary {
+  name: string;
+  description: string;
+  path: string;
+}
+
+export interface SkillDefinition extends SkillSummary {
+  instructions?: string;
+  contextMode?: 'inline' | 'fork';
+  dependencies?: {
+    python?: string[];
+    npm?: string[];
+  };
+}
+
+export interface SkillInvokeResult {
+  skill: SkillSummary;
+  instructions: string;
+  execution?: {
+    attempted: boolean;
+    success: boolean;
+    output: string;
+    error?: string;
+    commandsRun?: number;
+  };
+}

package/src/subagents/subagent-manager.ts

@@ -0,0 +1,22 @@
+import { createAgent, type AgentRunResult, type AgentRuntime } from '../agent/create-agent';
+import type { HarnessTelemetry } from '../observability/otel';
+import { traceStep } from '../observability/tracing';
+
+export interface SubagentManager {
+  runIsolated(taskPrompt: string): Promise<AgentRunResult>;
+}
+
+export function createSubagentManager(
+  runtimeFactory: () => AgentRuntime,
+  telemetry?: HarnessTelemetry
+): SubagentManager {
+  return {
+    async runIsolated(taskPrompt: string): Promise<AgentRunResult> {
+      return traceStep(telemetry, 'subagent.run', { promptLength: taskPrompt.length }, async () => {
+        const runtime = runtimeFactory();
+        const agent = createAgent(runtime);
+        return agent.run(taskPrompt);
+      });
+    }
+  };
+}

package/src/subagents/task-tool.ts

@@ -0,0 +1,13 @@
+import type { AgentRunResult } from '../agent/create-agent';
+
+export interface TaskTool {
+  run(taskPrompt: string): Promise<AgentRunResult>;
+}
+
+export function createTaskTool(runSubagent: (taskPrompt: string) => Promise<AgentRunResult>): TaskTool {
+  return {
+    run(taskPrompt: string) {
+      return runSubagent(taskPrompt);
+    }
+  };
+}

package/tests/integration/agent-loop-basic.spec.ts

@@ -0,0 +1,56 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createAgent } from '../../src/agent/create-agent';
+import { LocalToolProvider } from '../../src/providers/local-tool-provider';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempDirs.map((dir) => rm(dir, { recursive: true, force: true })));
+  tempDirs.length = 0;
+});
+
+describe('agent loop basic', () => {
+  it('runs multi-step tool actions and returns final output', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'harness-agent-'));
+    tempDirs.push(dir);
+
+    const provider = new LocalToolProvider(dir);
+
+    let turn = 0;
+    const agent = createAgent({
+      toolProvider: provider,
+      async nextAction(messages) {
+        turn += 1;
+        if (turn === 1) {
+          return {
+            type: 'tool',
+            name: 'Write',
+            args: { path: 'hello.txt', content: 'hello harness' }
+          };
+        }
+
+        if (turn === 2) {
+          return {
+            type: 'tool',
+            name: 'Read',
+            args: { path: 'hello.txt' }
+          };
+        }
+
+        const toolMessage = [...messages].reverse().find((m: { role: string }) => m.role === 'tool');
+        return {
+          type: 'final',
+          content: `done: ${toolMessage?.content ?? 'missing'}`
+        };
+      }
+    });
+
+    const result = await agent.run('create file and read it');
+    expect(result.output).toContain('done: Read(hello.txt): hello harness');
+    expect(result.steps).toBe(3);
+  });
+});