@poncho-ai/sdk 0.2.0

package/.turbo/turbo-build.log

@@ -0,0 +1,14 @@
+
+> @poncho-ai/sdk@0.2.0 build /Users/cesar/Dev/latitude/poncho-ai/packages/sdk
+> 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 5.65 KB
+ESM ⚡️ Build success in 40ms
+DTS Build start
+DTS ⚡️ Build success in 937ms
+DTS dist/index.d.ts 11.57 KB

package/.turbo/turbo-test.log

@@ -0,0 +1,14 @@
+
+> @poncho-ai/sdk@0.1.0 test /Users/cesar/Dev/latitude/agentl/packages/sdk
+> vitest
+
+
+ RUN  v1.6.1 /Users/cesar/Dev/latitude/agentl/packages/sdk
+
+ ✓ test/sdk.test.ts  (1 test) 2ms
+
+ Test Files  1 passed (1)
+      Tests  1 passed (1)
+   Start at  12:05:57
+   Duration  475ms (transform 97ms, setup 0ms, collect 90ms, tests 2ms, environment 0ms, prepare 102ms)
+

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @poncho-ai/sdk
+
+## 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

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,389 @@
+type OnboardingScope = "light" | "full";
+type FeatureDomain = "model" | "storage" | "memory" | "auth" | "telemetry" | "mcp";
+type OnboardingFieldTarget = "agent" | "config" | "env";
+type OnboardingFieldKind = "select" | "boolean" | "string" | "number";
+type OnboardingFieldCondition = {
+    fieldId: string;
+    equals?: string | number | boolean;
+    oneOf?: Array<string | number | boolean>;
+};
+type OnboardingOption = {
+    value: string;
+    label: string;
+    envVars?: string[];
+    description?: string;
+};
+type OnboardingField = {
+    id: string;
+    domain: FeatureDomain;
+    target: OnboardingFieldTarget;
+    path: string;
+    kind: OnboardingFieldKind;
+    scopes: OnboardingScope[];
+    label: string;
+    prompt: string;
+    defaultValue: string | number | boolean;
+    options?: OnboardingOption[];
+    envVars?: string[];
+    placeholder?: string;
+    secret?: boolean;
+    dependsOn?: OnboardingFieldCondition;
+};
+declare const ONBOARDING_FIELDS: readonly [{
+    readonly id: "model.provider";
+    readonly domain: "model";
+    readonly target: "agent";
+    readonly path: "model.provider";
+    readonly kind: "select";
+    readonly scopes: ["light", "full"];
+    readonly label: "Model provider";
+    readonly prompt: "Choose a model provider";
+    readonly defaultValue: "anthropic";
+    readonly options: [{
+        readonly value: "anthropic";
+        readonly label: "Anthropic";
+        readonly envVars: ["ANTHROPIC_API_KEY"];
+    }, {
+        readonly value: "openai";
+        readonly label: "OpenAI";
+        readonly envVars: ["OPENAI_API_KEY"];
+    }];
+}, {
+    readonly id: "env.ANTHROPIC_API_KEY";
+    readonly domain: "model";
+    readonly target: "env";
+    readonly path: "ANTHROPIC_API_KEY";
+    readonly kind: "string";
+    readonly scopes: ["light", "full"];
+    readonly label: "Anthropic API key";
+    readonly prompt: "Anthropic API key";
+    readonly defaultValue: "";
+    readonly placeholder: "sk-ant-...";
+    readonly secret: true;
+    readonly dependsOn: {
+        readonly fieldId: "model.provider";
+        readonly equals: "anthropic";
+    };
+}, {
+    readonly id: "env.OPENAI_API_KEY";
+    readonly domain: "model";
+    readonly target: "env";
+    readonly path: "OPENAI_API_KEY";
+    readonly kind: "string";
+    readonly scopes: ["light", "full"];
+    readonly label: "OpenAI API key";
+    readonly prompt: "OpenAI API key";
+    readonly defaultValue: "";
+    readonly placeholder: "sk-...";
+    readonly secret: true;
+    readonly dependsOn: {
+        readonly fieldId: "model.provider";
+        readonly equals: "openai";
+    };
+}, {
+    readonly id: "storage.provider";
+    readonly domain: "storage";
+    readonly target: "config";
+    readonly path: "storage.provider";
+    readonly kind: "select";
+    readonly scopes: ["light", "full"];
+    readonly label: "Storage provider";
+    readonly prompt: "Choose storage provider for conversations and memory";
+    readonly defaultValue: "local";
+    readonly options: [{
+        readonly value: "memory";
+        readonly label: "In-memory only";
+    }, {
+        readonly value: "local";
+        readonly label: "Local file storage";
+    }, {
+        readonly value: "redis";
+        readonly label: "Redis";
+        readonly envVars: ["REDIS_URL"];
+    }, {
+        readonly value: "upstash";
+        readonly label: "Upstash REST";
+        readonly envVars: ["UPSTASH_REDIS_REST_URL", "UPSTASH_REDIS_REST_TOKEN"];
+    }, {
+        readonly value: "dynamodb";
+        readonly label: "DynamoDB";
+        readonly envVars: ["PONCHO_DYNAMODB_TABLE"];
+    }];
+}, {
+    readonly id: "storage.url";
+    readonly domain: "storage";
+    readonly target: "config";
+    readonly path: "storage.url";
+    readonly kind: "string";
+    readonly scopes: ["full"];
+    readonly label: "Storage URL";
+    readonly prompt: "Storage URL";
+    readonly defaultValue: "";
+    readonly dependsOn: {
+        readonly fieldId: "storage.provider";
+        readonly oneOf: ["redis", "upstash"];
+    };
+}, {
+    readonly id: "storage.token";
+    readonly domain: "storage";
+    readonly target: "config";
+    readonly path: "storage.token";
+    readonly kind: "string";
+    readonly scopes: ["full"];
+    readonly label: "Storage token";
+    readonly prompt: "Storage token";
+    readonly defaultValue: "";
+    readonly dependsOn: {
+        readonly fieldId: "storage.provider";
+        readonly equals: "upstash";
+    };
+}, {
+    readonly id: "storage.table";
+    readonly domain: "storage";
+    readonly target: "config";
+    readonly path: "storage.table";
+    readonly kind: "string";
+    readonly scopes: ["full"];
+    readonly label: "DynamoDB table";
+    readonly prompt: "DynamoDB table name";
+    readonly defaultValue: "";
+    readonly dependsOn: {
+        readonly fieldId: "storage.provider";
+        readonly equals: "dynamodb";
+    };
+}, {
+    readonly id: "storage.region";
+    readonly domain: "storage";
+    readonly target: "config";
+    readonly path: "storage.region";
+    readonly kind: "string";
+    readonly scopes: ["full"];
+    readonly label: "DynamoDB region";
+    readonly prompt: "DynamoDB region (optional)";
+    readonly defaultValue: "";
+    readonly dependsOn: {
+        readonly fieldId: "storage.provider";
+        readonly equals: "dynamodb";
+    };
+}, {
+    readonly id: "storage.memory.enabled";
+    readonly domain: "memory";
+    readonly target: "config";
+    readonly path: "storage.memory.enabled";
+    readonly kind: "boolean";
+    readonly scopes: ["light", "full"];
+    readonly label: "Enable memory tools";
+    readonly prompt: "Enable memory tools (memory_get, memory_update, conversation_recall)?";
+    readonly defaultValue: true;
+}, {
+    readonly id: "storage.memory.maxRecallConversations";
+    readonly domain: "memory";
+    readonly target: "config";
+    readonly path: "storage.memory.maxRecallConversations";
+    readonly kind: "number";
+    readonly scopes: ["full"];
+    readonly label: "Max recall conversations";
+    readonly prompt: "Max conversations scanned by conversation_recall";
+    readonly defaultValue: 20;
+    readonly dependsOn: {
+        readonly fieldId: "storage.memory.enabled";
+        readonly equals: true;
+    };
+}, {
+    readonly id: "auth.required";
+    readonly domain: "auth";
+    readonly target: "config";
+    readonly path: "auth.required";
+    readonly kind: "boolean";
+    readonly scopes: ["light", "full"];
+    readonly label: "Require auth";
+    readonly prompt: "Require auth for API requests?";
+    readonly defaultValue: false;
+}, {
+    readonly id: "auth.type";
+    readonly domain: "auth";
+    readonly target: "config";
+    readonly path: "auth.type";
+    readonly kind: "select";
+    readonly scopes: ["full"];
+    readonly label: "Auth type";
+    readonly prompt: "Auth type";
+    readonly defaultValue: "bearer";
+    readonly options: [{
+        readonly value: "bearer";
+        readonly label: "Bearer token";
+    }, {
+        readonly value: "header";
+        readonly label: "Custom header";
+    }, {
+        readonly value: "custom";
+        readonly label: "Custom validate() function";
+    }];
+    readonly dependsOn: {
+        readonly fieldId: "auth.required";
+        readonly equals: true;
+    };
+}, {
+    readonly id: "auth.headerName";
+    readonly domain: "auth";
+    readonly target: "config";
+    readonly path: "auth.headerName";
+    readonly kind: "string";
+    readonly scopes: ["full"];
+    readonly label: "Header name";
+    readonly prompt: "Header name (for auth type=header)";
+    readonly defaultValue: "x-poncho-key";
+    readonly dependsOn: {
+        readonly fieldId: "auth.type";
+        readonly equals: "header";
+    };
+}, {
+    readonly id: "telemetry.enabled";
+    readonly domain: "telemetry";
+    readonly target: "config";
+    readonly path: "telemetry.enabled";
+    readonly kind: "boolean";
+    readonly scopes: ["light", "full"];
+    readonly label: "Enable telemetry";
+    readonly prompt: "Enable telemetry?";
+    readonly defaultValue: true;
+}, {
+    readonly id: "telemetry.otlp";
+    readonly domain: "telemetry";
+    readonly target: "config";
+    readonly path: "telemetry.otlp";
+    readonly kind: "string";
+    readonly scopes: ["full"];
+    readonly label: "OTLP endpoint";
+    readonly prompt: "OTLP endpoint (optional)";
+    readonly defaultValue: "";
+    readonly dependsOn: {
+        readonly fieldId: "telemetry.enabled";
+        readonly equals: true;
+    };
+}];
+declare const FEATURE_DOMAIN_ORDER: readonly FeatureDomain[];
+declare const fieldsForScope: (scope: OnboardingScope) => OnboardingField[];
+
+type JsonSchema = {
+    type?: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: Array<string | number | boolean | null>;
+    additionalProperties?: boolean | JsonSchema;
+    [key: string]: unknown;
+};
+type Role = "system" | "user" | "assistant" | "tool";
+interface Message {
+    role: Role;
+    content: string;
+    metadata?: {
+        id?: string;
+        timestamp?: number;
+        tokenCount?: number;
+        step?: number;
+        toolActivity?: string[];
+    };
+}
+interface ToolContext {
+    runId: string;
+    agentId: string;
+    step: number;
+    workingDir: string;
+    parameters: Record<string, unknown>;
+}
+type ToolHandler<TInput extends Record<string, unknown>, TOutput> = (input: TInput, context: ToolContext) => Promise<TOutput> | TOutput;
+interface ToolDefinition<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown> {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    timeout?: number;
+    retries?: number;
+    isolated?: boolean;
+    requiresApproval?: boolean;
+    handler: ToolHandler<TInput, TOutput>;
+}
+declare const defineTool: <TInput extends Record<string, unknown>, TOutput = unknown>(definition: ToolDefinition<TInput, TOutput>) => ToolDefinition<TInput, TOutput>;
+
+interface RunInput {
+    task: string;
+    parameters?: Record<string, unknown>;
+    messages?: Message[];
+}
+interface TokenUsage {
+    input: number;
+    output: number;
+    cached: number;
+}
+interface RunResult {
+    status: "completed" | "error" | "cancelled";
+    response?: string;
+    steps: number;
+    tokens: TokenUsage;
+    duration: number;
+}
+interface AgentFailure {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type AgentEvent = {
+    type: "run:started";
+    runId: string;
+    agentId: string;
+} | {
+    type: "run:completed";
+    runId: string;
+    result: RunResult;
+} | {
+    type: "run:error";
+    runId: string;
+    error: AgentFailure;
+} | {
+    type: "step:started";
+    step: number;
+} | {
+    type: "step:completed";
+    step: number;
+    duration: number;
+} | {
+    type: "model:request";
+    tokens: number;
+} | {
+    type: "model:chunk";
+    content: string;
+} | {
+    type: "model:response";
+    usage: TokenUsage;
+} | {
+    type: "tool:started";
+    tool: string;
+    input: unknown;
+} | {
+    type: "tool:completed";
+    tool: string;
+    output: unknown;
+    duration: number;
+} | {
+    type: "tool:error";
+    tool: string;
+    error: string;
+    recoverable: boolean;
+} | {
+    type: "tool:approval:required";
+    tool: string;
+    input: unknown;
+    approvalId: string;
+} | {
+    type: "tool:approval:granted";
+    approvalId: string;
+} | {
+    type: "tool:approval:denied";
+    approvalId: string;
+    reason?: string;
+};
+
+export { type AgentEvent, type AgentFailure, FEATURE_DOMAIN_ORDER, type FeatureDomain, type JsonSchema, type Message, ONBOARDING_FIELDS, type OnboardingField, type OnboardingFieldCondition, type OnboardingFieldKind, type OnboardingFieldTarget, type OnboardingOption, type OnboardingScope, type Role, type RunInput, type RunResult, type TokenUsage, type ToolContext, type ToolDefinition, type ToolHandler, defineTool, fieldsForScope };

package/dist/index.js

@@ -0,0 +1,226 @@
+// src/config-registry.ts
+var ONBOARDING_FIELDS = [
+  {
+    id: "model.provider",
+    domain: "model",
+    target: "agent",
+    path: "model.provider",
+    kind: "select",
+    scopes: ["light", "full"],
+    label: "Model provider",
+    prompt: "Choose a model provider",
+    defaultValue: "anthropic",
+    options: [
+      { value: "anthropic", label: "Anthropic", envVars: ["ANTHROPIC_API_KEY"] },
+      { value: "openai", label: "OpenAI", envVars: ["OPENAI_API_KEY"] }
+    ]
+  },
+  {
+    id: "env.ANTHROPIC_API_KEY",
+    domain: "model",
+    target: "env",
+    path: "ANTHROPIC_API_KEY",
+    kind: "string",
+    scopes: ["light", "full"],
+    label: "Anthropic API key",
+    prompt: "Anthropic API key",
+    defaultValue: "",
+    placeholder: "sk-ant-...",
+    secret: true,
+    dependsOn: { fieldId: "model.provider", equals: "anthropic" }
+  },
+  {
+    id: "env.OPENAI_API_KEY",
+    domain: "model",
+    target: "env",
+    path: "OPENAI_API_KEY",
+    kind: "string",
+    scopes: ["light", "full"],
+    label: "OpenAI API key",
+    prompt: "OpenAI API key",
+    defaultValue: "",
+    placeholder: "sk-...",
+    secret: true,
+    dependsOn: { fieldId: "model.provider", equals: "openai" }
+  },
+  {
+    id: "storage.provider",
+    domain: "storage",
+    target: "config",
+    path: "storage.provider",
+    kind: "select",
+    scopes: ["light", "full"],
+    label: "Storage provider",
+    prompt: "Choose storage provider for conversations and memory",
+    defaultValue: "local",
+    options: [
+      { value: "memory", label: "In-memory only" },
+      { value: "local", label: "Local file storage" },
+      { value: "redis", label: "Redis", envVars: ["REDIS_URL"] },
+      {
+        value: "upstash",
+        label: "Upstash REST",
+        envVars: ["UPSTASH_REDIS_REST_URL", "UPSTASH_REDIS_REST_TOKEN"]
+      },
+      {
+        value: "dynamodb",
+        label: "DynamoDB",
+        envVars: ["PONCHO_DYNAMODB_TABLE"]
+      }
+    ]
+  },
+  {
+    id: "storage.url",
+    domain: "storage",
+    target: "config",
+    path: "storage.url",
+    kind: "string",
+    scopes: ["full"],
+    label: "Storage URL",
+    prompt: "Storage URL",
+    defaultValue: "",
+    dependsOn: { fieldId: "storage.provider", oneOf: ["redis", "upstash"] }
+  },
+  {
+    id: "storage.token",
+    domain: "storage",
+    target: "config",
+    path: "storage.token",
+    kind: "string",
+    scopes: ["full"],
+    label: "Storage token",
+    prompt: "Storage token",
+    defaultValue: "",
+    dependsOn: { fieldId: "storage.provider", equals: "upstash" }
+  },
+  {
+    id: "storage.table",
+    domain: "storage",
+    target: "config",
+    path: "storage.table",
+    kind: "string",
+    scopes: ["full"],
+    label: "DynamoDB table",
+    prompt: "DynamoDB table name",
+    defaultValue: "",
+    dependsOn: { fieldId: "storage.provider", equals: "dynamodb" }
+  },
+  {
+    id: "storage.region",
+    domain: "storage",
+    target: "config",
+    path: "storage.region",
+    kind: "string",
+    scopes: ["full"],
+    label: "DynamoDB region",
+    prompt: "DynamoDB region (optional)",
+    defaultValue: "",
+    dependsOn: { fieldId: "storage.provider", equals: "dynamodb" }
+  },
+  {
+    id: "storage.memory.enabled",
+    domain: "memory",
+    target: "config",
+    path: "storage.memory.enabled",
+    kind: "boolean",
+    scopes: ["light", "full"],
+    label: "Enable memory tools",
+    prompt: "Enable memory tools (memory_get, memory_update, conversation_recall)?",
+    defaultValue: true
+  },
+  {
+    id: "storage.memory.maxRecallConversations",
+    domain: "memory",
+    target: "config",
+    path: "storage.memory.maxRecallConversations",
+    kind: "number",
+    scopes: ["full"],
+    label: "Max recall conversations",
+    prompt: "Max conversations scanned by conversation_recall",
+    defaultValue: 20,
+    dependsOn: { fieldId: "storage.memory.enabled", equals: true }
+  },
+  {
+    id: "auth.required",
+    domain: "auth",
+    target: "config",
+    path: "auth.required",
+    kind: "boolean",
+    scopes: ["light", "full"],
+    label: "Require auth",
+    prompt: "Require auth for API requests?",
+    defaultValue: false
+  },
+  {
+    id: "auth.type",
+    domain: "auth",
+    target: "config",
+    path: "auth.type",
+    kind: "select",
+    scopes: ["full"],
+    label: "Auth type",
+    prompt: "Auth type",
+    defaultValue: "bearer",
+    options: [
+      { value: "bearer", label: "Bearer token" },
+      { value: "header", label: "Custom header" },
+      { value: "custom", label: "Custom validate() function" }
+    ],
+    dependsOn: { fieldId: "auth.required", equals: true }
+  },
+  {
+    id: "auth.headerName",
+    domain: "auth",
+    target: "config",
+    path: "auth.headerName",
+    kind: "string",
+    scopes: ["full"],
+    label: "Header name",
+    prompt: "Header name (for auth type=header)",
+    defaultValue: "x-poncho-key",
+    dependsOn: { fieldId: "auth.type", equals: "header" }
+  },
+  {
+    id: "telemetry.enabled",
+    domain: "telemetry",
+    target: "config",
+    path: "telemetry.enabled",
+    kind: "boolean",
+    scopes: ["light", "full"],
+    label: "Enable telemetry",
+    prompt: "Enable telemetry?",
+    defaultValue: true
+  },
+  {
+    id: "telemetry.otlp",
+    domain: "telemetry",
+    target: "config",
+    path: "telemetry.otlp",
+    kind: "string",
+    scopes: ["full"],
+    label: "OTLP endpoint",
+    prompt: "OTLP endpoint (optional)",
+    defaultValue: "",
+    dependsOn: { fieldId: "telemetry.enabled", equals: true }
+  }
+];
+var FEATURE_DOMAIN_ORDER = [
+  "model",
+  "storage",
+  "memory",
+  "auth",
+  "telemetry",
+  "mcp"
+];
+var fieldsForScope = (scope) => ONBOARDING_FIELDS.filter(
+  (field) => field.scopes.includes(scope)
+);
+
+// src/index.ts
+var defineTool = (definition) => definition;
+export {
+  FEATURE_DOMAIN_ORDER,
+  ONBOARDING_FIELDS,
+  defineTool,
+  fieldsForScope
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@poncho-ai/sdk",
+  "version": "0.2.0",
+  "description": "Core types and utilities for building Poncho skills",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/latitude-dev/poncho-ai.git",
+    "directory": "packages/sdk"
+  },
+  "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": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "vitest": "^1.4.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "sdk",
+    "tools"
+  ],
+  "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/config-registry.ts

