@poncho-ai/harness 0.42.0 → 0.43.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.42.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.43.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -8,9 +8,9 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js            504.78 KB
 ESM dist/isolate-VY35DGLM.js 49.43 KB
-ESM ⚡️ Build success in 228ms
+ESM dist/index.js            506.40 KB
+ESM ⚡️ Build success in 222ms
 DTS Build start
-DTS ⚡️ Build success in 7856ms
-DTS dist/index.d.ts 79.11 KB
+DTS ⚡️ Build success in 6907ms
+DTS dist/index.d.ts 80.85 KB

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @poncho-ai/harness
 
+## 0.43.0
+
+### Minor Changes
+
+- [`ff89631`](https://github.com/cesr/poncho-ai/commit/ff89631715e54d6fdce174943e6e0fc9e4ce5d1e) Thanks [@cesr](https://github.com/cesr)! - harness: export `defaultAgentDefinition` so SDK consumers can match `poncho init` exactly
+
+  Lifts the `AGENT_TEMPLATE` markdown body from `@poncho-ai/cli` (where it lived
+  inside the `init` scaffolding) into a public helper on `@poncho-ai/harness`.
+  SDK consumers (PonchOS, custom servers, anyone calling
+  `new AgentHarness({ agentDefinition })` directly) can now do:
+
+  ```ts
+  import { defaultAgentDefinition } from "@poncho-ai/harness";
+
+  const harness = new AgentHarness({
+    agentDefinition: defaultAgentDefinition({
+      name: "poncho",
+      modelName: "claude-sonnet-4-6",
+    }),
+    // ... storageEngine, config, etc.
+  });
+  ```
+
+  This eliminates hand-copying the template — drift between consumers and
+  `poncho init` is no longer possible.
+
+  The CLI's `AGENT_TEMPLATE` export is preserved as a thin back-compat
+  wrapper that delegates to `defaultAgentDefinition`. No behavior change.
+
+  API additions (harness):
+  - `defaultAgentDefinition(opts?: DefaultAgentDefinitionOptions): string`
+  - `DefaultAgentDefinitionOptions`
+  - `DEFAULT_AGENT_NAME`, `DEFAULT_AGENT_DESCRIPTION`,
+    `DEFAULT_MODEL_PROVIDER`, `DEFAULT_MODEL_NAME`, `DEFAULT_TEMPERATURE`,
+    `DEFAULT_MAX_STEPS`, `DEFAULT_TIMEOUT` constants
+
 ## 0.42.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -685,6 +685,43 @@ declare const resolveStateConfig: (config: PonchoConfig | undefined) => StateCon
 declare const resolveMemoryConfig: (config: PonchoConfig | undefined) => MemoryConfig | undefined;
 declare const loadPonchoConfig: (workingDir: string) => Promise<PonchoConfig | undefined>;
 
+interface DefaultAgentDefinitionOptions {
+    /** Display name for the agent. Default: "agent". */
+    name?: string;
+    /**
+     * Stable identifier embedded in the frontmatter. Default: a fresh
+     * `agent_<32hex>`. Note: when an injected `StorageEngine` is also passed
+     * to `AgentHarness`, the engine's `agentId` overrides this at runtime, so
+     * SDK consumers can leave it default.
+     */
+    id?: string;
+    /** Frontmatter description. Default: "A helpful Poncho assistant". */
+    description?: string;
+    /** Model provider. Default: "anthropic". */
+    modelProvider?: "anthropic" | "openai" | "openai-codex";
+    /** Model name. Default: "claude-opus-4-5". */
+    modelName?: string;
+    /** Sampling temperature. Default: 0.2. */
+    temperature?: number;
+    /** Max tool-call steps per run. Default: 20. */
+    maxSteps?: number;
+    /** Hard timeout in seconds. Default: 300. */
+    timeout?: number;
+}
+declare const DEFAULT_AGENT_NAME = "agent";
+declare const DEFAULT_AGENT_DESCRIPTION = "A helpful Poncho assistant";
+declare const DEFAULT_MODEL_PROVIDER: "anthropic";
+declare const DEFAULT_MODEL_NAME = "claude-opus-4-5";
+declare const DEFAULT_TEMPERATURE = 0.2;
+declare const DEFAULT_MAX_STEPS = 20;
+declare const DEFAULT_TIMEOUT = 300;
+/**
+ * Returns the canonical default agent definition as a markdown string,
+ * ready to pass to `new AgentHarness({ agentDefinition })`. This is the
+ * exact same template `poncho init` writes to `AGENT.md`.
+ */
+declare const defaultAgentDefinition: (opts?: DefaultAgentDefinitionOptions) => string;
+
 declare const createDefaultTools: (workingDir: string) => ToolDefinition[];
 declare const createWriteTool: (workingDir: string) => ToolDefinition;
 declare const createEditTool: (workingDir: string) => ToolDefinition;
@@ -1925,4 +1962,4 @@ interface RunConversationTurnResult {
 }
 declare const runConversationTurn: (opts: RunConversationTurnOpts) => Promise<RunConversationTurnResult>;
 
-export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type NetworkConfig, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentSpawnResult, type SubagentSummary, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };
+export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type NetworkConfig, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentSpawnResult, type SubagentSummary, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };

