@poncho-ai/client 0.2.0

package/.turbo/turbo-build.log

@@ -0,0 +1,14 @@
+
+> @poncho-ai/client@0.2.0 build /Users/cesar/Dev/latitude/poncho-ai/packages/client
+> 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 6.32 KB
+ESM ⚡️ Build success in 19ms
+DTS Build start
+DTS ⚡️ Build success in 977ms
+DTS dist/index.d.ts 1.83 KB

package/.turbo/turbo-test.log

@@ -0,0 +1,14 @@
+
+> @poncho-ai/client@0.1.0 test /Users/cesar/Dev/latitude/agentl/packages/client
+> vitest
+
+
+ RUN  v1.6.1 /Users/cesar/Dev/latitude/agentl/packages/client
+
+ ✓ test/client.test.ts  (3 tests) 5ms
+
+ Test Files  1 passed (1)
+      Tests  3 passed (3)
+   Start at  12:05:59
+   Duration  340ms (transform 43ms, setup 0ms, collect 50ms, tests 5ms, environment 0ms, prepare 64ms)
+

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @poncho-ai/client
+
+## 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,56 @@
+import { RunResult, RunInput, AgentEvent } from '@poncho-ai/sdk';
+
+interface AgentClientOptions {
+    url: string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}
+interface SyncRunResponse {
+    runId: string;
+    status: RunResult["status"];
+    result: RunResult;
+}
+interface ContinueInput {
+    runId: string;
+    message: string;
+    parameters?: Record<string, unknown>;
+}
+interface ConversationSummary {
+    conversationId: string;
+    title: string;
+    runtimeRunId?: string;
+    ownerId: string;
+    tenantId: string | null;
+    createdAt: number;
+    updatedAt: number;
+    messageCount: number;
+}
+interface ConversationRecord extends Omit<ConversationSummary, "messageCount"> {
+    messages: Array<{
+        role: "user" | "assistant";
+        content: string;
+    }>;
+}
+declare class AgentClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly fetchImpl;
+    constructor(options: AgentClientOptions);
+    private headers;
+    private parseSse;
+    listConversations(): Promise<ConversationSummary[]>;
+    createConversation(input?: {
+        title?: string;
+    }): Promise<ConversationRecord>;
+    getConversation(conversationId: string): Promise<ConversationRecord>;
+    deleteConversation(conversationId: string): Promise<void>;
+    sendMessage(conversationId: string, message: string, parameters?: Record<string, unknown>): Promise<SyncRunResponse>;
+    run(input: RunInput): Promise<SyncRunResponse>;
+    continue(input: ContinueInput): Promise<SyncRunResponse>;
+    conversation(initialRunId?: string): {
+        send: (message: string, parameters?: Record<string, unknown>) => Promise<SyncRunResponse>;
+    };
+    stream(input: RunInput): AsyncGenerator<AgentEvent>;
+}
+
+export { AgentClient, type AgentClientOptions, type ContinueInput, type ConversationRecord, type ConversationSummary, type SyncRunResponse };

package/dist/index.js

