@poncho-ai/harness 0.2.0

package/.turbo/turbo-build.log

@@ -0,0 +1,14 @@
+
+> @poncho-ai/harness@0.2.0 build /Users/cesar/Dev/latitude/poncho-ai/packages/harness
+> tsup src/index.ts --format esm --dts
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Target: es2022
+ESM Build start
+ESM dist/index.js 93.22 KB
+ESM ⚡️ Build success in 31ms
+DTS Build start
+DTS ⚡️ Build success in 2649ms
+DTS dist/index.d.ts 13.93 KB

package/.turbo/turbo-test.log

@@ -0,0 +1,22 @@
+
+> @poncho-ai/harness@0.1.0 test /Users/cesar/Dev/latitude/agentl/packages/harness
+> vitest
+
+
+ RUN  v1.6.1 /Users/cesar/Dev/latitude/agentl/packages/harness
+
+[event] step:completed {"type":"step:completed","step":1,"duration":1}
+[event] step:started {"type":"step:started","step":2}
+ ✓ test/telemetry.test.ts  (3 tests) 5ms
+ ✓ test/state.test.ts  (4 tests) 20ms
+ ✓ test/mcp.test.ts  (1 test) 31ms
+ ✓ test/memory.test.ts  (4 tests) 11ms
+ ✓ test/agent-parser.test.ts  (2 tests) 8ms
+ ✓ test/model-factory.test.ts  (2 tests) 7ms
+ ✓ test/harness.test.ts  (15 tests) 57ms
+
+ Test Files  7 passed (7)
+      Tests  31 passed (31)
+   Start at  12:06:00
+   Duration  1.66s (transform 964ms, setup 0ms, collect 1.43s, tests 139ms, environment 1ms, prepare 3.37s)
+

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @poncho-ai/harness
+
+## 0.2.0
+
+### Minor Changes
+
+- Initial release of Poncho - an open framework for building and deploying AI agents.
+  - `@poncho-ai/sdk`: Core types and utilities for building Poncho skills
+  - `@poncho-ai/harness`: Agent execution runtime with conversation loop, tool dispatch, and streaming
+  - `@poncho-ai/client`: TypeScript client for calling deployed Poncho agents
+  - `@poncho-ai/cli`: CLI for building and deploying AI agents
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @poncho-ai/sdk@0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Latitude
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,416 @@
+import { Message, ToolDefinition, RunInput, AgentEvent, RunResult, ToolContext } from '@poncho-ai/sdk';
+export { ToolDefinition, defineTool } from '@poncho-ai/sdk';
+
+interface AgentModelConfig {
+    provider: string;
+    name: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+interface AgentLimitsConfig {
+    maxSteps?: number;
+    timeout?: number;
+}
+interface AgentFrontmatter {
+    name: string;
+    description?: string;
+    model?: AgentModelConfig;
+    limits?: AgentLimitsConfig;
+}
+interface ParsedAgent {
+    frontmatter: AgentFrontmatter;
+    body: string;
+}
+interface RuntimeRenderContext {
+    parameters?: Record<string, unknown>;
+    runtime?: {
+        workingDir?: string;
+        agentId?: string;
+        runId?: string;
+        environment?: string;
+    };
+}
+declare const parseAgentMarkdown: (content: string) => ParsedAgent;
+declare const parseAgentFile: (workingDir: string) => Promise<ParsedAgent>;
+declare const renderAgentPrompt: (agent: ParsedAgent, context?: RuntimeRenderContext) => string;
+
+interface ConversationState {
+    runId: string;
+    messages: Message[];
+    updatedAt: number;
+}
+interface StateStore {
+    get(runId: string): Promise<ConversationState | undefined>;
+    set(state: ConversationState): Promise<void>;
+    delete(runId: string): Promise<void>;
+}
+interface Conversation {
+    conversationId: string;
+    title: string;
+    messages: Message[];
+    runtimeRunId?: string;
+    ownerId: string;
+    tenantId: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+interface ConversationStore {
+    list(ownerId?: string): Promise<Conversation[]>;
+    get(conversationId: string): Promise<Conversation | undefined>;
+    create(ownerId?: string, title?: string): Promise<Conversation>;
+    update(conversation: Conversation): Promise<void>;
+    rename(conversationId: string, title: string): Promise<Conversation | undefined>;
+    delete(conversationId: string): Promise<boolean>;
+}
+type StateProviderName = "local" | "memory" | "redis" | "upstash" | "dynamodb";
+interface StateConfig {
+    provider?: StateProviderName;
+    ttl?: number;
+    url?: string;
+    token?: string;
+    table?: string;
+    region?: string;
+}
+declare class InMemoryStateStore implements StateStore {
+    private readonly store;
+    private readonly ttlMs?;
+    constructor(ttlSeconds?: number);
+    private isExpired;
+    get(runId: string): Promise<ConversationState | undefined>;
+    set(state: ConversationState): Promise<void>;
+    delete(runId: string): Promise<void>;
+}
+declare class InMemoryConversationStore implements ConversationStore {
+    private readonly conversations;
+    private readonly ttlMs?;
+    constructor(ttlSeconds?: number);
+    private isExpired;
+    private purgeExpired;
+    list(ownerId?: string): Promise<Conversation[]>;
+    get(conversationId: string): Promise<Conversation | undefined>;
+    create(ownerId?: string, title?: string): Promise<Conversation>;
+    update(conversation: Conversation): Promise<void>;
+    rename(conversationId: string, title: string): Promise<Conversation | undefined>;
+    delete(conversationId: string): Promise<boolean>;
+}
+declare const createStateStore: (config?: StateConfig, options?: {
+    workingDir?: string;
+}) => StateStore;
+declare const createConversationStore: (config?: StateConfig, options?: {
+    workingDir?: string;
+}) => ConversationStore;
+
+interface MainMemory {
+    content: string;
+    updatedAt: number;
+}
+interface MemoryConfig {
+    enabled?: boolean;
+    provider?: StateProviderName;
+    url?: string;
+    token?: string;
+    table?: string;
+    region?: string;
+    ttl?: number;
+    maxRecallConversations?: number;
+}
+interface MemoryStore {
+    getMainMemory(): Promise<MainMemory>;
+    updateMainMemory(input: {
+        content: string;
+        mode?: "replace" | "append";
+    }): Promise<MainMemory>;
+}
+declare const createMemoryStore: (agentId: string, config?: MemoryConfig, options?: {
+    workingDir?: string;
+}) => MemoryStore;
+declare const createMemoryTools: (store: MemoryStore, options?: {
+    maxRecallConversations?: number;
+}) => ToolDefinition[];
+
+interface RemoteMcpServerConfig {
+    name?: string;
+    url: string;
+    env?: string[];
+    timeoutMs?: number;
+    reconnectAttempts?: number;
+    reconnectDelayMs?: number;
+}
+interface McpConfig {
+    mcp?: RemoteMcpServerConfig[];
+}
+declare class LocalMcpBridge {
+    private readonly remoteServers;
+    private readonly rpcClients;
+    constructor(config: McpConfig | undefined);
+    loadTools(): Promise<ToolDefinition[]>;
+    startLocalServers(): Promise<void>;
+    stopLocalServers(): Promise<void>;
+    listServers(): RemoteMcpServerConfig[];
+    listRemoteServers(): RemoteMcpServerConfig[];
+    checkRemoteConnectivity(): Promise<Array<{
+        url: string;
+        ok: boolean;
+        error?: string;
+    }>>;
+    toSerializableConfig(): McpConfig;
+    getLocalServers(): never[];
+    private toToolDefinitions;
+}
+
+interface StorageConfig {
+    provider?: "local" | "memory" | "redis" | "upstash" | "dynamodb";
+    url?: string;
+    token?: string;
+    table?: string;
+    region?: string;
+    ttl?: number | {
+        conversations?: number;
+        memory?: number;
+    };
+    memory?: {
+        enabled?: boolean;
+        maxRecallConversations?: number;
+    };
+}
+type BuiltInToolToggles = {
+    list_directory?: boolean;
+    read_file?: boolean;
+    write_file?: boolean;
+};
+interface PonchoConfig extends McpConfig {
+    harness?: string;
+    tools?: {
+        defaults?: BuiltInToolToggles;
+        byEnvironment?: {
+            development?: BuiltInToolToggles;
+            staging?: BuiltInToolToggles;
+            production?: BuiltInToolToggles;
+        };
+    };
+    auth?: {
+        required?: boolean;
+        type?: "bearer" | "header" | "custom";
+        headerName?: string;
+        validate?: (token: string, req?: unknown) => Promise<boolean> | boolean;
+    };
+    state?: {
+        provider?: "local" | "memory" | "redis" | "upstash" | "dynamodb";
+        ttl?: number;
+        [key: string]: unknown;
+    };
+    memory?: MemoryConfig;
+    storage?: StorageConfig;
+    telemetry?: {
+        enabled?: boolean;
+        otlp?: string;
+        latitude?: {
+            apiKey?: string;
+            projectId?: string | number;
+            path?: string;
+            documentPath?: string;
+        };
+        handler?: (event: unknown) => Promise<void> | void;
+    };
+    skills?: Record<string, Record<string, unknown>>;
+    /** Extra directories (relative to project root) to scan for skills.
+     *  `skills/` and `.poncho/skills/` are always scanned. */
+    skillPaths?: string[];
+    build?: {
+        vercel?: Record<string, unknown>;
+        docker?: Record<string, unknown>;
+        lambda?: Record<string, unknown>;
+        fly?: Record<string, unknown>;
+    };
+}
+declare const resolveStateConfig: (config: PonchoConfig | undefined) => StateConfig | undefined;
+declare const resolveMemoryConfig: (config: PonchoConfig | undefined) => MemoryConfig | undefined;
+declare const loadPonchoConfig: (workingDir: string) => Promise<PonchoConfig | undefined>;
+
+declare const createDefaultTools: (workingDir: string) => ToolDefinition[];
+declare const createWriteTool: (workingDir: string) => ToolDefinition;
+
+interface HarnessOptions {
+    workingDir?: string;
+    environment?: "development" | "staging" | "production";
+    toolDefinitions?: ToolDefinition[];
+    approvalHandler?: (request: {
+        tool: string;
+        input: Record<string, unknown>;
+        runId: string;
+        step: number;
+        approvalId: string;
+    }) => Promise<boolean> | boolean;
+}
+interface HarnessRunOutput {
+    runId: string;
+    result: RunResult;
+    events: AgentEvent[];
+    messages: Message[];
+}
+declare class AgentHarness {
+    private readonly workingDir;
+    private readonly environment;
+    private modelClient;
+    private readonly dispatcher;
+    private readonly approvalHandler?;
+    private skillContextWindow;
+    private memoryStore?;
+    private parsedAgent?;
+    private mcpBridge?;
+    private getConfiguredToolFlag;
+    private isBuiltInToolEnabled;
+    private registerIfMissing;
+    private registerConfiguredBuiltInTools;
+    private shouldEnableWriteTool;
+    constructor(options?: HarnessOptions);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    listTools(): ToolDefinition[];
+    run(input: RunInput): AsyncGenerator<AgentEvent>;
+    runToCompletion(input: RunInput): Promise<HarnessRunOutput>;
+}
+
+interface LatitudeCaptureConfig {
+    apiKey?: string;
+    projectId?: string | number;
+    path?: string;
+    defaultPath?: string;
+}
+declare class LatitudeCapture {
+    private readonly apiKey?;
+    private telemetryPromise?;
+    private readonly projectId?;
+    private readonly path?;
+    constructor(config?: LatitudeCaptureConfig);
+    private initializeTelemetry;
+    capture<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+interface ModelResponse {
+    text: string;
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        input: Record<string, unknown>;
+    }>;
+    usage: {
+        input: number;
+        output: number;
+    };
+    rawContent: unknown[];
+}
+interface ModelCallInput {
+    systemPrompt: string;
+    messages: Message[];
+    tools: ToolDefinition[];
+    modelName: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+interface ModelClientOptions {
+    latitudeCapture?: LatitudeCapture;
+}
+type ModelStreamEvent = {
+    type: "chunk";
+    content: string;
+} | {
+    type: "final";
+    response: ModelResponse;
+};
+interface ModelClient {
+    generate(input: ModelCallInput): Promise<ModelResponse>;
+    generateStream?(input: ModelCallInput): AsyncGenerator<ModelStreamEvent>;
+}
+
+declare const createModelClient: (provider?: string, options?: ModelClientOptions) => ModelClient;
+
+declare class OpenAiModelClient implements ModelClient {
+    private readonly client;
+    private readonly latitudeCapture;
+    constructor(apiKey?: string, options?: ModelClientOptions);
+    generateStream(input: ModelCallInput): AsyncGenerator<ModelStreamEvent>;
+    generate(input: ModelCallInput): Promise<ModelResponse>;
+}
+
+/**
+ * Resolve the full list of skill directories to scan.
+ * Merges the defaults with any extra paths provided via config.
+ */
+declare const resolveSkillDirs: (workingDir: string, extraPaths?: string[]) => string[];
+interface SkillMetadata {
+    /** Unique skill name from frontmatter. */
+    name: string;
+    /** What the skill does and when to use it. */
+    description: string;
+    /** Tool hints declared in frontmatter (spec `allowed-tools` or legacy `tools`). */
+    tools: string[];
+    /** Absolute path to the skill directory. */
+    skillDir: string;
+    /** Absolute path to the SKILL.md file. */
+    skillPath: string;
+}
+/**
+ * @deprecated Use {@link SkillMetadata} instead. Kept for backward compatibility.
+ */
+type SkillContextEntry = SkillMetadata & {
+    instructions: string;
+};
+declare const loadSkillMetadata: (workingDir: string, extraSkillPaths?: string[]) => Promise<SkillMetadata[]>;
+declare const buildSkillContextWindow: (skills: SkillMetadata[]) => string;
+declare const loadSkillInstructions: (skill: SkillMetadata) => Promise<string>;
+declare const readSkillResource: (skill: SkillMetadata, relativePath: string) => Promise<string>;
+declare const loadSkillContext: (workingDir: string) => Promise<SkillContextEntry[]>;
+
+/**
+ * Creates the built-in skill tools that implement progressive disclosure
+ * per the Agent Skills specification (https://agentskills.io/integrate-skills).
+ *
+ * - `activate_skill`  — loads the full SKILL.md body on demand
+ * - `read_skill_resource` — reads a file from a skill directory (references, scripts, assets)
+ * - `list_skill_scripts` — lists runnable JavaScript/TypeScript scripts under scripts/
+ * - `run_skill_script` — executes a JavaScript/TypeScript module under scripts/
+ */
+declare const createSkillTools: (skills: SkillMetadata[]) => ToolDefinition[];
+
+interface TelemetryConfig {
+    enabled?: boolean;
+    otlp?: string;
+    latitude?: {
+        apiKey?: string;
+        projectId?: string | number;
+        path?: string;
+        documentPath?: string;
+    };
+    handler?: (event: AgentEvent) => Promise<void> | void;
+}
+declare class TelemetryEmitter {
+    private readonly config;
+    constructor(config?: TelemetryConfig);
+    emit(event: AgentEvent): Promise<void>;
+    private sendOtlp;
+    private sendLatitude;
+}
+
+interface ToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface ToolExecutionResult {
+    callId: string;
+    tool: string;
+    output?: unknown;
+    error?: string;
+}
+declare class ToolDispatcher {
+    private readonly tools;
+    register(tool: ToolDefinition): void;
+    registerMany(tools: ToolDefinition[]): void;
+    list(): ToolDefinition[];
+    get(name: string): ToolDefinition | undefined;
+    execute(call: ToolCall, context: ToolContext): Promise<ToolExecutionResult>;
+    executeBatch(calls: ToolCall[], context: ToolContext): Promise<ToolExecutionResult[]>;
+}
+
+export { type AgentFrontmatter, AgentHarness, type AgentLimitsConfig, type AgentModelConfig, type BuiltInToolToggles, type Conversation, type ConversationState, type ConversationStore, type HarnessOptions, type HarnessRunOutput, InMemoryConversationStore, InMemoryStateStore, LatitudeCapture, type LatitudeCaptureConfig, LocalMcpBridge, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type ModelCallInput, type ModelClient, type ModelClientOptions, type ModelResponse, type ModelStreamEvent, OpenAiModelClient, type ParsedAgent, type PonchoConfig, type RemoteMcpServerConfig, type RuntimeRenderContext, type SkillContextEntry, type SkillMetadata, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type TelemetryConfig, TelemetryEmitter, type ToolCall, ToolDispatcher, type ToolExecutionResult, buildSkillContextWindow, createConversationStore, createDefaultTools, createMemoryStore, createMemoryTools, createModelClient, createSkillTools, createStateStore, createWriteTool, loadPonchoConfig, loadSkillContext, loadSkillInstructions, loadSkillMetadata, parseAgentFile, parseAgentMarkdown, readSkillResource, renderAgentPrompt, resolveMemoryConfig, resolveSkillDirs, resolveStateConfig };