package/dist/index.js

@@ -565,6 +565,53 @@ var loadPonchoConfig = async (workingDir) => {
   }
 };
 
+// src/default-agent.ts
+import { randomBytes } from "crypto";
+var DEFAULT_AGENT_NAME = "agent";
+var DEFAULT_AGENT_DESCRIPTION = "A helpful Poncho assistant";
+var DEFAULT_MODEL_PROVIDER = "anthropic";
+var DEFAULT_MODEL_NAME = "claude-opus-4-5";
+var DEFAULT_TEMPERATURE = 0.2;
+var DEFAULT_MAX_STEPS = 20;
+var DEFAULT_TIMEOUT = 300;
+var defaultAgentDefinition = (opts = {}) => {
+  const name = opts.name ?? DEFAULT_AGENT_NAME;
+  const id = opts.id ?? `agent_${randomBytes(16).toString("hex")}`;
+  const description = opts.description ?? DEFAULT_AGENT_DESCRIPTION;
+  const modelProvider = opts.modelProvider ?? DEFAULT_MODEL_PROVIDER;
+  const modelName = opts.modelName ?? DEFAULT_MODEL_NAME;
+  const temperature = opts.temperature ?? DEFAULT_TEMPERATURE;
+  const maxSteps = opts.maxSteps ?? DEFAULT_MAX_STEPS;
+  const timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+  return `---
+name: ${name}
+id: ${id}
+description: ${description}
+model:
+  provider: ${modelProvider}
+  name: ${modelName}
+  temperature: ${temperature}
+limits:
+  maxSteps: ${maxSteps}
+  timeout: ${timeout}
+---
+
+# {{name}}
+
+You are **{{name}}**, a helpful assistant built with Poncho.
+
+Working directory: {{runtime.workingDir}}
+Environment: {{runtime.environment}}
+
+## Task Guidance
+
+- Use tools when needed
+- Explain your reasoning clearly
+- Ask clarifying questions when requirements are ambiguous
+- Never claim a file/tool change unless the corresponding tool call actually succeeded
+`;
+};
+
 // src/default-tools.ts
 import { mkdir, readdir, readFile as readFile3, rm, unlink, writeFile as writeFile2 } from "fs/promises";
 import { dirname, resolve as resolve4, sep } from "path";
@@ -5562,14 +5609,14 @@ var createTodoTools = (store) => {
 };
 
 // src/secrets-store.ts
