@poncho-ai/harness 0.20.13 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.20.13",
+  "version": "0.21.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",
@@ -46,8 +46,8 @@
   ],
   "license": "MIT",
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "build": "node scripts/embed-docs.js && tsup src/index.ts --format esm --dts",
+    "dev": "node scripts/embed-docs.js && tsup src/index.ts --format esm --dts --watch",
     "test": "vitest",
     "lint": "eslint src/"
   }

package/scripts/embed-docs.js

@@ -0,0 +1,26 @@
+import { readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, "..", "..", "..");
+const outDir = resolve(__dirname, "..", "src", "generated");
+
+const TOPICS = ["api", "features", "configuration", "troubleshooting"];
+
+const entries = TOPICS.map((topic) => {
+  const filePath = resolve(repoRoot, "docs", `${topic}.md`);
+  const content = readFileSync(filePath, "utf8");
+  const escaped = content.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$/g, "\\$");
+  return `  ${JSON.stringify(topic)}: \`${escaped}\``;
+});
+
+const output = `// Auto-generated by scripts/embed-docs.js — do not edit manually.
+export const PONCHO_DOCS: Record<string, string> = {
+${entries.join(",\n")},
+};
+`;
+
+mkdirSync(outDir, { recursive: true });
+writeFileSync(resolve(outDir, "poncho-docs.ts"), output, "utf8");
+console.log(`[embed-docs] Generated poncho-docs.ts with ${TOPICS.length} topics`);

package/src/config.ts

@@ -130,6 +130,11 @@ export interface PonchoConfig extends McpConfig {
         sessionName?: string;
         executablePath?: string;
         headless?: boolean;
+        /** Custom user-agent string. When stealth is enabled (default) a
+         *  realistic Chrome UA is used automatically. */
+        userAgent?: string;
+        /** Reduce bot-detection fingerprints. Defaults to `true`. */
+        stealth?: boolean;
       };
 }
 

package/src/default-tools.ts

@@ -1,6 +1,7 @@
 import { mkdir, readdir, readFile, rm, unlink, writeFile } from "node:fs/promises";
 import { dirname, resolve, sep } from "node:path";
 import { defineTool, type ToolDefinition } from "@poncho-ai/sdk";
+import { PONCHO_DOCS } from "./generated/poncho-docs.js";
 
 const resolveSafePath = (workingDir: string, inputPath: string): string => {
   const base = resolve(workingDir);
@@ -136,4 +137,33 @@ export const createDeleteDirectoryTool = (workingDir: string): ToolDefinition =>
       await rm(resolved, { recursive: true });
       return { path, deleted: true };
     },
