@botbotgo/agent-harness 0.0.62 → 0.0.63

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+type CliIo = {
+    cwd?: string;
+    stdout?: (message: string) => void;
+    stderr?: (message: string) => void;
+};
+export declare function runCli(argv: string[], io?: CliIo): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { initProject } from "./init-project.js";
+function renderUsage() {
+    return `Usage:
+  agent-harness init <project-name> [--template deep-research|single-agent] [--provider <provider>] [--model <model>] [--with-web-search|--no-web-search]
+`;
+}
+function isTemplate(value) {
+    return value === "deep-research" || value === "single-agent";
+}
+function parseInitOptions(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--with-web-search") {
+            options.withWebSearch = true;
+            continue;
+        }
+        if (arg === "--no-web-search") {
+            options.withWebSearch = false;
+            continue;
+        }
+        if (arg === "--template" || arg === "--provider" || arg === "--model") {
+            const value = args[index + 1];
+            if (!value) {
+                return { error: `Missing value for ${arg}` };
+            }
+            if (arg === "--template") {
+                if (!isTemplate(value)) {
+                    return { error: `Unsupported template: ${value}` };
+                }
+                options.template = value;
+            }
+            else if (arg === "--provider") {
+                options.provider = value;
+            }
+            else {
+                options.model = value;
+            }
+            index += 1;
+            continue;
+        }
+        return { error: `Unknown option: ${arg}` };
+    }
+    return { options };
+}
+export async function runCli(argv, io = {}) {
+    const cwd = io.cwd ?? process.cwd();
+    const stdout = io.stdout ?? ((message) => process.stdout.write(message));
+    const stderr = io.stderr ?? ((message) => process.stderr.write(message));
+    const [command, projectName, ...rest] = argv;
+    if (command === "init") {
+        if (!projectName?.trim()) {
+            stderr(renderUsage());
+            return 1;
+        }
+        const parsed = parseInitOptions(rest);
+        if (parsed.error) {
+            stderr(`${parsed.error}\n`);
+            stderr(renderUsage());
+            return 1;
+        }
+        try {
+            const projectRoot = path.resolve(cwd, projectName);
+            const result = await initProject(projectRoot, projectName, parsed.options);
+            stdout(`Created ${result.projectSlug} at ${result.projectRoot}\n`);
+            stdout("Next steps:\n");
+            stdout(`  cd ${projectName}\n`);
+            stdout("  npm install\n");
+            if ((parsed.options?.provider ?? "openai") === "openai") {
+                stdout("  export OPENAI_API_KEY=your_key_here\n");
+            }
+            stdout('  npm run start -- "Research a topic"\n');
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            stderr(`${message}\n`);
+            return 1;
+        }
+    }
+    stderr(renderUsage());
+    return 1;
+}
+const invokedPath = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : "";
+if (import.meta.url === invokedPath) {
+    const exitCode = await runCli(process.argv.slice(2));
+    process.exitCode = exitCode;
+}

package/dist/init-project.d.ts

@@ -0,0 +1,12 @@
+export type InitTemplate = "deep-research" | "single-agent";
+export type InitProjectOptions = {
+    template?: InitTemplate;
+    provider?: string;
+    model?: string;
+    withWebSearch?: boolean;
+};
+export type InitProjectResult = {
+    projectRoot: string;
+    projectSlug: string;
+};
+export declare function initProject(projectRoot: string, projectName: string, options?: InitProjectOptions): Promise<InitProjectResult>;

package/dist/init-project.js