-import { createCipheriv, createDecipheriv, randomBytes, createHash as createHash3 } from "crypto";
+import { createCipheriv, createDecipheriv, randomBytes as randomBytes2, createHash as createHash3 } from "crypto";
 import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile4 } from "fs/promises";
 import { dirname as dirname3, resolve as resolve7 } from "path";
 function deriveKey(signingKey) {
   return createHash3("sha256").update("poncho-secrets-v1:" + signingKey).digest();
 }
 function encrypt(plaintext, key) {
-  const iv = randomBytes(12);
+  const iv = randomBytes2(12);
   const cipher = createCipheriv("aes-256-gcm", key, iv);
   const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
   const tag = cipher.getAuthTag();
@@ -13307,6 +13354,13 @@ export {
   AgentOrchestrator,
   BashEnvironmentManager,
   CALLBACK_LOCK_STALE_MS,
+  DEFAULT_AGENT_DESCRIPTION,
+  DEFAULT_AGENT_NAME,
+  DEFAULT_MAX_STEPS,
+  DEFAULT_MODEL_NAME,
+  DEFAULT_MODEL_PROVIDER,
+  DEFAULT_TEMPERATURE,
+  DEFAULT_TIMEOUT,
   InMemoryConversationStore,
   InMemoryEngine,
   InMemoryStateStore,
@@ -13363,6 +13417,7 @@ export {
   createTurnDraftState,
   createUploadStore,
   createWriteTool,
+  defaultAgentDefinition,
   defineTool13 as defineTool,
   deleteOpenAICodexSession,
   deriveUploadKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

package/src/default-agent.ts

@@ -0,0 +1,89 @@
+// ---------------------------------------------------------------------------
+// Canonical default agent definition.
+//
+// This is the same agent.md a fresh `poncho init` produces. The CLI's
+// AGENT_TEMPLATE in `packages/cli/src/templates.ts` delegates to this helper
+// so there is exactly one source of truth, and SDK consumers (PonchOS, custom
+// servers, etc.) can pass the same default to `new AgentHarness({ agentDefinition: ... })`
+// without hand-copying the template.
+// ---------------------------------------------------------------------------
+
+import { randomBytes } from "node:crypto";
+
+export interface DefaultAgentDefinitionOptions {
+  /** Display name for the agent. Default: "agent". */
+  name?: string;
+  /**
+   * Stable identifier embedded in the frontmatter. Default: a fresh
+   * `agent_<32hex>`. Note: when an injected `StorageEngine` is also passed
+   * to `AgentHarness`, the engine's `agentId` overrides this at runtime, so
+   * SDK consumers can leave it default.
+   */
+  id?: string;
+  /** Frontmatter description. Default: "A helpful Poncho assistant". */
+  description?: string;
+  /** Model provider. Default: "anthropic". */
+  modelProvider?: "anthropic" | "openai" | "openai-codex";
+  /** Model name. Default: "claude-opus-4-5". */
+  modelName?: string;
+  /** Sampling temperature. Default: 0.2. */
+  temperature?: number;
+  /** Max tool-call steps per run. Default: 20. */
+  maxSteps?: number;
+  /** Hard timeout in seconds. Default: 300. */
+  timeout?: number;
+}
+
+export const DEFAULT_AGENT_NAME = "agent";
+export const DEFAULT_AGENT_DESCRIPTION = "A helpful Poncho assistant";
+export const DEFAULT_MODEL_PROVIDER = "anthropic" as const;
+export const DEFAULT_MODEL_NAME = "claude-opus-4-5";
+export const DEFAULT_TEMPERATURE = 0.2;
+export const DEFAULT_MAX_STEPS = 20;
+export const DEFAULT_TIMEOUT = 300;
+
+/**
+ * Returns the canonical default agent definition as a markdown string,
+ * ready to pass to `new AgentHarness({ agentDefinition })`. This is the
+ * exact same template `poncho init` writes to `AGENT.md`.
+ */
+export const defaultAgentDefinition = (
+  opts: DefaultAgentDefinitionOptions = {},
+): string => {
+  const name = opts.name ?? DEFAULT_AGENT_NAME;
+  const id = opts.id ?? `agent_${randomBytes(16).toString("hex")}`;
+  const description = opts.description ?? DEFAULT_AGENT_DESCRIPTION;
+  const modelProvider = opts.modelProvider ?? DEFAULT_MODEL_PROVIDER;
+  const modelName = opts.modelName ?? DEFAULT_MODEL_NAME;
+  const temperature = opts.temperature ?? DEFAULT_TEMPERATURE;
+  const maxSteps = opts.maxSteps ?? DEFAULT_MAX_STEPS;
+  const timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+
+  return `---
+name: ${name}
+id: ${id}
+description: ${description}
+model:
+  provider: ${modelProvider}
+  name: ${modelName}
+  temperature: ${temperature}
+limits:
+  maxSteps: ${maxSteps}
+  timeout: ${timeout}
+---
+
+# {{name}}
+
+You are **{{name}}**, a helpful assistant built with Poncho.
+
+Working directory: {{runtime.workingDir}}
+Environment: {{runtime.environment}}
+
+## Task Guidance
+
+- Use tools when needed
+- Explain your reasoning clearly
+- Ask clarifying questions when requirements are ambiguous
+- Never claim a file/tool change unless the corresponding tool call actually succeeded
+`;
+};

package/src/index.ts

@@ -2,6 +2,7 @@ export * from "./agent-parser.js";
 export * from "./agent-identity.js";
 export * from "./compaction.js";
 export * from "./config.js";
+export * from "./default-agent.js";
 export * from "./default-tools.js";
 export * from "./harness.js";
 export * from "./memory.js";