@poncho-ai/sdk 1.8.1 → 1.10.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/sdk@1.8.1 build /home/runner/work/poncho-ai/poncho-ai/packages/sdk
+> @poncho-ai/sdk@1.10.0 build /home/runner/work/poncho-ai/poncho-ai/packages/sdk
 > tsup src/index.ts --format esm --dts
 
 CLI Building entry: src/index.ts
@@ -7,8 +7,8 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js 12.46 KB
-ESM ⚡️ Build success in 16ms
+ESM dist/index.js 17.24 KB
+ESM ⚡️ Build success in 21ms
 DTS Build start
-DTS ⚡️ Build success in 1193ms
-DTS dist/index.d.ts 24.92 KB
+DTS ⚡️ Build success in 1318ms
+DTS dist/index.d.ts 28.29 KB

package/CHANGELOG.md

@@ -1,5 +1,190 @@
 # @poncho-ai/sdk
 
+## 1.10.0
+
+### Minor Changes
+
+- [#104](https://github.com/cesr/poncho-ai/pull/104) [`9616060`](https://github.com/cesr/poncho-ai/commit/96160607502c2c0b05bc60b67b8fc012f4052ef1) Thanks [@cesr](https://github.com/cesr)! - dev: add a Files mode to the sidebar with VFS browsing, preview, and uploads
+
+  The web UI sidebar now has a Chats / Files segmented control. Switching to
+  Files reveals a folder-tree view of the agent's VFS — the same storage the
+  agent reads and writes via `read_file`, `write_file`, and the virtualized
+  `bash` tool. Folders expand inline with the same caret/dropdown pattern as
+  the Cron jobs section. Clicking a file previews it in the main panel:
+  - Text / JSON / source code render as a wrapped `<pre>` (5 MB cap), with an Edit button for inline editing (last-write-wins via PUT).
+  - Images render inline.
+  - PDFs render in an embedded iframe.
+  - Audio and video render with native controls.
+  - Anything else shows a placeholder card with a Download button.
+
+  Files can be added directly from the UI: an Upload button (multi-file
+  picker), drag-and-drop onto the explorer or onto a specific folder row, and
+  a New folder button. Files and folders are deletable via a hover-X with a
+  two-step confirm. Conflicts prompt to overwrite. Four new HTTP routes back
+  this UI: `GET /api/vfs-list`, `PUT /api/vfs/{path}`, `DELETE /api/vfs/{path}`,
+  and `POST /api/vfs-mkdir`. URLs of the form `/f/{path}` deep-link to a file
+  preview; the chat composer is hidden while previewing a file.
+
+  The same routes are exposed on `AgentClient` for programmatic use:
+  `listDir`, `writeFile`, `deleteFile`, and `mkdir` (alongside the existing
+  `readFile`). New shared types `ApiVfsEntry`, `ApiVfsListResponse`, and
+  `ApiVfsWriteResponse` are exported from `@poncho-ai/sdk`.
+
+### Patch Changes
+
+- [`524df41`](https://github.com/cesr/poncho-ai/commit/524df411904bd00c07901695eda6d4dd07dde972) Thanks [@cesr](https://github.com/cesr)! - fix: persist harness messages on cancelled runs so the agent doesn't lose context
+
+  When a run was cancelled (Stop button, abort signal), `conversation.messages`
+  was updated with the partial assistant turn but `conversation._harnessMessages`
+  — the canonical history `loadCanonicalHistory` hands to the model on the next
+  turn — was left holding a snapshot from the _previous_ successful run. The
+  agent had no memory of the cancelled work, even though the user-facing UI
+  still showed it. The new verbose-mode harness toggle made this divergence
+  directly visible.
+
+  The fix plumbs an in-flight `messages` snapshot through the `run:cancelled`
+  event, trims it to a model-valid prefix (no orphan `tool_use`), and persists
+  it as `_harnessMessages` on every cancel path in the CLI.
+
+## 1.9.0
+
+### Minor Changes
+
+- [#100](https://github.com/cesr/poncho-ai/pull/100) [`ef4fe5d`](https://github.com/cesr/poncho-ai/commit/ef4fe5d1fd4bb31c201fd240f4524b64f01e3e6d) Thanks [@cesr](https://github.com/cesr)! - feat(logging): readable, scoped, level-aware dev server logs
+
+  `poncho dev` output is now formatted consistently across the CLI and
+  harness:
+
+  ```
+  20:23:45 ✓ poncho     dev server ready at http://localhost:3000
+  20:23:45 • slack      enabled at /api/messaging/slack
+  20:23:45 • cron       scheduled 2 jobs: hourly_check, nightly_summary
+  20:24:15 → cron:hourly_check  started
+  20:24:17 ✓ cron:hourly_check  completed in 1.2s (3 chats)
+  20:25:00 ⚠ telegram   approval not found: req-7f42a
+  20:25:01 ✗ poncho     internal error: ECONNREFUSED
+  ```
+
+  Format: `HH:mm:ss <symbol> <scope> <message>`. Scopes (`poncho`, `cron`,
+  `reminder`, `messaging`, `slack`, `telegram`, `resend`, `subagent`,
+  `approval`, `browser`, `csrf`, `upload`, `serverless`, `self-fetch`,
+  `mcp`, `telemetry`, `cost`, `model`, `harness`, `event`, `tools`)
+  replace the previous mix of `[poncho]`, `[poncho][cost]`, `[cron]`,
+  `[messaging-runner]`, `[event] ...`, etc.
+  - New `createLogger(scope)` exported from `@poncho-ai/sdk` with
+    `.debug/.info/.warn/.error/.success/.ready/.item/.child(sub)` and
+    helpers `formatError`, `url`, `muted`, `num`.
+  - Honors `NO_COLOR` / `FORCE_COLOR` and `LOG_LEVEL=debug|info|warn|error|silent`.
+    Verbose telemetry/cost/event lines now log at `debug` and are silent
+    by default.
+  - `poncho dev` gains `-v`/`--verbose` (debug), `-q`/`--quiet` (warn+),
+    and `--log-level <level>` flags.
+  - Each scope tag is colored with a stable pastel hue (truecolor), with
+    256-color and 16-color fallbacks. Children (`cron:hourly_check`)
+    inherit their parent's color.
+  - TTY-aware: ANSI color is stripped when stdout is piped.
+  - Conversation-egress logging (`[poncho][egress] read: …`) is now opt-in
+    via `PONCHO_LOG_EGRESS=1` (matching the documented behavior; it had
+    been logging unconditionally).
+  - No behavior changes to which events are emitted — only formatting.
+
+- [#100](https://github.com/cesr/poncho-ai/pull/100) [`ef4fe5d`](https://github.com/cesr/poncho-ai/commit/ef4fe5d1fd4bb31c201fd240f4524b64f01e3e6d) Thanks [@cesr](https://github.com/cesr)! - feat: Slack-style message threads
+
+  Users can now fork any persisted message into one or more threads. Each
+  thread is a new conversation whose initial history is a snapshot of the
+  parent up to and including the anchor message; replies in the thread
+  evolve independently of the parent. Multiple threads per parent message
+  are supported.
+
+  ## Web UI
+  - Hover any message in the main pane to reveal a "Reply in thread" pill
+    positioned just below the bubble (offset varies by role). The pill is
+    invisible by default and only appears on hover; a delayed-hide bridges
+    the empty space between message and pill so the user can move the
+    mouse onto it without it flickering off.
+  - Once a thread exists on a message, the pill is replaced by an
+    always-visible badge (`"N replies · 5m ago"`, count bold + meta muted).
+    Multiple threads stack vertically under the message, each with its own
+    badge. Hovering a badge reveals an outside-positioned `×` delete with
+    the same two-step "× → sure?" confirmation as the sidebar
+    conversation-delete.
+  - Clicking a badge opens the thread in a right-side panel that mirrors
+    the existing browser-panel pattern: a flex sibling of `.main-chat`
+    with a 1px drag-resize handle. The panel has its own composer
+    (independent file uploads, paste-to-attach, attachment preview)
+    rendered alongside the main composer so users can keep typing in the
+    parent conversation. Vertical padding matches the main composer so
+    both chatboxes line up at the same baseline.
+  - The pinned parent message and replies inside the panel render through
+    the same DOM construction logic as the main pane (assistant avatar +
+    markdown, user bubble + file thumbnails). Reply submissions stream
+    token-by-token via SSE (parsed model:chunk events feed an optimistic
+    assistant placeholder; a thinking-indicator shows until the first
+    chunk lands).
+  - The open thread is reflected in the URL hash (`#thread=<id>`) so a
+    page reload restores the panel. Switching conversations or closing
+    the panel clears the hash and any sticky drag-resize widths.
+
+  ## DB
+  - New `parent_message_id TEXT` column on `conversations` (migration 6)
+    plus a partial index on `(parent_conversation_id, parent_message_id)
+WHERE parent_message_id IS NOT NULL`.
+  - The existing `parent_conversation_id` plumbing is reused; subagents
+    and threads coexist on that column, discriminated by whether
+    `parent_message_id` is set (subagents leave it `NULL`).
+  - `threadMeta` (snapshot length + cached parent-message summary)
+    round-trips inside the conversation `data` blob.
+
+  ## API
+  - `GET /api/conversations/:id/threads` → `{ threads: ApiThreadSummary[] }`
+  - `POST /api/conversations/:id/threads { parentMessageId, title? }` →
+    201 `{ thread, conversationId }` |
+    404 `PARENT_MESSAGE_NOT_FOUND` |
+    409 `MESSAGE_ID_REQUIRED` (anchor lacks a stable id) |
+    409 `ANCHOR_IN_FLIGHT` (anchor is the streaming tail of a live run)
+  - The two `SUBAGENT_READ_ONLY` gates on `/messages` and `/continue` are
+    now keyed on `subagentMeta` rather than `parentConversationId` so
+    threads remain writable.
+  - New `ApiThreadSummary`, `ApiThreadListResponse`,
+    `ApiCreateThreadRequest`, `ApiCreateThreadResponse` types in
+    `@poncho-ai/sdk`. New `AgentClient.listThreads` /
+    `AgentClient.createThread` wrappers in `@poncho-ai/client`.
+
+  ## Storage interface
+  - `ConversationStore.listThreads(parentConversationId)` and the
+    matching `StorageEngine.conversations.listThreads(...)`. External
+    implementers of these interfaces will need to add the method.
+  - `Conversation` / `ConversationCreateInit` / `ConversationSummary`
+    gained optional `parentMessageId` and `threadMeta` fields.
+
+  ## Fork semantics
+  - Stable `metadata.id` on every persisted message: `randomUUID()` is
+    hoisted once per turn and reused for both the user message and the
+    in-flight assistant message across all persist sites (cli messaging
+    run, cli `/messages` handler, cron path). `buildAssistantMetadata`
+    takes an optional `{ id, timestamp }` opt-arg.
+  - No DB backfill of legacy id-less messages; the SPA hides the
+    "Reply in thread" affordance on rows whose `metadata.id` is missing.
+  - The visible-sequence used for the anchor lookup is reconstructed as
+    `[...compactedHistory, ...messages.filter(notCompactionSummary)]`,
+    so pre-compaction anchors are supported. For pre-compaction anchors,
+    `_harnessMessages` is reset to `undefined` so the harness rebuilds
+    canonical history from `messages` on the thread's first run.
+  - Forking on the actively-streaming tail message of a live run returns
+    409 `ANCHOR_IN_FLIGHT`; any prior, already-persisted message is
+    fork-able even while the parent is mid-run.
+  - Tool-result archive entries are filtered to only those referenced by
+    tool calls in the trimmed `_harnessMessages` (no whole-archive clones).
+  - All run-specific state is reset on the new thread:
+    `runtimeRunId`, `pendingApprovals`, `runStatus`,
+    `pendingSubagentResults`, `subagentCallbackCount`,
+    `runningCallbackSince`, `_continuationMessages`. `channelMeta` and
+    `subagentMeta` are explicitly NOT inherited so threads aren't bound
+    to the parent's Slack/Telegram thread and aren't subagent runs.
+  - Thread conversations stay out of the sidebar list (already-existing
+    `!c.parentConversationId` filter) and are cascade-deleted with their
+    parent.
+
 ## 1.8.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -528,6 +528,120 @@ declare const ONBOARDING_FIELDS: readonly [{
 declare const FEATURE_DOMAIN_ORDER: readonly FeatureDomain[];
 declare const fieldsForScope: (scope: OnboardingScope) => OnboardingField[];
 
+/**
+ * Shared API response types used by both the CLI server and the client SDK.
+ * Defining them here ensures compile-time drift detection between the two.
+ */
+interface ApiApprovalResponse {
+    ok: true;
+    approvalId: string;
+    approved: boolean;
+    batchComplete?: boolean;
+}
+interface ApiStopRunResponse {
+    ok: true;
+    stopped: boolean;
+    runId?: string;
+}
+interface ApiCompactResponse {
+    compacted: boolean;
+    messagesBefore: number;
+    messagesAfter: number;
+    warning?: string;
+}
+interface ApiSubagentSummary {
+    conversationId: string;
+    title: string;
+    task: string;
+    status: string;
+    messageCount: number;
+    hasPendingApprovals: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ApiThreadSummary {
+    conversationId: string;
+    parentConversationId: string;
+    parentMessageId: string;
+    title: string;
+    parentMessageSummary?: string;
+    messageCount: number;
+    /** messageCount - snapshotLength: number of replies posted into the thread. */
+    replyCount: number;
+    snapshotLength: number;
+    createdAt: number;
+    updatedAt: number;
+    /** Same as updatedAt; named for the inline-row UI. */
+    lastReplyAt: number;
+}
+interface ApiThreadListResponse {
+    threads: ApiThreadSummary[];
+}
+interface ApiCreateThreadRequest {
+    parentMessageId: string;
+    title?: string;
+}
+interface ApiCreateThreadResponse {
+    thread: ApiThreadSummary;
+    conversationId: string;
+}
+interface ApiSecretEntry {
+    name: string;
+    label?: string;
+    isSet: boolean;
+}
+interface ApiSlashCommand {
+    command: string;
+    description: string;
+    type: "command" | "skill";
+}
+interface ApiVfsEntry {
+    name: string;
+    type: "file" | "directory" | "symlink";
+    size: number;
+    mimeType: string | null;
+    updatedAt: number | null;
+}
+interface ApiVfsListResponse {
+    path: string;
+    entries: ApiVfsEntry[];
+    usage: {
+        fileCount: number;
+        totalBytes: number;
+    };
+}
+interface ApiVfsWriteResponse {
+    path: string;
+    size: number;
+    mimeType: string | null;
+    updatedAt: number;
+}
+
+declare const LEVELS: {
+    readonly debug: 10;
+    readonly info: 20;
+    readonly warn: 30;
+    readonly error: 40;
+    readonly silent: 100;
+};
+type LevelName = keyof typeof LEVELS;
+declare const setLogLevel: (level: LevelName) => void;
+type Logger = {
+    debug: (msg: string, ...extras: unknown[]) => void;
+    info: (msg: string, ...extras: unknown[]) => void;
+    warn: (msg: string, ...extras: unknown[]) => void;
+    error: (msg: string, ...extras: unknown[]) => void;
+    success: (msg: string, ...extras: unknown[]) => void;
+    ready: (msg: string, ...extras: unknown[]) => void;
+    item: (msg: string, ...extras: unknown[]) => void;
+    child: (subscope: string) => Logger;
+};
+declare const createLogger: (scope: string) => Logger;
+declare const formatError: (err: unknown) => string;
+declare const url: (s: string) => string;
+declare const muted: (s: string) => string;
+declare const num: (s: string | number) => string;
+
 type JsonSchema = {
     type?: string;
     description?: string;
@@ -677,6 +791,7 @@ type AgentEvent = {
 } | {
     type: "run:cancelled";
     runId: string;
+    messages?: Message[];
 } | {
     type: "run:error";
     runId: string;
@@ -795,4 +910,4 @@ type AgentEvent = {
     reason: string;
 };
 
-export { type AgentEvent, type AgentFailure, type ContentPart, FEATURE_DOMAIN_ORDER, type FeatureDomain, type FileContentPart, type FileInput, 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 TextContentPart, type TokenUsage, type ToolContext, type ToolDefinition, type ToolHandler, type VfsAccess, defineTool, fieldsForScope, getTextContent };
+export { type AgentEvent, type AgentFailure, type ApiApprovalResponse, type ApiCompactResponse, type ApiCreateThreadRequest, type ApiCreateThreadResponse, type ApiSecretEntry, type ApiSlashCommand, type ApiStopRunResponse, type ApiSubagentSummary, type ApiThreadListResponse, type ApiThreadSummary, type ApiVfsEntry, type ApiVfsListResponse, type ApiVfsWriteResponse, type ContentPart, FEATURE_DOMAIN_ORDER, type FeatureDomain, type FileContentPart, type FileInput, type JsonSchema, type Logger, type Message, ONBOARDING_FIELDS, type OnboardingField, type OnboardingFieldCondition, type OnboardingFieldKind, type OnboardingFieldTarget, type OnboardingOption, type OnboardingScope, type Role, type RunInput, type RunResult, type TextContentPart, type TokenUsage, type ToolContext, type ToolDefinition, type ToolHandler, type VfsAccess, createLogger, defineTool, fieldsForScope, formatError, getTextContent, muted, num, setLogLevel, url };

package/dist/index.js

@@ -439,6 +439,189 @@ var fieldsForScope = (scope) => ONBOARDING_FIELDS.filter(
   (field) => field.scopes.includes(scope)
 );
 
+// src/logger.ts
+var LEVELS = { debug: 10, info: 20, warn: 30, error: 40, silent: 100 };
+var parseLevel = (raw) => {
+  const v = (raw ?? "").trim().toLowerCase();
+  return v in LEVELS ? v : "info";
+};
+var colorEnabled = (() => {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") return true;
+  return Boolean(process.stdout.isTTY);
+})();
+var wrap = (open, close = 0) => colorEnabled ? (s) => `\x1B[${open}m${s}\x1B[${close}m` : (s) => s;
+var c = {
+  dim: wrap(2, 22),
+  bold: wrap(1, 22),
+  red: wrap(31),
+  green: wrap(32),
+  yellow: wrap(33),
+  blue: wrap(34),
+  magenta: wrap(35),
+  cyan: wrap(36),
+  gray: wrap(90)
+};
+var supportsTruecolor = (() => {
+  if (!colorEnabled) return false;
+  const t = process.env.COLORTERM;
+  return t === "truecolor" || t === "24bit";
+})();
+var supports256 = (() => {
+  if (!colorEnabled) return false;
+  if (supportsTruecolor) return true;
+  return Boolean(process.env.TERM && /256/.test(process.env.TERM));
+})();
+var PALETTE_256 = [
+  33,
+  39,
+  38,
+  75,
+  81,
+  45,
+  50,
+  49,
+  43,
+  36,
+  73,
+  80,
+  86,
+  76,
+  82,
+  113,
+  119,
+  148,
+  149,
+  178,
+  184,
+  220,
+  221,
+  208,
+  209,
+  214,
+  215,
+  202,
+  203,
+  198,
+  199,
+  200,
+  207,
+  206,
+  171,
+  165,
+  135,
+  141,
+  99,
+  105,
+  129,
+  134,
+  174
+];
+var PALETTE_16 = [31, 32, 33, 34, 35, 36, 91, 92, 93, 94, 95, 96];
+var hashScope = (s) => {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = (h * 33 ^ s.charCodeAt(i)) >>> 0;
+  return h;
+};
+var hslToRgb = (h, s, l) => {
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => {
+    const k = (n + h / 30) % 12;
+    return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+  };
+  return [Math.round(f(0) * 255), Math.round(f(8) * 255), Math.round(f(4) * 255)];
+};
+var scopeColorCache = /* @__PURE__ */ new Map();
+var colorForScope = (scope) => {
+  if (!colorEnabled) return (s) => s;
+  const base = scope.split(":")[0];
+  const cached = scopeColorCache.get(base);
+  if (cached) return cached;
+  const hash = hashScope(base);
+  let fn;
+  if (supportsTruecolor) {
+    const hue = hash * 137 % 360;
+    const [r, g, b] = hslToRgb(hue, 0.4, 0.75);
+    fn = (s) => `\x1B[38;2;${r};${g};${b}m${s}\x1B[39m`;
+  } else if (supports256) {
+    const code = PALETTE_256[hash % PALETTE_256.length];
+    fn = (s) => `\x1B[38;5;${code}m${s}\x1B[39m`;
+  } else {
+    const code = PALETTE_16[hash % PALETTE_16.length];
+    fn = (s) => `\x1B[${code}m${s}\x1B[39m`;
+  }
+  scopeColorCache.set(base, fn);
+  return fn;
+};
+var pad2 = (n) => n < 10 ? `0${n}` : String(n);
+var formatTime = (d) => `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+var SCOPE_WIDTH = 10;
+var padScope = (scope) => scope.length >= SCOPE_WIDTH ? scope : scope + " ".repeat(SCOPE_WIDTH - scope.length);
+var SYMBOLS = {
+  debug: "\xB7",
+  info: "\u2192",
+  warn: "\u26A0",
+  error: "\u2717",
+  success: "\u2713",
+  ready: "\u2713",
+  neutral: "\u2022"
+};
+var SYMBOL_COLOR = {
+  debug: c.dim,
+  info: c.cyan,
+  warn: c.yellow,
+  error: c.red,
+  success: c.green,
+  ready: c.green,
+  neutral: c.gray
+};
+var VARIANT_LEVEL = {
+  debug: "debug",
+  info: "info",
+  neutral: "info",
+  success: "info",
+  ready: "info",
+  warn: "warn",
+  error: "error"
+};
+var currentLevel = parseLevel(process.env.LOG_LEVEL);
+var setLogLevel = (level) => {
+  currentLevel = level;
+};
+var stringifyArg = (a) => {
+  if (a instanceof Error) return a.stack ?? a.message;
+  if (typeof a === "string") return a;
+  try {
+    return JSON.stringify(a);
+  } catch {
+    return String(a);
+  }
+};
+var write = (variant, scope, msg, extras) => {
+  if (LEVELS[VARIANT_LEVEL[variant]] < LEVELS[currentLevel]) return;
+  const stream = variant === "warn" || variant === "error" ? process.stderr : process.stdout;
+  const time = c.gray(formatTime(/* @__PURE__ */ new Date()));
+  const symbol = SYMBOL_COLOR[variant](SYMBOLS[variant]);
+  const scopeText = colorForScope(scope)(padScope(scope));
+  const tail = extras.length > 0 ? " " + extras.map(stringifyArg).join(" ") : "";
+  stream.write(`${time} ${symbol} ${scopeText} ${msg}${tail}
+`);
+};
+var createLogger = (scope) => ({
+  debug: (msg, ...extras) => write("debug", scope, msg, extras),
+  info: (msg, ...extras) => write("info", scope, msg, extras),
+  warn: (msg, ...extras) => write("warn", scope, msg, extras),
+  error: (msg, ...extras) => write("error", scope, msg, extras),
+  success: (msg, ...extras) => write("success", scope, msg, extras),
+  ready: (msg, ...extras) => write("ready", scope, msg, extras),
+  item: (msg, ...extras) => write("neutral", scope, msg, extras),
+  child: (subscope) => createLogger(`${scope}:${subscope}`)
+});
+var formatError = (err) => err instanceof Error ? err.message : String(err);
+var url = (s) => c.cyan(s);
+var muted = (s) => c.dim(s);
+var num = (s) => c.bold(String(s));
+
 // src/index.ts
 var getTextContent = (message) => {
   if (typeof message.content === "string") return message.content;
@@ -448,7 +631,13 @@ var defineTool = (definition) => definition;
 export {
   FEATURE_DOMAIN_ORDER,
   ONBOARDING_FIELDS,
+  createLogger,
   defineTool,
   fieldsForScope,
-  getTextContent
+  formatError,
+  getTextContent,
+  muted,
+  num,
+  setLogLevel,
+  url
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/sdk",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "description": "Core types and utilities for building Poncho skills",
   "repository": {
     "type": "git",

package/src/api-types.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared API response types used by both the CLI server and the client SDK.
+ * Defining them here ensures compile-time drift detection between the two.
+ */
+
+export interface ApiApprovalResponse {
+  ok: true;
+  approvalId: string;
+  approved: boolean;
+  batchComplete?: boolean;
+}
+
+export interface ApiStopRunResponse {
+  ok: true;
+  stopped: boolean;
+  runId?: string;
+}
+
+export interface ApiCompactResponse {
+  compacted: boolean;
+  messagesBefore: number;
+  messagesAfter: number;
+  warning?: string;
+}
+
+export interface ApiSubagentSummary {
+  conversationId: string;
+  title: string;
+  task: string;
+  status: string;
+  messageCount: number;
+  hasPendingApprovals: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ApiThreadSummary {
+  conversationId: string;
+  parentConversationId: string;
+  parentMessageId: string;
+  title: string;
+  parentMessageSummary?: string;
+  messageCount: number;
+  /** messageCount - snapshotLength: number of replies posted into the thread. */
+  replyCount: number;
+  snapshotLength: number;
+  createdAt: number;
+  updatedAt: number;
+  /** Same as updatedAt; named for the inline-row UI. */
+  lastReplyAt: number;
+}
+
+export interface ApiThreadListResponse {
+  threads: ApiThreadSummary[];
+}
+
+export interface ApiCreateThreadRequest {
+  parentMessageId: string;
+  title?: string;
+}
+
+export interface ApiCreateThreadResponse {
+  thread: ApiThreadSummary;
+  conversationId: string;
+}
+
+export interface ApiSecretEntry {
+  name: string;
+  label?: string;
+  isSet: boolean;
+}
+
+export interface ApiSlashCommand {
+  command: string;
+  description: string;
+  type: "command" | "skill";
+}
+
+export interface ApiVfsEntry {
+  name: string;
+  type: "file" | "directory" | "symlink";
+  size: number;
+  mimeType: string | null;
+  updatedAt: number | null;
+}
+
+export interface ApiVfsListResponse {
+  path: string;
+  entries: ApiVfsEntry[];
+  usage: { fileCount: number; totalBytes: number };
+}
+
+export interface ApiVfsWriteResponse {
+  path: string;
+  size: number;
+  mimeType: string | null;
+  updatedAt: number;
+}

package/src/index.ts

@@ -109,6 +109,7 @@ export const defineTool = <
 ): ToolDefinition<TInput, TOutput> => definition;
 
 export * from "./config-registry.js";
+export * from "./api-types.js";
 
 export interface FileInput {
   /** base64 data, data: URI, or https:// URL */
@@ -165,7 +166,7 @@ export interface AgentFailure {
 export type AgentEvent =
   | { type: "run:started"; runId: string; agentId: string; contextWindow?: number }
   | { type: "run:completed"; runId: string; result: RunResult; pendingSubagents?: boolean }
-  | { type: "run:cancelled"; runId: string }
+  | { type: "run:cancelled"; runId: string; messages?: Message[] }
   | { type: "run:error"; runId: string; error: AgentFailure }
   | { type: "step:started"; step: number }
   | { type: "step:completed"; step: number; duration: number }
@@ -225,3 +226,13 @@ export type AgentEvent =
     }
   | { type: "subagents:pending" }
   | { type: "compaction:warning"; reason: string };
+
+export {
+  createLogger,
+  setLogLevel,
+  formatError,
+  url,
+  muted,
+  num,
+  type Logger,
+} from "./logger.js";

package/src/logger.ts

@@ -0,0 +1,199 @@
+// Tiny zero-dependency logger for the dev server.
+//
+// Format: `HH:mm:ss <symbol> <scope-padded> <message>`
+//   10:23:45 ✓ poncho     dev server ready at http://localhost:3000
+//   10:25:01 ✗ poncho     internal error: ...
+//
+// Honors `NO_COLOR` / `FORCE_COLOR` and `LOG_LEVEL` (debug|info|warn|error|silent).
+
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40, silent: 100 } as const;
+type LevelName = keyof typeof LEVELS;
+
+const parseLevel = (raw: string | undefined): LevelName => {
+  const v = (raw ?? "").trim().toLowerCase();
+  return v in LEVELS ? (v as LevelName) : "info";
+};
+
+const colorEnabled = ((): boolean => {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") return true;
+  return Boolean(process.stdout.isTTY);
+})();
+
+const wrap = (open: number, close = 0): ((s: string) => string) =>
+  colorEnabled
+    ? (s: string) => `\x1b[${open}m${s}\x1b[${close}m`
+    : (s: string) => s;
+
+const c = {
+  dim: wrap(2, 22),
+  bold: wrap(1, 22),
+  red: wrap(31),
+  green: wrap(32),
+  yellow: wrap(33),
+  blue: wrap(34),
+  magenta: wrap(35),
+  cyan: wrap(36),
+  gray: wrap(90),
+};
+
+// Per-scope colors. Each scope name gets a stable, distinct color derived
+// from a hash of its base name (so children like `cron:hourly_check` share
+// the parent's color). Truecolor → unique hue per scope (best). 256-color
+// fallback → curated palette. 16-color fallback → small palette.
+const supportsTruecolor = ((): boolean => {
+  if (!colorEnabled) return false;
+  const t = process.env.COLORTERM;
+  return t === "truecolor" || t === "24bit";
+})();
+
+const supports256 = ((): boolean => {
+  if (!colorEnabled) return false;
+  if (supportsTruecolor) return true;
+  return Boolean(process.env.TERM && /256/.test(process.env.TERM));
+})();
+
+const PALETTE_256 = [
+  33, 39, 38, 75, 81, 45, 50, 49, 43, 36, 73, 80, 86, 76, 82, 113,
+  119, 148, 149, 178, 184, 220, 221, 208, 209, 214, 215, 202, 203,
+  198, 199, 200, 207, 206, 171, 165, 135, 141, 99, 105, 129, 134, 174,
+];
+const PALETTE_16 = [31, 32, 33, 34, 35, 36, 91, 92, 93, 94, 95, 96];
+
+const hashScope = (s: string): number => {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h * 33) ^ s.charCodeAt(i)) >>> 0;
+  return h;
+};
+
+const hslToRgb = (h: number, s: number, l: number): [number, number, number] => {
+  const a = s * Math.min(l, 1 - l);
+  const f = (n: number): number => {
+    const k = (n + h / 30) % 12;
+    return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+  };
+  return [Math.round(f(0) * 255), Math.round(f(8) * 255), Math.round(f(4) * 255)];
+};
+
+const scopeColorCache = new Map<string, (s: string) => string>();
+const colorForScope = (scope: string): ((s: string) => string) => {
+  if (!colorEnabled) return (s) => s;
+  const base = scope.split(":")[0]!;
+  const cached = scopeColorCache.get(base);
+  if (cached) return cached;
+  const hash = hashScope(base);
+  let fn: (s: string) => string;
+  if (supportsTruecolor) {
+    // Spread hues using the golden-angle multiplier for good visual distance
+    // between consecutive scopes. Mid-range S/L reads on dark and light bgs.
+    const hue = (hash * 137) % 360;
+    // Soft pastel: low saturation, high lightness — readable on dark and
+    // light backgrounds without being eye-grabbing.
+    const [r, g, b] = hslToRgb(hue, 0.40, 0.75);
+    fn = (s: string) => `\x1b[38;2;${r};${g};${b}m${s}\x1b[39m`;
+  } else if (supports256) {
+    const code = PALETTE_256[hash % PALETTE_256.length];
+    fn = (s: string) => `\x1b[38;5;${code}m${s}\x1b[39m`;
+  } else {
+    const code = PALETTE_16[hash % PALETTE_16.length];
+    fn = (s: string) => `\x1b[${code}m${s}\x1b[39m`;
+  }
+  scopeColorCache.set(base, fn);
+  return fn;
+};
+
+const pad2 = (n: number): string => (n < 10 ? `0${n}` : String(n));
+const formatTime = (d: Date): string =>
+  `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+
+const SCOPE_WIDTH = 10;
+const padScope = (scope: string): string =>
+  scope.length >= SCOPE_WIDTH ? scope : scope + " ".repeat(SCOPE_WIDTH - scope.length);
+
+type Variant = "debug" | "info" | "warn" | "error" | "success" | "ready" | "neutral";
+
+const SYMBOLS: Record<Variant, string> = {
+  debug: "·",
+  info: "→",
+  warn: "⚠",
+  error: "✗",
+  success: "✓",
+  ready: "✓",
+  neutral: "•",
+};
+
+const SYMBOL_COLOR: Record<Variant, (s: string) => string> = {
+  debug: c.dim,
+  info: c.cyan,
+  warn: c.yellow,
+  error: c.red,
+  success: c.green,
+  ready: c.green,
+  neutral: c.gray,
+};
+
+const VARIANT_LEVEL: Record<Variant, LevelName> = {
+  debug: "debug",
+  info: "info",
+  neutral: "info",
+  success: "info",
+  ready: "info",
+  warn: "warn",
+  error: "error",
+};
+
+let currentLevel: LevelName = parseLevel(process.env.LOG_LEVEL);
+
+export const setLogLevel = (level: LevelName): void => {
+  currentLevel = level;
+};
+
+const stringifyArg = (a: unknown): string => {
+  if (a instanceof Error) return a.stack ?? a.message;
+  if (typeof a === "string") return a;
+  try {
+    return JSON.stringify(a);
+  } catch {
+    return String(a);
+  }
+};
+
+const write = (variant: Variant, scope: string, msg: string, extras: unknown[]): void => {
+  if (LEVELS[VARIANT_LEVEL[variant]] < LEVELS[currentLevel]) return;
+  const stream = variant === "warn" || variant === "error" ? process.stderr : process.stdout;
+  const time = c.gray(formatTime(new Date()));
+  const symbol = SYMBOL_COLOR[variant](SYMBOLS[variant]);
+  const scopeText = colorForScope(scope)(padScope(scope));
+  const tail = extras.length > 0 ? " " + extras.map(stringifyArg).join(" ") : "";
+  stream.write(`${time} ${symbol} ${scopeText} ${msg}${tail}\n`);
+};
+
+export type Logger = {
+  debug: (msg: string, ...extras: unknown[]) => void;
+  info: (msg: string, ...extras: unknown[]) => void;
+  warn: (msg: string, ...extras: unknown[]) => void;
+  error: (msg: string, ...extras: unknown[]) => void;
+  success: (msg: string, ...extras: unknown[]) => void;
+  ready: (msg: string, ...extras: unknown[]) => void;
+  item: (msg: string, ...extras: unknown[]) => void;
+  child: (subscope: string) => Logger;
+};
+
+export const createLogger = (scope: string): Logger => ({
+  debug: (msg, ...extras) => write("debug", scope, msg, extras),
+  info: (msg, ...extras) => write("info", scope, msg, extras),
+  warn: (msg, ...extras) => write("warn", scope, msg, extras),
+  error: (msg, ...extras) => write("error", scope, msg, extras),
+  success: (msg, ...extras) => write("success", scope, msg, extras),
+  ready: (msg, ...extras) => write("ready", scope, msg, extras),
+  item: (msg, ...extras) => write("neutral", scope, msg, extras),
+  child: (subscope) => createLogger(`${scope}:${subscope}`),
+});
+
+export const formatError = (err: unknown): string =>
+  err instanceof Error ? err.message : String(err);
+
+// Highlight helpers — use sparingly inside messages
+export const url = (s: string): string => c.cyan(s);
+export const muted = (s: string): string => c.dim(s);
+export const num = (s: string | number): string => c.bold(String(s));