@@ -0,0 +1,203 @@
+// src/index.ts
+var trimTrailingSlash = (value) => value.replace(/\/+$/, "");
+var AgentClient = class {
+  baseUrl;
+  apiKey;
+  fetchImpl;
+  constructor(options) {
+    this.baseUrl = trimTrailingSlash(options.url);
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  headers() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) {
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    }
+    return headers;
+  }
+  async parseSse(response) {
+    if (!response.body) {
+      throw new Error("Missing response body");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const events = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      const frames = buffer.split("\n\n");
+      buffer = frames.pop() ?? "";
+      for (const frame of frames) {
+        const lines = frame.split("\n").map((line) => line.trim()).filter(Boolean);
+        const dataLine = lines.find((line) => line.startsWith("data:"));
+        if (!dataLine) {
+          continue;
+        }
+        const payload = JSON.parse(dataLine.slice("data:".length).trim());
+        events.push(payload);
+      }
+    }
+    return events;
+  }
+  async listConversations() {
+    const response = await this.fetchImpl(`${this.baseUrl}/api/conversations`, {
+      method: "GET",
+      headers: this.headers()
+    });
+    if (!response.ok) {
+      throw new Error(`List conversations failed: HTTP ${response.status}`);
+    }
+    const payload = await response.json();
+    return payload.conversations;
+  }
+  async createConversation(input) {
+    const response = await this.fetchImpl(`${this.baseUrl}/api/conversations`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(input ?? {})
+    });
+    if (!response.ok) {
+      throw new Error(`Create conversation failed: HTTP ${response.status}`);
+    }
+    const payload = await response.json();
+    return payload.conversation;
+  }
+  async getConversation(conversationId) {
+    const response = await this.fetchImpl(
+      `${this.baseUrl}/api/conversations/${encodeURIComponent(conversationId)}`,
+      {
+        method: "GET",
+        headers: this.headers()
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`Get conversation failed: HTTP ${response.status}`);
+    }
+    const payload = await response.json();
+    return payload.conversation;
+  }
+  async deleteConversation(conversationId) {
+    const response = await this.fetchImpl(
+      `${this.baseUrl}/api/conversations/${encodeURIComponent(conversationId)}`,
+      {
+        method: "DELETE",
+        headers: this.headers()
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`Delete conversation failed: HTTP ${response.status}`);
+    }
+  }
+  async sendMessage(conversationId, message, parameters) {
+    const response = await this.fetchImpl(
+      `${this.baseUrl}/api/conversations/${encodeURIComponent(conversationId)}/messages`,
+      {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify({ message, parameters })
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`Send message failed: HTTP ${response.status}`);
+    }
+    const events = await this.parseSse(response);
+    const runStarted = events.find(
+      (event) => event.type === "run:started"
+    );
+    const completed = events.find(
+      (event) => event.type === "run:completed"
+    );
+    if (!completed) {
+      throw new Error("Send message failed: missing run:completed event");
+    }
+    return {
+      runId: runStarted?.runId ?? completed.runId,
+      status: completed.result.status,
+      result: completed.result
+    };
+  }
+  async run(input) {
+    if ((input.messages?.length ?? 0) > 0) {
+      throw new Error(
+        "run() with pre-seeded messages is no longer supported. Use createConversation/sendMessage."
+      );
+    }
+    const conversation = await this.createConversation({
+      title: input.task
+    });
+    return await this.sendMessage(conversation.conversationId, input.task, input.parameters);
+  }
+  async continue(input) {
+    return await this.sendMessage(input.runId, input.message, input.parameters);
+  }
+  conversation(initialRunId) {
+    let runId = initialRunId;
+    return {
+      send: async (message, parameters) => {
+        if (!runId) {
+          const initialConversation = await this.createConversation({ title: message });
+          const initial = await this.sendMessage(
+            initialConversation.conversationId,
+            message,
+            parameters
+          );
+          runId = initialConversation.conversationId;
+          return initial;
+        }
+        const next = await this.continue({ runId, message, parameters });
+        return next;
+      }
+    };
+  }
+  async *stream(input) {
+    if ((input.messages?.length ?? 0) > 0) {
+      throw new Error(
+        "stream() with pre-seeded messages is no longer supported. Use conversation APIs directly."
+      );
+    }
+    const conversation = await this.createConversation({ title: input.task });
+    const response = await this.fetchImpl(
+      `${this.baseUrl}/api/conversations/${encodeURIComponent(conversation.conversationId)}/messages`,
+      {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify({ message: input.task, parameters: input.parameters })
+      }
+    );
+    if (!response.ok || !response.body) {
+      throw new Error(`Streaming request failed: HTTP ${response.status}`);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      const frames = buffer.split("\n\n");
+      buffer = frames.pop() ?? "";
+      for (const frame of frames) {
+        const lines = frame.split("\n").map((line) => line.trim()).filter(Boolean);
+        const eventType = lines.find((line) => line.startsWith("event:"));
+        const dataLine = lines.find((line) => line.startsWith("data:"));
+        if (!eventType || !dataLine) {
+          continue;
+        }
+        const payload = JSON.parse(dataLine.slice("data:".length).trim());
+        yield payload;
+      }
+    }
+  }
+};
+export {
+  AgentClient
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@poncho-ai/client",
+  "version": "0.2.0",
+  "description": "TypeScript client for calling deployed Poncho agents",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/latitude-dev/poncho-ai.git",
+    "directory": "packages/client"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@poncho-ai/sdk": "0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "vitest": "^1.4.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "client",
+    "sdk"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest",
+    "lint": "eslint src/"
+  }
+}

package/src/index.ts