@@ -0,0 +1,263 @@
+export type OnboardingScope = "light" | "full";
+
+export type FeatureDomain =
+  | "model"
+  | "storage"
+  | "memory"
+  | "auth"
+  | "telemetry"
+  | "mcp";
+
+export type OnboardingFieldTarget = "agent" | "config" | "env";
+
+export type OnboardingFieldKind = "select" | "boolean" | "string" | "number";
+
+export type OnboardingFieldCondition = {
+  fieldId: string;
+  equals?: string | number | boolean;
+  oneOf?: Array<string | number | boolean>;
+};
+
+export type OnboardingOption = {
+  value: string;
+  label: string;
+  envVars?: string[];
+  description?: string;
+};
+
+export type OnboardingField = {
+  id: string;
+  domain: FeatureDomain;
+  target: OnboardingFieldTarget;
+  path: string;
+  kind: OnboardingFieldKind;
+  scopes: OnboardingScope[];
+  label: string;
+  prompt: string;
+  defaultValue: string | number | boolean;
+  options?: OnboardingOption[];
+  envVars?: string[];
+  placeholder?: string;
+  secret?: boolean;
+  dependsOn?: OnboardingFieldCondition;
+};
+
+export const ONBOARDING_FIELDS = [
+  {
+    id: "model.provider",
+    domain: "model",
+    target: "agent",
+    path: "model.provider",
+    kind: "select",
+    scopes: ["light", "full"],
+    label: "Model provider",
+    prompt: "Choose a model provider",
+    defaultValue: "anthropic",
+    options: [
+      { value: "anthropic", label: "Anthropic", envVars: ["ANTHROPIC_API_KEY"] },
+      { value: "openai", label: "OpenAI", envVars: ["OPENAI_API_KEY"] },
+    ],
+  },
+  {
+    id: "env.ANTHROPIC_API_KEY",
+    domain: "model",
+    target: "env",
+    path: "ANTHROPIC_API_KEY",
+    kind: "string",
+    scopes: ["light", "full"],
+    label: "Anthropic API key",
+    prompt: "Anthropic API key",
+    defaultValue: "",
+    placeholder: "sk-ant-...",
+    secret: true,
+    dependsOn: { fieldId: "model.provider", equals: "anthropic" },
+  },
+  {
+    id: "env.OPENAI_API_KEY",
+    domain: "model",
+    target: "env",
+    path: "OPENAI_API_KEY",
+    kind: "string",
+    scopes: ["light", "full"],
+    label: "OpenAI API key",
+    prompt: "OpenAI API key",
+    defaultValue: "",
+    placeholder: "sk-...",
+    secret: true,
+    dependsOn: { fieldId: "model.provider", equals: "openai" },
+  },
+  {
+    id: "storage.provider",
+    domain: "storage",
+    target: "config",
+    path: "storage.provider",
+    kind: "select",
+    scopes: ["light", "full"],
+    label: "Storage provider",
+    prompt: "Choose storage provider for conversations and memory",
+    defaultValue: "local",
+    options: [
+      { value: "memory", label: "In-memory only" },
+      { value: "local", label: "Local file storage" },
+      { value: "redis", label: "Redis", envVars: ["REDIS_URL"] },
+      {
+        value: "upstash",
+        label: "Upstash REST",
+        envVars: ["UPSTASH_REDIS_REST_URL", "UPSTASH_REDIS_REST_TOKEN"],
+      },
+      {
+        value: "dynamodb",
+        label: "DynamoDB",
+        envVars: ["PONCHO_DYNAMODB_TABLE"],
+      },
+    ],
+  },
+  {
+    id: "storage.url",
+    domain: "storage",
+    target: "config",
+    path: "storage.url",
+    kind: "string",
+    scopes: ["full"],
+    label: "Storage URL",
+    prompt: "Storage URL",
+    defaultValue: "",
+    dependsOn: { fieldId: "storage.provider", oneOf: ["redis", "upstash"] },
+  },
+  {
+    id: "storage.token",
+    domain: "storage",
+    target: "config",
+    path: "storage.token",
+    kind: "string",
+    scopes: ["full"],
+    label: "Storage token",
+    prompt: "Storage token",
+    defaultValue: "",
+    dependsOn: { fieldId: "storage.provider", equals: "upstash" },
+  },
+  {
+    id: "storage.table",
+    domain: "storage",
+    target: "config",
+    path: "storage.table",
+    kind: "string",
+    scopes: ["full"],
+    label: "DynamoDB table",
+    prompt: "DynamoDB table name",
+    defaultValue: "",
+    dependsOn: { fieldId: "storage.provider", equals: "dynamodb" },
+  },
+  {
+    id: "storage.region",
+    domain: "storage",
+    target: "config",
+    path: "storage.region",
+    kind: "string",
+    scopes: ["full"],
+    label: "DynamoDB region",
+    prompt: "DynamoDB region (optional)",
+    defaultValue: "",
+    dependsOn: { fieldId: "storage.provider", equals: "dynamodb" },
+  },
+  {
+    id: "storage.memory.enabled",
+    domain: "memory",
+    target: "config",
+    path: "storage.memory.enabled",
+    kind: "boolean",
+    scopes: ["light", "full"],
+    label: "Enable memory tools",
+    prompt: "Enable memory tools (memory_get, memory_update, conversation_recall)?",
+    defaultValue: true,
+  },
+  {
+    id: "storage.memory.maxRecallConversations",
+    domain: "memory",
+    target: "config",
+    path: "storage.memory.maxRecallConversations",
+    kind: "number",
+    scopes: ["full"],
+    label: "Max recall conversations",
+    prompt: "Max conversations scanned by conversation_recall",
+    defaultValue: 20,
+    dependsOn: { fieldId: "storage.memory.enabled", equals: true },
+  },
+  {
+    id: "auth.required",
+    domain: "auth",
+    target: "config",
+    path: "auth.required",
+    kind: "boolean",
+    scopes: ["light", "full"],
+    label: "Require auth",
+    prompt: "Require auth for API requests?",
+    defaultValue: false,
+  },
+  {
+    id: "auth.type",
+    domain: "auth",
+    target: "config",
+    path: "auth.type",
+    kind: "select",
+    scopes: ["full"],
+    label: "Auth type",
+    prompt: "Auth type",
+    defaultValue: "bearer",
+    options: [
+      { value: "bearer", label: "Bearer token" },
+      { value: "header", label: "Custom header" },
+      { value: "custom", label: "Custom validate() function" },
+    ],
+    dependsOn: { fieldId: "auth.required", equals: true },
+  },
+  {
+    id: "auth.headerName",
+    domain: "auth",
+    target: "config",
+    path: "auth.headerName",
+    kind: "string",
+    scopes: ["full"],
+    label: "Header name",
+    prompt: "Header name (for auth type=header)",
+    defaultValue: "x-poncho-key",
+    dependsOn: { fieldId: "auth.type", equals: "header" },
+  },
+  {
+    id: "telemetry.enabled",
+    domain: "telemetry",
+    target: "config",
+    path: "telemetry.enabled",
+    kind: "boolean",
+    scopes: ["light", "full"],
+    label: "Enable telemetry",
+    prompt: "Enable telemetry?",
+    defaultValue: true,
+  },
+  {
+    id: "telemetry.otlp",
+    domain: "telemetry",
+    target: "config",
+    path: "telemetry.otlp",
+    kind: "string",
+    scopes: ["full"],
+    label: "OTLP endpoint",
+    prompt: "OTLP endpoint (optional)",
+    defaultValue: "",
+    dependsOn: { fieldId: "telemetry.enabled", equals: true },
+  },
+] as const satisfies readonly OnboardingField[];
+
+export const FEATURE_DOMAIN_ORDER: readonly FeatureDomain[] = [
+  "model",
+  "storage",
+  "memory",
+  "auth",
+  "telemetry",
+  "mcp",
+] as const;
+
+export const fieldsForScope = (scope: OnboardingScope): OnboardingField[] =>
+  ONBOARDING_FIELDS.filter((field) =>
+    (field.scopes as readonly OnboardingScope[]).includes(scope),
+  );