-  });
+  });
+
+const PONCHO_DOCS_TOPICS = Object.keys(PONCHO_DOCS);
+
+export const ponchoDocsTool: ToolDefinition = defineTool({
+  name: "poncho_docs",
+  description:
+    "Read detailed Poncho framework documentation by topic. " +
+    `Available topics: ${PONCHO_DOCS_TOPICS.join(", ")}.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      topic: {
+        type: "string",
+        enum: PONCHO_DOCS_TOPICS,
+        description: "Documentation topic to read",
+      },
+    },
+    required: ["topic"],
+    additionalProperties: false,
+  },
+  handler: async (input) => {
+    const topic = typeof input.topic === "string" ? input.topic : "";
+    const content = PONCHO_DOCS[topic];
+    if (!content) {
+      return { error: `Unknown topic "${topic}". Available: ${PONCHO_DOCS_TOPICS.join(", ")}` };
+    }
+    return { topic, content };
+  },
+});

package/src/harness.ts

@@ -15,7 +15,7 @@ import type { UploadStore } from "./upload-store.js";
 import { PONCHO_UPLOAD_SCHEME, deriveUploadKey } from "./upload-store.js";
 import { parseAgentFile, renderAgentPrompt, type ParsedAgent, type AgentFrontmatter } from "./agent-parser.js";
 import { loadPonchoConfig, resolveMemoryConfig, type PonchoConfig, type ToolAccess, type BuiltInToolToggles } from "./config.js";
-import { createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createWriteTool } from "./default-tools.js";
+import { createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createWriteTool, ponchoDocsTool } from "./default-tools.js";
 import {
   createMemoryStore,
   createMemoryTools,
@@ -479,7 +479,15 @@ Since all fields have defaults, you only need to specify \`*Env\` when your env
 - If shell/CLI access is unavailable, ask the user to run needed commands and provide exact copy-paste commands.
 - For setup, skills, MCP, auth, storage, telemetry, or "how do I..." questions, proactively read \`README.md\` with \`read_file\` before answering.
 - Prefer quoting concrete commands and examples from \`README.md\` over guessing.
-- Keep edits minimal, preserve unrelated settings/code, and summarize what changed.`;
+- Keep edits minimal, preserve unrelated settings/code, and summarize what changed.
+
+## Detailed Documentation
+
+For topics not covered above, use the \`poncho_docs\` tool to load full documentation on demand:
+- \`api\` — HTTP API endpoints, SSE events, TypeScript client SDK, file attachments, upload providers
+- \`features\` — Web UI details, browser automation, subagents, persistent memory, custom messaging adapters
+- \`configuration\` — Full config reference, env vars, auth types, storage, telemetry, tool approval
+- \`troubleshooting\` — Error codes, recoverable vs fatal errors, common issues and fixes`;
 
 /**
  * Detect FileContentPart objects ({ type:"file", data, mediaType }) in a tool
@@ -624,6 +632,9 @@ export class AgentHarness {
     if (this.isToolEnabled("delete_directory")) {
       this.registerIfMissing(createDeleteDirectoryTool(this.workingDir));
     }
+    if (this.environment === "development" && this.isToolEnabled("poncho_docs")) {
+      this.registerIfMissing(ponchoDocsTool);
+    }
   }
 
   private shouldEnableWriteTool(): boolean {

package/.turbo/turbo-lint.log

@@ -1,6 +0,0 @@
-
-> @poncho-ai/harness@0.11.2 lint /Users/cesar/Dev/latitude/poncho-ai/packages/harness
-> eslint src/
-
-sh: eslint: command not found
- ELIFECYCLE  Command failed.

package/.turbo/turbo-test.log

@@ -1,135 +0,0 @@
-
-> @poncho-ai/harness@0.16.1 test /Users/cesar/Dev/latitude/poncho-ai/packages/harness
-> vitest
-
-
- RUN  v1.6.1 /Users/cesar/Dev/latitude/poncho-ai/packages/harness
-
- ✓ test/telemetry.test.ts  (3 tests) 2ms
-[event] step:completed {"type":"step:completed","step":1,"duration":1}
-[event] step:started {"type":"step:started","step":2}
- ✓ test/schema-converter.test.ts  (27 tests) 19ms
-stdout | test/mcp.test.ts > mcp bridge protocol transports > discovers and calls tools over streamable HTTP
-[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":1}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-
-stdout | test/mcp.test.ts > mcp bridge protocol transports > selects discovered tools by requested patterns
-[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":2}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":1}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":2,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-
- ✓ test/agent-parser.test.ts  (10 tests) 24ms
-stdout | test/mcp.test.ts > mcp bridge protocol transports > skips discovery when bearer token env value is missing
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":0,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-
-stderr | test/mcp.test.ts > mcp bridge protocol transports > skips discovery when bearer token env value is missing
-[poncho][mcp] {"event":"auth.token_missing","server":"remote","tokenEnv":"MISSING_TOKEN_ENV"}
-
-stdout | test/mcp.test.ts > mcp bridge protocol transports > returns actionable errors for 403 permission failures
-[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":1}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-
- ✓ test/mcp.test.ts  (6 tests) 81ms
- ✓ test/memory.test.ts  (4 tests) 56ms
- ✓ test/state.test.ts  (5 tests) 237ms
- ✓ test/model-factory.test.ts  (4 tests) 2ms
- ✓ test/agent-identity.test.ts  (2 tests) 43ms
-stdout | test/harness.test.ts > agent harness > registers default filesystem tools
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > disables write_file by default in production environment
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > allows disabling built-in tools via poncho.config.js
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > supports per-environment tool overrides
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > supports per-environment tool overrides
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > does not auto-register exported tool objects from skill scripts
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > refreshes skill metadata and tools in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > refreshes skill metadata and tools in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"skills:changed","requestedPatterns":[]}
-[poncho][mcp] {"event":"tools.cleared","reason":"activate:beta","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > prunes removed active skills after refresh in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-[poncho][mcp] {"event":"tools.cleared","reason":"activate:obsolete","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > prunes removed active skills after refresh in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"skills:changed","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > does not refresh skills outside development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > clears active skills when skill metadata changes in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-[poncho][mcp] {"event":"tools.cleared","reason":"activate:alpha","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > clears active skills when skill metadata changes in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"skills:changed","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > lists skill scripts through list_skill_scripts
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > runs JavaScript/TypeScript skill scripts through run_skill_script
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > runs AGENT-scope scripts from root scripts directory
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > blocks path traversal in run_skill_script
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > requires allowed-tools entries for non-standard script directories
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > registers MCP tools dynamically for stacked active skills and supports deactivation
-[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":2}
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":1}
-[poncho][mcp] {"event":"tools.refreshed","reason":"activate:skill-a","requestedPatterns":["remote/a"],"registeredCount":1,"activeSkills":["skill-a"]}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":2,"registeredCount":2,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-[poncho][mcp] {"event":"tools.refreshed","reason":"activate:skill-b","requestedPatterns":["remote/a","remote/b"],"registeredCount":2,"activeSkills":["skill-a","skill-b"]}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":1}
-[poncho][mcp] {"event":"tools.refreshed","reason":"deactivate:skill-a","requestedPatterns":["remote/b"],"registeredCount":1,"activeSkills":["skill-b"]}
-
-stdout | test/harness.test.ts > agent harness > supports flat tool access config format
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > flat tool access takes priority over legacy defaults
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > byEnvironment overrides flat tool access
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > registerTools skips tools disabled via config
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > approval access level registers the tool but marks it for approval
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > tools without approval config do not require approval
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > allows in-flight MCP calls to finish after skill deactivation
-[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":1}
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-[poncho][mcp] {"event":"tools.refreshed","reason":"activate:skill-slow","requestedPatterns":["remote/slow"],"registeredCount":1,"activeSkills":["skill-slow"]}
-[poncho][mcp] {"event":"tools.cleared","reason":"deactivate:skill-slow","requestedPatterns":[]}
-
- ✓ test/harness.test.ts  (25 tests) 291ms
-
- Test Files  9 passed (9)
-      Tests  86 passed (86)
-   Start at  17:47:43
-   Duration  1.88s (transform 684ms, setup 1ms, collect 2.34s, tests 755ms, environment 2ms, prepare 1.27s)
-