@@ -0,0 +1,267 @@
+import type { AgentEvent, RunInput, RunResult } from "@poncho-ai/sdk";
+
+export interface AgentClientOptions {
+  url: string;
+  apiKey?: string;
+  fetchImpl?: typeof fetch;
+}
+
+export interface SyncRunResponse {
+  runId: string;
+  status: RunResult["status"];
+  result: RunResult;
+}
+
+export interface ContinueInput {
+  runId: string;
+  message: string;
+  parameters?: Record<string, unknown>;
+}
+
+export interface ConversationSummary {
+  conversationId: string;
+  title: string;
+  runtimeRunId?: string;
+  ownerId: string;
+  tenantId: string | null;
+  createdAt: number;
+  updatedAt: number;
+  messageCount: number;
+}
+
+export interface ConversationRecord extends Omit<ConversationSummary, "messageCount"> {
+  messages: Array<{ role: "user" | "assistant"; content: string }>;
+}
+
+const trimTrailingSlash = (value: string): string => value.replace(/\/+$/, "");
+
+export class AgentClient {
+  private readonly baseUrl: string;
+  private readonly apiKey?: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: AgentClientOptions) {
+    this.baseUrl = trimTrailingSlash(options.url);
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  private headers(): HeadersInit {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (this.apiKey) {
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    }
+    return headers;
+  }
+
+  private async parseSse(response: Response): Promise<AgentEvent[]> {
+    if (!response.body) {
+      throw new Error("Missing response body");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const events: AgentEvent[] = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      const frames = buffer.split("\n\n");
+      buffer = frames.pop() ?? "";
+      for (const frame of frames) {
+        const lines = frame
+          .split("\n")
+          .map((line) => line.trim())
+          .filter(Boolean);
+        const dataLine = lines.find((line) => line.startsWith("data:"));
+        if (!dataLine) {
+          continue;
+        }
+        const payload = JSON.parse(dataLine.slice("data:".length).trim()) as AgentEvent;
+        events.push(payload);
+      }
+    }
+    return events;
+  }
+
+  async listConversations(): Promise<ConversationSummary[]> {
+    const response = await this.fetchImpl(`${this.baseUrl}/api/conversations`, {
+      method: "GET",
+      headers: this.headers(),
+    });
+    if (!response.ok) {
+      throw new Error(`List conversations failed: HTTP ${response.status}`);
+    }
+    const payload = (await response.json()) as { conversations: ConversationSummary[] };
+    return payload.conversations;
+  }
+
+  async createConversation(input?: { title?: string }): Promise<ConversationRecord> {
+    const response = await this.fetchImpl(`${this.baseUrl}/api/conversations`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(input ?? {}),
+    });
+    if (!response.ok) {
+      throw new Error(`Create conversation failed: HTTP ${response.status}`);
+    }
+    const payload = (await response.json()) as { conversation: ConversationRecord };
+    return payload.conversation;
+  }
+
+  async getConversation(conversationId: string): Promise<ConversationRecord> {
+    const response = await this.fetchImpl(
+      `${this.baseUrl}/api/conversations/${encodeURIComponent(conversationId)}`,
+      {
+        method: "GET",
+        headers: this.headers(),
+      },
+    );
+    if (!response.ok) {
+      throw new Error(`Get conversation failed: HTTP ${response.status}`);
+    }
+    const payload = (await response.json()) as { conversation: ConversationRecord };
+    return payload.conversation;
+  }
+
+  async deleteConversation(conversationId: string): Promise<void> {
+    const response = await this.fetchImpl(
+      `${this.baseUrl}/api/conversations/${encodeURIComponent(conversationId)}`,
+      {
+        method: "DELETE",
+        headers: this.headers(),
+      },
+    );
+    if (!response.ok) {
+      throw new Error(`Delete conversation failed: HTTP ${response.status}`);
+    }
+  }
+
+  async sendMessage(
+    conversationId: string,
+    message: string,
+    parameters?: Record<string, unknown>,
+  ): Promise<SyncRunResponse> {
+    const response = await this.fetchImpl(
+      `${this.baseUrl}/api/conversations/${encodeURIComponent(conversationId)}/messages`,
+      {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify({ message, parameters }),
+      },
+    );
+    if (!response.ok) {
+      throw new Error(`Send message failed: HTTP ${response.status}`);
+    }
+    const events = await this.parseSse(response);
+    const runStarted = events.find(
+      (event): event is Extract<AgentEvent, { type: "run:started" }> =>
+        event.type === "run:started",
+    );
+    const completed = events.find(
+      (event): event is Extract<AgentEvent, { type: "run:completed" }> =>
+        event.type === "run:completed",
+    );
+    if (!completed) {
+      throw new Error("Send message failed: missing run:completed event");
+    }
+    return {
+      runId: runStarted?.runId ?? completed.runId,
+      status: completed.result.status,
+      result: completed.result,
+    };
+  }
+
+  async run(input: RunInput): Promise<SyncRunResponse> {
+    if ((input.messages?.length ?? 0) > 0) {
+      throw new Error(
+        "run() with pre-seeded messages is no longer supported. Use createConversation/sendMessage.",
+      );
+    }
+    const conversation = await this.createConversation({
+      title: input.task,
+    });
+    return await this.sendMessage(conversation.conversationId, input.task, input.parameters);
+  }
+
+  async continue(input: ContinueInput): Promise<SyncRunResponse> {
+    return await this.sendMessage(input.runId, input.message, input.parameters);
+  }
+
+  conversation(initialRunId?: string): {
+    send: (message: string, parameters?: Record<string, unknown>) => Promise<SyncRunResponse>;
+  } {
+    let runId = initialRunId;
+    return {
+      send: async (message: string, parameters?: Record<string, unknown>) => {
+        if (!runId) {
+          const initialConversation = await this.createConversation({ title: message });
+          const initial = await this.sendMessage(
+            initialConversation.conversationId,
+            message,
+            parameters,
+          );
+          runId = initialConversation.conversationId;
+          return initial;
+        }
+        const next = await this.continue({ runId, message, parameters });
+        return next;
+      },
+    };
+  }
+
+  async *stream(input: RunInput): AsyncGenerator<AgentEvent> {
+    if ((input.messages?.length ?? 0) > 0) {
+      throw new Error(
+        "stream() with pre-seeded messages is no longer supported. Use conversation APIs directly.",
+      );
+    }
+    const conversation = await this.createConversation({ title: input.task });
+    const response = await this.fetchImpl(
+      `${this.baseUrl}/api/conversations/${encodeURIComponent(conversation.conversationId)}/messages`,
+      {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({ message: input.task, parameters: input.parameters }),
+    });
+
+    if (!response.ok || !response.body) {
+      throw new Error(`Streaming request failed: HTTP ${response.status}`);
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+      const frames = buffer.split("\n\n");
+      buffer = frames.pop() ?? "";
+
+      for (const frame of frames) {
+        const lines = frame
+          .split("\n")
+          .map((line) => line.trim())
+          .filter(Boolean);
+
+        const eventType = lines.find((line) => line.startsWith("event:"));
+        const dataLine = lines.find((line) => line.startsWith("data:"));
+        if (!eventType || !dataLine) {
+          continue;
+        }
+
+        const payload = JSON.parse(dataLine.slice("data:".length).trim()) as AgentEvent;
+        yield payload;
+      }
+    }
+  }
+}

