@poncho-ai/sdk 1.8.0 → 1.9.0

package/.turbo/turbo-build.log

@@ -1,14 +1,14 @@
 
-> @poncho-ai/sdk@1.7.1 build /Users/cesar/Dev/latitude/poncho-ai/packages/sdk
+> @poncho-ai/sdk@1.9.0 build /home/runner/work/poncho-ai/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 12.46 KB
-ESM ⚡️ Build success in 21ms
-DTS Build start
-DTS ⚡️ Build success in 1577ms
-DTS dist/index.d.ts 24.03 KB
+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 17.24 KB
+ESM ⚡️ Build success in 23ms
+DTS Build start
+DTS ⚡️ Build success in 1448ms
+DTS dist/index.d.ts 27.76 KB

package/CHANGELOG.md

@@ -1,5 +1,150 @@
 # @poncho-ai/sdk
 
+## 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
+
+- Add VfsAccess interface and expand ToolContext with optional `vfs` field for tenant-scoped virtual filesystem access in tool handlers.
+
 ## 1.8.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -528,6 +528,99 @@ 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";
+}
+
+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;
@@ -570,6 +663,27 @@ interface Message {
 }
 /** Extract the text content from a message, regardless of content format. */
 declare const getTextContent: (message: Message) => string;
+/** Virtual filesystem scoped to the current tenant. Available when VFS is enabled. */
+interface VfsAccess {
+    readFile(path: string): Promise<Uint8Array>;
+    readText(path: string): Promise<string>;
+    writeFile(path: string, content: Uint8Array, mimeType?: string): Promise<void>;
+    writeText(path: string, content: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<{
+        size: number;
+        isDirectory: boolean;
+        mimeType?: string;
+        updatedAt: number;
+    }>;
+    readdir(path: string): Promise<string[]>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+}
 interface ToolContext {
     runId: string;
     agentId: string;
@@ -580,6 +694,8 @@ interface ToolContext {
     conversationId?: string;
     /** The tenant ID when running in multi-tenant mode. */
     tenantId?: string;
+    /** Virtual filesystem scoped to the current tenant. Available when VFS is enabled. */
+    vfs?: VfsAccess;
 }
 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> {
@@ -685,6 +801,7 @@ type AgentEvent = {
 } | {
     type: "tool:completed";
     tool: string;
+    input?: unknown;
     output: unknown;
     duration: number;
     outputTokenEstimate?: number;
@@ -771,4 +888,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, 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 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.0",
+  "version": "1.9.0",
   "description": "Core types and utilities for building Poncho skills",
   "repository": {
     "type": "git",

package/src/api-types.ts

@@ -0,0 +1,77 @@
+/**
+ * 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";
+}

package/src/index.ts

@@ -50,6 +50,24 @@ export const getTextContent = (message: Message): string => {
     .join("");
 };
 
+/** Virtual filesystem scoped to the current tenant. Available when VFS is enabled. */
+export interface VfsAccess {
+  readFile(path: string): Promise<Uint8Array>;
+  readText(path: string): Promise<string>;
+  writeFile(path: string, content: Uint8Array, mimeType?: string): Promise<void>;
+  writeText(path: string, content: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  stat(path: string): Promise<{
+    size: number;
+    isDirectory: boolean;
+    mimeType?: string;
+    updatedAt: number;
+  }>;
+  readdir(path: string): Promise<string[]>;
+  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
+  rm(path: string, options?: { recursive?: boolean }): Promise<void>;
+}
+
 export interface ToolContext {
   runId: string;
   agentId: string;
@@ -60,6 +78,8 @@ export interface ToolContext {
   conversationId?: string;
   /** The tenant ID when running in multi-tenant mode. */
   tenantId?: string;
+  /** Virtual filesystem scoped to the current tenant. Available when VFS is enabled. */
+  vfs?: VfsAccess;
 }
 
 export type ToolHandler<TInput extends Record<string, unknown>, TOutput> = (
@@ -89,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 */
@@ -154,7 +175,7 @@ export type AgentEvent =
   | { type: "model:response"; usage: TokenUsage }
   | { type: "tool:generating"; tool: string; toolCallId: string }
   | { type: "tool:started"; tool: string; input: unknown }
-  | { type: "tool:completed"; tool: string; output: unknown; duration: number; outputTokenEstimate?: number }
+  | { type: "tool:completed"; tool: string; input?: unknown; output: unknown; duration: number; outputTokenEstimate?: number }
   | { type: "tool:error"; tool: string; error: string; recoverable: boolean }
   | {
       type: "tool:approval:required";
@@ -205,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));

package/.turbo/turbo-lint.log

@@ -1,6 +0,0 @@
-
-> @poncho-ai/sdk@0.6.0 lint /Users/cesar/Dev/latitude/poncho-ai/packages/sdk
-> eslint src/
-
-sh: eslint: command not found
- ELIFECYCLE  Command failed.