@@ -0,0 +1,292 @@
+import path from "node:path";
+import { writeFile } from "node:fs/promises";
+import { AGENT_HARNESS_VERSION } from "./package-version.js";
+import { ensureDir, fileExists } from "./utils/fs.js";
+function toProjectSlug(projectName) {
+    const normalized = projectName
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return normalized || "agent-harness-app";
+}
+function toDisplayName(projectName) {
+    return projectName
+        .trim()
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+function resolveOptions(options = {}) {
+    return {
+        template: options.template ?? "deep-research",
+        provider: options.provider?.trim() || "openai",
+        model: options.model?.trim() || "gpt-4o-mini",
+        withWebSearch: options.withWebSearch ?? true,
+    };
+}
+function renderPackageJson(projectSlug, template) {
+    return `${JSON.stringify({
+        name: projectSlug,
+        version: "0.0.1",
+        private: true,
+        type: "module",
+        description: `Starter ${template} application generated by agent-harness init.`,
+        scripts: {
+            start: "node ./src/run.mjs",
+        },
+        dependencies: {
+            "@botbotgo/agent-harness": `^${AGENT_HARNESS_VERSION}`,
+        },
+    }, null, 2)}\n`;
+}
+function renderReadme(displayName, projectSlug, options) {
+    const webSearchLine = options.withWebSearch
+        ? `- ${options.provider} native web search enabled through \`config/tools.yaml\``
+        : "- no provider-native web search by default";
+    const providerEnvLine = options.provider === "openai" ? "export OPENAI_API_KEY=your_key_here\n" : "";
+    const templateLine = options.template === "deep-research"
+        ? "- a host research agent plus a specialist analyst subagent"
+        : "- a single host research agent for direct iteration";
+    return `# ${displayName}
+
+This project was scaffolded with \`agent-harness init ${projectSlug}\`.
+
+It is a minimal ${options.template} workspace with:
+
+${templateLine}
+${webSearchLine}
+
+## Run
+
+\`\`\`bash
+npm install
+${providerEnvLine}npm run start -- "Research the latest model serving stack for agent products and summarize the tradeoffs."
+\`\`\`
+
+## Structure
+
+- \`src/run.mjs\`: minimal launcher
+- \`config/\`: workspace runtime and agent topology
+- \`resources/\`: place local tools and skills here as your product grows
+
+## Customize
+
+- change \`config/models.yaml\` to switch models or providers
+- add local tools under \`resources/tools/\`
+- add product-specific skills under \`resources/skills/\`
+- edit the prompts in \`config/agents/\` to turn this into your own product
+`;
+}
+function renderGitignore() {
+    return `node_modules
+.agent
+`;
+}
+function renderWorkspaceYaml() {
+    return `apiVersion: agent-harness/v1alpha1
+kind: Runtime
+metadata:
+  name: default
+spec:
+  runRoot: ./.agent
+`;
+}
+function renderAgentContext(options) {
+    const webSearchGuidance = options.withWebSearch
+        ? "- Favor recent, attributable sources when the request depends on current information."
+        : "- Favor clear internal reasoning and add search or local tools as your product needs evolve.";
+    return `# Deep Research Workspace Context
+
+- This workspace is a starter for product-oriented research applications.
+${webSearchGuidance}
+- Synthesize findings clearly, call out uncertainty, and separate facts from inference.
+`;
+}
+function renderModelsYaml(options) {
+    return `apiVersion: agent-harness/v1alpha1
+kind: Models
+spec:
+  - name: default
+    kind: Model
+    provider: ${options.provider}
+    model: ${options.model}
+    temperature: 0.2
+`;
+}
+function renderBackendsYaml() {
+    return `apiVersion: agent-harness/v1alpha1
+kind: Backends
+spec:
+  - kind: Backend
+    name: default
+    description: Default DeepAgent backend preset for generated research apps.
+    backendKind: CompositeBackend
+    state:
+      kind: VfsSandbox
+      timeout: 600
+    routes:
+      /memories/:
+        kind: StoreBackend
+`;
+}
+function renderToolsYaml(options) {
+    if (!options.withWebSearch) {
+        return `apiVersion: agent-harness/v1alpha1
+kind: Tools
+spec: []
+`;
+    }
+    return `apiVersion: agent-harness/v1alpha1
+kind: Tools
+spec:
+  - kind: Tool
+    name: web-search
+    type: provider
+    description: ${options.provider} web search tool for current research.
+    providerTool:
+      provider: ${options.provider}
+      tool: webSearch
+      args:
+        searchContextSize: medium
+`;
+}
+function renderResearchAgentYaml(options) {
+    const toolsBlock = options.withWebSearch ? "    tools:\n      - ref: tool/web-search\n" : "    tools: []\n";
+    const subagentsBlock = options.template === "deep-research" ? "    subagents:\n      - ref: agent/research-analyst\n" : "    subagents: []\n";
+    const prompt = options.withWebSearch
+        ? "Break complex research requests into a clear plan, use web search when current information matters, and return a concise synthesis with sources and explicit uncertainty."
+        : "Break complex research requests into a clear plan and return a concise synthesis with explicit assumptions and uncertainty.";
+    const delegationLine = options.template === "deep-research"
+        ? " Delegate detailed investigation to the analyst when useful."
+        : "";
+    return `apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: research
+  description: Host-facing research agent for investigating and synthesizing answers.
+spec:
+  execution:
+    backend: deepagent
+    modelRef: model/default
+${toolsBlock}    skills:
+      - path: ./
+${subagentsBlock}    config:
+      backend:
+        ref: backend/default
+      systemPrompt: ${prompt}${delegationLine}
+`;
+}
+function renderResearchAnalystYaml(options) {
+    const toolsBlock = options.withWebSearch ? "    tools:\n      - ref: tool/web-search\n" : "    tools: []\n";
+    const prompt = options.withWebSearch
+        ? "Gather current sources, compare claims carefully, extract the most decision-relevant facts, and return clean notes the host agent can synthesize."
+        : "Break down the problem, compare alternatives carefully, extract the most decision-relevant facts, and return clean notes the host agent can synthesize.";
+    return `apiVersion: agent-harness/v1alpha1
+kind: Agent
+metadata:
+  name: research-analyst
+  description: Specialist subagent for source gathering, comparison, and evidence extraction.
+spec:
+  execution:
+    backend: deepagent
+    modelRef: model/default
+${toolsBlock}    skills:
+      - path: ./
+    config:
+      backend:
+        ref: backend/default
+      systemPrompt: ${prompt}
+`;
+}
+function renderResourcePackageJson(projectSlug) {
+    return `${JSON.stringify({
+        name: `${projectSlug}-resources`,
+        version: "0.0.1",
+        private: true,
+        type: "module",
+        description: "Resource package for a generated agent-harness project.",
+    }, null, 2)}\n`;
+}
+function renderSkill(options) {
+    const stepTwo = options.withWebSearch
+        ? "2. Use `web-search` to collect recent primary or otherwise authoritative sources."
+        : "2. Collect the key facts and assumptions needed to answer the request cleanly.";
+    return `---
+name: deep-research
+description: Default research workflow for product investigations that need careful synthesis.
+---
+
+# Deep Research
+
+Use this skill when the user wants comparisons, source-backed analysis, or a concise brief.
+
+## Workflow
+
+1. Clarify the target question and what "done" looks like.
+${stepTwo}
+3. Compare evidence instead of trusting a single source.
+4. Separate verified facts from inference.
+5. End with a concise synthesis, explicit caveats, and source links when available.
+`;
+}
+function renderRunScript(options) {
+    const defaultInput = options.withWebSearch
+        ? "Research the latest model and tooling trends for AI product teams. Return a concise brief with sources and caveats."
+        : "Analyze the current architecture direction for this product and return a concise brief with assumptions and caveats.";
+    return `import { fileURLToPath } from "node:url";
+import { createAgentHarness, run, stop } from "@botbotgo/agent-harness";
+
+const appRoot = fileURLToPath(new URL("..", import.meta.url));
+const input = process.argv.slice(2).join(" ").trim() ||
+  ${JSON.stringify(defaultInput)};
+
+const runtime = await createAgentHarness(appRoot);
+
+try {
+  const result = await run(runtime, {
+    agentId: "research",
+    input,
+  });
+  process.stdout.write(\`\${result.output}\\n\`);
+} finally {
+  await stop(runtime);
+}
+`;
+}
+export async function initProject(projectRoot, projectName, options = {}) {
+    if (await fileExists(projectRoot)) {
+        throw new Error(`Target path already exists: ${projectRoot}`);
+    }
+    const resolved = resolveOptions(options);
+    const projectSlug = toProjectSlug(projectName);
+    const displayName = toDisplayName(projectName) || "Agent Harness App";
+    const files = new Map([
+        ["package.json", renderPackageJson(projectSlug, resolved.template)],
+        [".gitignore", renderGitignore()],
+        ["README.md", renderReadme(displayName, projectSlug, resolved)],
+        ["src/run.mjs", renderRunScript(resolved)],
+        ["config/workspace.yaml", renderWorkspaceYaml()],
+        ["config/agent-context.md", renderAgentContext(resolved)],
+        ["config/models.yaml", renderModelsYaml(resolved)],
+        ["config/backends.yaml", renderBackendsYaml()],
+        ["config/tools.yaml", renderToolsYaml(resolved)],
+        ["config/agents/research.yaml", renderResearchAgentYaml(resolved)],
+        ["resources/package.json", renderResourcePackageJson(projectSlug)],
+        ["resources/skills/deep-research/SKILL.md", renderSkill(resolved)],
+    ]);
+    if (resolved.template === "deep-research") {
+        files.set("config/agents/research-analyst.yaml", renderResearchAnalystYaml(resolved));
+    }
+    await ensureDir(projectRoot);
+    for (const [relativePath, content] of files) {
+        const filePath = path.join(projectRoot, relativePath);
+        await ensureDir(path.dirname(filePath));
+        await writeFile(filePath, content, "utf8");
+    }
+    return {
+        projectRoot,
+        projectSlug,
+    };
+}

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.61";
+export declare const AGENT_HARNESS_VERSION = "0.0.62";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.61";
+export const AGENT_HARNESS_VERSION = "0.0.62";

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.62",
+  "version": "0.0.63",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "agent-harness": "./dist/cli.js"
+  },
   "files": [
     "dist"
   ],
@@ -50,7 +53,7 @@
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp -R config dist/",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run test/hello-file.test.ts test/public-api.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/stock-research-app-config.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/product-boundary-docs.test.ts test/docs-site.test.ts test/runtime-adapter-regressions.test.ts test/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/yaml-format.test.ts",
+    "test": "vitest run test/hello-file.test.ts test/public-api.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/stock-research-app-config.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/product-boundary-docs.test.ts test/docs-site.test.ts test/runtime-adapter-regressions.test.ts test/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/yaml-format.test.ts test/config-secrets.test.ts test/init-command.test.ts",
     "test:real-providers": "vitest run test/real-provider-harness.test.ts",
     "release:prepare": "npm version patch --no-git-tag-version && node ./scripts/sync-example-version.mjs",
     "release:pack": "npm pack --dry-run",