package/test/client.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import { AgentClient } from "../src/index.js";
+
+describe("AgentClient", () => {
+  const sseResponse = (): Response =>
+    new Response(
+      `event: run:started\n` +
+        `data: {"type":"run:started","runId":"run_1","agentId":"test-agent"}\n\n` +
+        `event: run:completed\n` +
+        `data: {"type":"run:completed","runId":"run_1","result":{"status":"completed","response":"ok","steps":1,"tokens":{"input":1,"output":1,"cached":0},"duration":1}}\n\n`,
+      {
+        status: 200,
+        headers: { "Content-Type": "text/event-stream" },
+      },
+    );
+
+  it("runs a message through conversation APIs", async () => {
+    let call = 0;
+    const client = new AgentClient({
+      url: "http://localhost:3000",
+      fetchImpl: async () => {
+        call += 1;
+        if (call === 1) {
+          return new Response(
+            JSON.stringify({
+              conversation: {
+                conversationId: "conv_1",
+                title: "hello",
+                ownerId: "local-owner",
+                tenantId: null,
+                createdAt: Date.now(),
+                updatedAt: Date.now(),
+                messages: [],
+              },
+            }),
+            {
+              status: 201,
+              headers: { "Content-Type": "application/json" },
+            },
+          );
+        }
+        return sseResponse();
+      },
+    });
+
+    const result = await client.run({ task: "hello" });
+    expect(result.runId).toBe("run_1");
+    expect(result.result.response).toBe("ok");
+  });
+
+  it("supports continue() via conversation message route", async () => {
+    const client = new AgentClient({
+      url: "http://localhost:3000",
+      fetchImpl: async () => sseResponse(),
+    });
+
+    const result = await client.continue({ runId: "conv_1", message: "next" });
+    expect(result.runId).toBe("run_1");
+    expect(result.result.response).toBe("ok");
+  });
+
+  it("lists conversations", async () => {
+    const client = new AgentClient({
+      url: "http://localhost:3000",
+      fetchImpl: async () =>
+        new Response(
+          JSON.stringify({
+            conversations: [
+              {
+                conversationId: "conv_1",
+                title: "Example",
+                runtimeRunId: "run_1",
+                ownerId: "local-owner",
+                tenantId: null,
+                createdAt: Date.now(),
+                updatedAt: Date.now(),
+                messageCount: 2,
+              },
+            ],
+          }),
+          {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          },
+        ),
+    });
+
+    const results = await client.listConversations();
+    expect(results).toHaveLength(1);
+    expect(results[0]?.conversationId).toBe("conv_1");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}