package/src/index.ts

@@ -0,0 +1,108 @@
+export type JsonSchema = {
+  type?: string;
+  description?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  enum?: Array<string | number | boolean | null>;
+  additionalProperties?: boolean | JsonSchema;
+  [key: string]: unknown;
+};
+
+export type Role = "system" | "user" | "assistant" | "tool";
+
+export interface Message {
+  role: Role;
+  content: string;
+  metadata?: {
+    id?: string;
+    timestamp?: number;
+    tokenCount?: number;
+    step?: number;
+    toolActivity?: string[];
+  };
+}
+
+export interface ToolContext {
+  runId: string;
+  agentId: string;
+  step: number;
+  workingDir: string;
+  parameters: Record<string, unknown>;
+}
+
+export type ToolHandler<TInput extends Record<string, unknown>, TOutput> = (
+  input: TInput,
+  context: ToolContext,
+) => Promise<TOutput> | TOutput;
+
+export interface ToolDefinition<
+  TInput extends Record<string, unknown> = Record<string, unknown>,
+  TOutput = unknown,
+> {
+  name: string;
+  description: string;
+  inputSchema: JsonSchema;
+  outputSchema?: JsonSchema;
+  timeout?: number;
+  retries?: number;
+  isolated?: boolean;
+  requiresApproval?: boolean;
+  handler: ToolHandler<TInput, TOutput>;
+}
+
+export const defineTool = <
+  TInput extends Record<string, unknown>,
+  TOutput = unknown,
+>(
+  definition: ToolDefinition<TInput, TOutput>,
+): ToolDefinition<TInput, TOutput> => definition;
+
+export * from "./config-registry.js";
+
+export interface RunInput {
+  task: string;
+  parameters?: Record<string, unknown>;
+  messages?: Message[];
+}
+
+export interface TokenUsage {
+  input: number;
+  output: number;
+  cached: number;
+}
+
+export interface RunResult {
+  status: "completed" | "error" | "cancelled";
+  response?: string;
+  steps: number;
+  tokens: TokenUsage;
+  duration: number;
+}
+
+export interface AgentFailure {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export type AgentEvent =
+  | { type: "run:started"; runId: string; agentId: string }
+  | { type: "run:completed"; runId: string; result: RunResult }
+  | { type: "run:error"; runId: string; error: AgentFailure }
+  | { type: "step:started"; step: number }
+  | { type: "step:completed"; step: number; duration: number }
+  | { type: "model:request"; tokens: number }
+  | { type: "model:chunk"; content: string }
+  | { type: "model:response"; usage: TokenUsage }
+  | { type: "tool:started"; tool: string; input: unknown }
+  | { type: "tool:completed"; tool: string; output: unknown; duration: number }
+  | { type: "tool:error"; tool: string; error: string; recoverable: boolean }
+  | {
+      type: "tool:approval:required";
+      tool: string;
+      input: unknown;
+      approvalId: string;
+    }
+  | { type: "tool:approval:granted"; approvalId: string }
+  | { type: "tool:approval:denied"; approvalId: string; reason?: string };

package/test/sdk.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { defineTool } from "../src/index.js";
+
+describe("defineTool", () => {
+  it("returns the same tool definition", () => {
+    const tool = defineTool({
+      name: "echo",
+      description: "Echoes text",
+      inputSchema: {
+        type: "object",
+        properties: { text: { type: "string" } },
+        required: ["text"],
+      },
+      handler: async (input) => ({ text: input.text }),
+    });
+
+    expect(tool.name).toBe("echo");
+    expect(tool.description).toBe("Echoes text");
+  });
+});

package/tsconfig.json

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