@poncho-ai/harness 0.34.1 → 0.36.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { LanguageModel } from 'ai';
 import * as _poncho_ai_sdk from '@poncho-ai/sdk';
-import { Message, ToolDefinition, RunResult, AgentFailure, ToolContext, RunInput, AgentEvent, JsonSchema } from '@poncho-ai/sdk';
+import { Message, ToolContext, ToolDefinition, JsonSchema, RunResult, AgentFailure, RunInput, AgentEvent } from '@poncho-ai/sdk';
 export { ToolDefinition, defineTool } from '@poncho-ai/sdk';
 import { z } from 'zod';
+import { IFileSystem, BufferEncoding, FsStat, FileContent, MkdirOptions, RmOptions, CpOptions, Bash } from 'just-bash';
 
 interface AgentModelConfig {
     provider: string;
@@ -188,40 +189,25 @@ interface Conversation {
     subagentCallbackCount?: number;
     runningCallbackSince?: number;
     lastActivityAt?: number;
-    /** Harness-internal message chain preserved across continuation runs.
-     *  Cleared when a run completes without continuation. */
     _continuationMessages?: Message[];
-    /** Number of continuation pickups for the current multi-step run.
-     *  Reset when a run completes without continuation. Used to enforce
-     *  a maximum continuation count across all entry points. */
     _continuationCount?: number;
-    /** Full structured message chain from the last harness run, including
-     *  tool-call and tool-result messages the model needs for context.
-     *  Unlike `_continuationMessages`, this is always set after a run
-     *  and does NOT signal that a continuation is pending. */
     _harnessMessages?: Message[];
-    /** Archived full-fidelity tool results keyed by toolResultId. */
     _toolResultArchive?: Record<string, ArchivedToolResult$1>;
     createdAt: number;
     updatedAt: number;
 }
 interface ConversationStore {
-    list(ownerId?: string): Promise<Conversation[]>;
-    listSummaries(ownerId?: string): Promise<ConversationSummary[]>;
+    list(ownerId?: string, tenantId?: string | null): Promise<Conversation[]>;
+    listSummaries(ownerId?: string, tenantId?: string | null): Promise<ConversationSummary[]>;
     get(conversationId: string): Promise<Conversation | undefined>;
-    create(ownerId?: string, title?: string): Promise<Conversation>;
+    create(ownerId?: string, title?: string, tenantId?: string | null): Promise<Conversation>;
     update(conversation: Conversation): Promise<void>;
     rename(conversationId: string, title: string): Promise<Conversation | undefined>;
     delete(conversationId: string): Promise<boolean>;
     appendSubagentResult(conversationId: string, result: PendingSubagentResult): Promise<void>;
-    /**
-     * Atomically clear `runningCallbackSince` without clobbering other fields.
-     * Returns the conversation as it exists after the clear (with current
-     * `pendingSubagentResults`).
-     */
     clearCallbackLock(conversationId: string): Promise<Conversation | undefined>;
 }
-type StateProviderName = "local" | "memory" | "redis" | "upstash" | "dynamodb";
+type StateProviderName = "local" | "memory" | "sqlite" | "postgresql" | "redis" | "upstash" | "dynamodb";
 interface StateConfig {
     provider?: StateProviderName;
     ttl?: number;
@@ -245,10 +231,10 @@ declare class InMemoryConversationStore implements ConversationStore {
     constructor(ttlSeconds?: number);
     private isExpired;
     private purgeExpired;
-    list(ownerId?: string): Promise<Conversation[]>;
-    listSummaries(ownerId?: string): Promise<ConversationSummary[]>;
+    list(ownerId?: string, tenantId?: string | null): Promise<Conversation[]>;
+    listSummaries(ownerId?: string, tenantId?: string | null): Promise<ConversationSummary[]>;
     get(conversationId: string): Promise<Conversation | undefined>;
-    create(ownerId?: string, title?: string): Promise<Conversation>;
+    create(ownerId?: string, title?: string, tenantId?: string | null): Promise<Conversation>;
     update(conversation: Conversation): Promise<void>;
     rename(conversationId: string, title: string): Promise<Conversation | undefined>;
     delete(conversationId: string): Promise<boolean>;
@@ -261,6 +247,7 @@ type ConversationSummary = {
     updatedAt: number;
     createdAt?: number;
     ownerId: string;
+    tenantId?: string | null;
     parentConversationId?: string;
     messageCount?: number;
     hasPendingApprovals?: boolean;
@@ -270,11 +257,11 @@ type ConversationSummary = {
         platformThreadId: string;
     };
 };
-declare const createStateStore: (config?: StateConfig, options?: {
+declare const createStateStore: (config?: StateConfig, _options?: {
     workingDir?: string;
     agentId?: string;
 }) => StateStore;
-declare const createConversationStore: (config?: StateConfig, options?: {
+declare const createConversationStore: (config?: StateConfig, _options?: {
     workingDir?: string;
     agentId?: string;
 }) => ConversationStore;
@@ -301,8 +288,9 @@ interface MemoryStore {
 }
 declare const createMemoryStore: (agentId: string, config?: MemoryConfig, options?: {
     workingDir?: string;
+    tenantId?: string;
 }) => MemoryStore;
-declare const createMemoryTools: (store: MemoryStore, options?: {
+declare const createMemoryTools: (store: MemoryStore | ((context: ToolContext) => MemoryStore), options?: {
     maxRecallConversations?: number;
 }) => ToolDefinition[];
 
@@ -328,10 +316,24 @@ declare class LocalMcpBridge {
     private readonly toolCatalog;
     private readonly unavailableServers;
     private readonly authFailedServers;
+    private envResolver?;
+    /**
+     * Set a resolver for per-tenant env vars (e.g. MCP auth tokens).
+     * Called by the harness after creating the secrets store.
+     */
+    setEnvResolver(resolver: (tenantId: string | undefined, envName: string) => Promise<string | undefined>): void;
     constructor(config: McpConfig | undefined);
     private getServerName;
     private log;
+    /** Set of servers where discovery was deferred (no default token, has env resolver). */
+    private readonly deferredDiscoveryServers;
     discoverTools(): Promise<void>;
+    /**
+     * Run deferred discovery and return ToolDefinitions for all newly discovered tools.
+     * Call this during run() so the tools are available to the model immediately.
+     */
+    discoverAndLoadDeferred(tenantId: string): Promise<ToolDefinition[]>;
+    private tryDeferredDiscovery;
     startLocalServers(): Promise<void>;
     stopLocalServers(): Promise<void>;
     listServers(): RemoteMcpServerConfig[];
@@ -344,12 +346,17 @@ declare class LocalMcpBridge {
     toSerializableConfig(): McpConfig;
     getLocalServers(): never[];
     listDiscoveredTools(serverName?: string): string[];
+    hasDeferredServers(): boolean;
+    /**
+     * Return ToolDefinitions for catalog tools not already registered in the dispatcher.
+     */
+    getUnregisteredTools(registeredNames: Set<string>): ToolDefinition[];
     loadTools(requestedPatterns: string[]): Promise<ToolDefinition[]>;
     private toToolDefinitions;
 }
 
 interface StorageConfig {
-    provider?: "local" | "memory" | "redis" | "upstash" | "dynamodb";
+    provider?: "local" | "memory" | "sqlite" | "postgresql" | "redis" | "upstash" | "dynamodb";
     urlEnv?: string;
     tokenEnv?: string;
     table?: string;
@@ -362,6 +369,10 @@ interface StorageConfig {
         enabled?: boolean;
         maxRecallConversations?: number;
     };
+    limits?: {
+        maxFileSize?: number;
+        maxTotalStorage?: number;
+    };
 }
 interface UploadsConfig {
     provider?: "local" | "vercel-blob" | "s3";
@@ -401,6 +412,99 @@ interface MessagingChannelConfig {
     maxSendsPerRun?: number;
     allowedUserIds?: number[];
 }
+interface IsolateBinding {
+    description: string;
+    inputSchema: JsonSchema;
+    handler: (input: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+/**
+ * Network access configuration for the bash sandbox (curl, wget).
+ * Network access is disabled by default — you must explicitly allow URLs.
+ */
+interface NetworkConfig {
+    /**
+     * List of allowed URL prefixes. Each entry must be a full origin (scheme + host),
+     * optionally followed by a path prefix.
+     *
+     * Examples:
+     * - `"https://api.example.com"` — allows all paths on this origin
+     * - `"https://api.example.com/v1/"` — allows only paths starting with /v1/
+     *
+     * Entries can be plain strings or objects with header transforms for credentials brokering:
+     * ```
+     * { url: "https://api.example.com", transform: [{ headers: { "Authorization": "Bearer ..." } }] }
+     * ```
+     */
+    allowedUrls?: (string | {
+        url: string;
+        transform?: {
+            headers: Record<string, string>;
+        }[];
+    })[];
+    /** Allowed HTTP methods. Defaults to `["GET", "HEAD"]`. */
+    allowedMethods?: ("GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS")[];
+    /** Bypass the allow-list and permit all URLs and methods. Only use in trusted environments. */
+    dangerouslyAllowAll?: boolean;
+    /** Maximum number of redirects to follow. Default: 20. */
+    maxRedirects?: number;
+    /** Request timeout in milliseconds. Default: 30000. */
+    timeoutMs?: number;
+    /** Maximum response body size in bytes. Default: 10MB. */
+    maxResponseSize?: number;
+    /** Reject URLs resolving to private/loopback IPs (SSRF protection). Default: false. */
+    denyPrivateRanges?: boolean;
+}
+interface BashExecutionLimits {
+    /** Maximum function call/recursion depth. Default: 100. */
+    maxCallDepth?: number;
+    /** Maximum number of commands to execute. Default: 10000. */
+    maxCommandCount?: number;
+    /** Maximum loop iterations for while/for/until. Default: 10000. */
+    maxLoopIterations?: number;
+    /** Maximum total output size (stdout + stderr) in bytes. Default: 10MB. */
+    maxOutputSize?: number;
+    /** Maximum string length in bytes. Default: 10MB. */
+    maxStringLength?: number;
+    /** Maximum array elements. Default: 100000. */
+    maxArrayElements?: number;
+}
+interface BashConfig {
+    /**
+     * Whitelist of allowed commands. When set, only these commands are available.
+     * Omit to allow all built-in commands.
+     *
+     * @example ["cat", "grep", "jq", "echo", "ls", "head", "tail", "wc", "sort"]
+     */
+    commands?: string[];
+    /** Execution limits to prevent runaway scripts. */
+    executionLimits?: BashExecutionLimits;
+    /** Enable python3/python commands in the sandbox. Default: false. */
+    python?: boolean;
+    /** Enable js-exec/node commands via QuickJS in the sandbox. Default: false. */
+    javascript?: boolean;
+    /** Environment variables injected into every bash session. */
+    env?: Record<string, string>;
+}
+interface IsolateConfig {
+    /** V8 isolate memory limit in MB. Default: 128 */
+    memoryLimit?: number;
+    /** Execution timeout in ms. Default: 10000 */
+    timeLimit?: number;
+    /** Max combined stdout+stderr in bytes. Default: 65536 */
+    outputLimit?: number;
+    /** Max code input size in bytes. Default: 102400 (100KB) */
+    codeLimit?: number;
+    /** npm packages to bundle and make available via require() */
+    libraries?: string[];
+    /** External API access */
+    apis?: {
+        fetch?: {
+            allowedDomains: string[];
+        };
+    };
+    /** Builder-defined custom bindings injected into the isolate */
+    bindings?: Record<string, IsolateBinding>;
+}
 interface PonchoConfig extends McpConfig {
     harness?: string;
     messaging?: MessagingChannelConfig[];
@@ -467,8 +571,23 @@ interface PonchoConfig extends McpConfig {
         /** Cron expression controlling how often the reminder poll runs (local and serverless). Default: every 10 minutes. */
         pollSchedule?: string;
     };
+    /**
+     * Declare env var names that tenants can self-manage via the web UI or API.
+     * Key = env var name, value = human-readable label shown in the settings panel.
+     * Example: { LINEAR_API_KEY: "Linear API Key", STRIPE_KEY: "Stripe Secret Key" }
+     */
+    tenantSecrets?: Record<string, string>;
     /** Set to `false` to disable the built-in web UI (headless / API-only mode). */
     webUi?: false;
+    /** Enable sandboxed V8 isolate code execution. */
+    isolate?: IsolateConfig;
+    /**
+     * Network access for sandboxed tools (bash curl/wget, isolate fetch).
+     * Disabled by default — you must explicitly allow URLs.
+     */
+    network?: NetworkConfig;
+    /** Bash sandbox configuration. */
+    bash?: BashConfig;
     /** Enable browser automation tools. Set `true` for defaults, or provide config. */
     browser?: boolean | {
         viewport?: {
@@ -506,6 +625,7 @@ declare const createDeleteDirectoryTool: (workingDir: string) => ToolDefinition;
 declare const ponchoDocsTool: ToolDefinition;
 
 declare const PONCHO_UPLOAD_SCHEME = "poncho-upload://";
+declare const VFS_SCHEME = "vfs://";
 interface UploadStore {
     put(key: string, data: Buffer, mediaType: string): Promise<string>;
     get(urlOrKey: string): Promise<Buffer>;
@@ -556,6 +676,10 @@ interface TodoItem {
     createdAt: number;
     updatedAt: number;
 }
+interface TodoStore {
+    get(conversationId: string): Promise<TodoItem[]>;
+    set(conversationId: string, todos: TodoItem[]): Promise<void>;
+}
 
 type ReminderStatus = "pending" | "fired" | "cancelled";
 interface Reminder {
@@ -567,6 +691,7 @@ interface Reminder {
     createdAt: number;
     conversationId: string;
     ownerId?: string;
+    tenantId?: string | null;
 }
 interface ReminderStore {
     list(): Promise<Reminder[]>;
@@ -576,14 +701,102 @@ interface ReminderStore {
         timezone?: string;
         conversationId: string;
         ownerId?: string;
+        tenantId?: string | null;
     }): Promise<Reminder>;
     cancel(id: string): Promise<Reminder>;
     delete(id: string): Promise<void>;
 }
-declare const createReminderStore: (agentId: string, config?: StateConfig, options?: {
+declare const createReminderStore: (_agentId: string, _config?: StateConfig, _options?: {
     workingDir?: string;
 }) => ReminderStore;
 
+interface VfsStat {
+    type: "file" | "directory" | "symlink";
+    size: number;
+    mode: number;
+    mimeType?: string;
+    symlinkTarget?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+interface VfsDirEntry {
+    name: string;
+    type: "file" | "directory" | "symlink";
+}
+interface StorageEngine {
+    /** Run migrations and prepare the storage backend. */
+    initialize(): Promise<void>;
+    /** Gracefully release resources. */
+    close(): Promise<void>;
+    conversations: {
+        list(ownerId?: string, tenantId?: string | null): Promise<ConversationSummary[]>;
+        get(conversationId: string): Promise<Conversation | undefined>;
+        create(ownerId?: string, title?: string, tenantId?: string | null): Promise<Conversation>;
+        update(conversation: Conversation): Promise<void>;
+        rename(conversationId: string, title: string): Promise<Conversation | undefined>;
+        delete(conversationId: string): Promise<boolean>;
+        search(query: string, tenantId?: string | null): Promise<ConversationSummary[]>;
+        appendSubagentResult(conversationId: string, result: PendingSubagentResult): Promise<void>;
+        clearCallbackLock(conversationId: string): Promise<Conversation | undefined>;
+    };
+    memory: {
+        get(tenantId?: string | null): Promise<MainMemory>;
+        update(content: string, tenantId?: string | null): Promise<MainMemory>;
+    };
+    todos: {
+        get(conversationId: string): Promise<TodoItem[]>;
+        set(conversationId: string, todos: TodoItem[]): Promise<void>;
+    };
+    reminders: {
+        list(tenantId?: string | null): Promise<Reminder[]>;
+        create(input: {
+            task: string;
+            scheduledAt: number;
+            timezone?: string;
+            conversationId: string;
+            ownerId?: string;
+            tenantId?: string | null;
+        }): Promise<Reminder>;
+        cancel(id: string): Promise<Reminder>;
+        delete(id: string): Promise<void>;
+    };
+    vfs: {
+        readFile(tenantId: string, path: string): Promise<Uint8Array>;
+        writeFile(tenantId: string, path: string, content: Uint8Array, mimeType?: string): Promise<void>;
+        appendFile(tenantId: string, path: string, content: Uint8Array): Promise<void>;
+        deleteFile(tenantId: string, path: string): Promise<void>;
+        deleteDir(tenantId: string, path: string, recursive?: boolean): Promise<void>;
+        stat(tenantId: string, path: string): Promise<VfsStat | undefined>;
+        readdir(tenantId: string, path: string): Promise<VfsDirEntry[]>;
+        mkdir(tenantId: string, path: string, recursive?: boolean): Promise<void>;
+        rename(tenantId: string, oldPath: string, newPath: string): Promise<void>;
+        chmod(tenantId: string, path: string, mode: number): Promise<void>;
+        utimes(tenantId: string, path: string, mtime: Date): Promise<void>;
+        symlink(tenantId: string, target: string, linkPath: string): Promise<void>;
+        readlink(tenantId: string, path: string): Promise<string>;
+        lstat(tenantId: string, path: string): Promise<VfsStat | undefined>;
+        listAllPaths(tenantId: string): string[];
+        getUsage(tenantId: string): Promise<{
+            fileCount: number;
+            totalBytes: number;
+        }>;
+    };
+}
+
+interface SecretsStore {
+    get(tenantId: string): Promise<Record<string, string>>;
+    set(tenantId: string, key: string, value: string): Promise<void>;
+    delete(tenantId: string, key: string): Promise<void>;
+    list(tenantId: string): Promise<string[]>;
+}
+declare const createSecretsStore: (_agentId: string, signingKey: string, _config?: StateConfig, options?: {
+    workingDir?: string;
+}) => SecretsStore;
+/**
+ * Resolve an env var name: check tenant secrets first, then process.env.
+ */
+declare function resolveEnv(secretsStore: SecretsStore | undefined, tenantId: string | null | undefined, envName: string): Promise<string | undefined>;
+
 declare const OPENAI_CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
 interface OpenAICodexAuthConfig {
     refreshTokenEnv?: string;
@@ -660,6 +873,7 @@ interface SubagentManager {
         task: string;
         parentConversationId: string;
         ownerId: string;
+        tenantId?: string | null;
     }): Promise<SubagentSpawnResult>;
     sendMessage(subagentId: string, message: string): Promise<SubagentSpawnResult>;
     stop(subagentId: string): Promise<void>;
@@ -720,8 +934,11 @@ declare class AgentHarness {
     readonly uploadStore?: UploadStore;
     private skillContextWindow;
     private memoryStore?;
+    private readonly tenantMemoryStores;
+    private memoryConfig?;
     private todoStore?;
     reminderStore?: ReminderStore;
+    secretsStore?: SecretsStore;
     private loadedConfig?;
     private loadedSkills;
     private skillFingerprint;
@@ -738,6 +955,10 @@ declare class AgentHarness {
     private mcpBridge?;
     private subagentManager?;
     private readonly archivedToolResultsByConversation;
+    /** Unified storage engine (replaces individual KV-backed stores). */
+    storageEngine?: StorageEngine;
+    /** Bash environment manager (creates per-tenant bash instances). */
+    private bashManager?;
     private resolveToolAccess;
     private isToolEnabled;
     private registerIfMissing;
@@ -751,6 +972,7 @@ declare class AgentHarness {
     setSubagentManager(manager: SubagentManager): void;
     private registerConfiguredBuiltInTools;
     private createGetToolResultByIdTool;
+    private createVfsAccess;
     private shouldEnableWriteTool;
     constructor(options?: HarnessOptions);
     get frontmatter(): AgentFrontmatter | undefined;
@@ -759,6 +981,11 @@ declare class AgentHarness {
     private truncateHistoricalToolResults;
     private shouldPreserveSkillToolResult;
     getTodos(conversationId: string): Promise<TodoItem[]>;
+    /**
+     * Get a memory store, optionally scoped to a tenant.
+     * Returns the default (agent-wide) store when tenantId is null/undefined.
+     */
+    private getMemoryStore;
     private listActiveSkills;
     private getAgentMcpIntent;
     private getAgentScriptIntent;
@@ -806,6 +1033,10 @@ declare class AgentHarness {
     get browserSession(): unknown;
     shutdown(): Promise<void>;
     listTools(): ToolDefinition[];
+    listSkills(): Array<{
+        name: string;
+        description: string;
+    }>;
     /**
      * Wraps the run() generator with an OTel root span (invoke_agent) so all
      * child spans (LLM calls via AI SDK, tool execution) group under one trace.
@@ -921,6 +1152,299 @@ declare class TelemetryEmitter {
     private sendOtlp;
 }
 
+declare class InMemoryEngine implements StorageEngine {
+    private readonly agentId;
+    private convs;
+    private mem;
+    private todoData;
+    private reminderData;
+    private vfsData;
+    constructor(agentId: string);
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    conversations: {
+        list: (ownerId?: string, tenantId?: string | null) => Promise<ConversationSummary[]>;
+        get: (conversationId: string) => Promise<Conversation | undefined>;
+        create: (ownerId?: string, title?: string, tenantId?: string | null) => Promise<Conversation>;
+        update: (conversation: Conversation) => Promise<void>;
+        rename: (conversationId: string, title: string) => Promise<Conversation | undefined>;
+        delete: (conversationId: string) => Promise<boolean>;
+        search: (query: string, tenantId?: string | null) => Promise<ConversationSummary[]>;
+        appendSubagentResult: (conversationId: string, result: PendingSubagentResult) => Promise<void>;
+        clearCallbackLock: (conversationId: string) => Promise<Conversation | undefined>;
+    };
+    memory: {
+        get: (tenantId?: string | null) => Promise<MainMemory>;
+        update: (content: string, tenantId?: string | null) => Promise<MainMemory>;
+    };
+    todos: {
+        get: (conversationId: string) => Promise<TodoItem[]>;
+        set: (conversationId: string, todos: TodoItem[]) => Promise<void>;
+    };
+    reminders: {
+        list: (tenantId?: string | null) => Promise<Reminder[]>;
+        create: (input: {
+            task: string;
+            scheduledAt: number;
+            timezone?: string;
+            conversationId: string;
+            ownerId?: string;
+            tenantId?: string | null;
+        }) => Promise<Reminder>;
+        cancel: (id: string) => Promise<Reminder>;
+        delete: (id: string) => Promise<void>;
+    };
+    vfs: {
+        readFile: (tenantId: string, path: string) => Promise<Uint8Array>;
+        writeFile: (tenantId: string, path: string, content: Uint8Array, mimeType?: string) => Promise<void>;
+        appendFile: (tenantId: string, path: string, content: Uint8Array) => Promise<void>;
+        deleteFile: (tenantId: string, path: string) => Promise<void>;
+        deleteDir: (tenantId: string, path: string, recursive?: boolean) => Promise<void>;
+        stat: (tenantId: string, path: string) => Promise<VfsStat | undefined>;
+        readdir: (tenantId: string, path: string) => Promise<VfsDirEntry[]>;
+        mkdir: (tenantId: string, path: string, recursive?: boolean) => Promise<void>;
+        rename: (tenantId: string, oldPath: string, newPath: string) => Promise<void>;
+        chmod: (tenantId: string, path: string, mode: number) => Promise<void>;
+        utimes: (tenantId: string, path: string, mtime: Date) => Promise<void>;
+        symlink: (tenantId: string, target: string, linkPath: string) => Promise<void>;
+        readlink: (tenantId: string, path: string) => Promise<string>;
+        lstat: (tenantId: string, path: string) => Promise<VfsStat | undefined>;
+        listAllPaths: (tenantId: string) => string[];
+        getUsage: (tenantId: string) => Promise<{
+            fileCount: number;
+            totalBytes: number;
+        }>;
+    };
+    private toSummary;
+    private ensureParentDirs;
+    private mkdirSingle;
+    private resolveSymlink;
+}
+
+/** Tag used by migrations to branch on backend. */
+type DialectTag = "sqlite" | "postgresql";
+
+interface Dialect {
+    tag: DialectTag;
+    /** Return a positional parameter placeholder. 1-indexed. */
+    param(index: number): string;
+    /** BLOB type name */
+    blob: string;
+    /** JSON type name */
+    json: string;
+    /** Current-timestamp expression */
+    now(): string;
+    /** UPSERT conflict clause for a given PK column list */
+    upsert(pkCols: string[]): string;
+}
+interface QueryRow {
+    [key: string]: unknown;
+}
+interface QueryExecutor {
+    run(sql: string, params?: unknown[]): Promise<void>;
+    get<T extends QueryRow = QueryRow>(sql: string, params?: unknown[]): Promise<T | undefined>;
+    all<T extends QueryRow = QueryRow>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Execute raw SQL (for migrations). */
+    exec(sql: string): Promise<void>;
+    /** Run multiple statements in a transaction. */
+    transaction(fn: () => Promise<void>): Promise<void>;
+}
+declare abstract class SqlStorageEngine implements StorageEngine {
+    protected readonly dialect: Dialect;
+    protected readonly agentId: string;
+    protected abstract readonly executor: QueryExecutor;
+    constructor(dialect: Dialect, agentId: string);
+    initialize(): Promise<void>;
+    abstract close(): Promise<void>;
+    /** Hook for subclass-specific setup (e.g. WAL mode). */
+    protected onBeforeInit(): Promise<void>;
+    private runMigrations;
+    conversations: {
+        list: (ownerId?: string, tenantId?: string | null) => Promise<ConversationSummary[]>;
+        get: (conversationId: string) => Promise<Conversation | undefined>;
+        create: (ownerId?: string, title?: string, tenantId?: string | null) => Promise<Conversation>;
+        update: (conversation: Conversation) => Promise<void>;
+        rename: (conversationId: string, title: string) => Promise<Conversation | undefined>;
+        delete: (conversationId: string) => Promise<boolean>;
+        search: (query: string, tenantId?: string | null) => Promise<ConversationSummary[]>;
+        appendSubagentResult: (conversationId: string, result: PendingSubagentResult) => Promise<void>;
+        clearCallbackLock: (conversationId: string) => Promise<Conversation | undefined>;
+    };
+    memory: {
+        get: (tenantId?: string | null) => Promise<MainMemory>;
+        update: (content: string, tenantId?: string | null) => Promise<MainMemory>;
+    };
+    todos: {
+        get: (conversationId: string) => Promise<TodoItem[]>;
+        set: (conversationId: string, todos: TodoItem[]) => Promise<void>;
+    };
+    reminders: {
+        list: (tenantId?: string | null) => Promise<Reminder[]>;
+        create: (input: {
+            task: string;
+            scheduledAt: number;
+            timezone?: string;
+            conversationId: string;
+            ownerId?: string;
+            tenantId?: string | null;
+        }) => Promise<Reminder>;
+        cancel: (id: string) => Promise<Reminder>;
+        delete: (id: string) => Promise<void>;
+    };
+    vfs: {
+        readFile: (tenantId: string, path: string) => Promise<Uint8Array>;
+        writeFile: (tenantId: string, path: string, content: Uint8Array, mimeType?: string) => Promise<void>;
+        appendFile: (tenantId: string, path: string, content: Uint8Array) => Promise<void>;
+        deleteFile: (tenantId: string, path: string) => Promise<void>;
+        deleteDir: (tenantId: string, path: string, recursive?: boolean) => Promise<void>;
+        stat: (tenantId: string, path: string) => Promise<VfsStat | undefined>;
+        readdir: (tenantId: string, path: string) => Promise<VfsDirEntry[]>;
+        mkdir: (tenantId: string, path: string, recursive?: boolean) => Promise<void>;
+        rename: (tenantId: string, oldPath: string, newPath: string) => Promise<void>;
+        chmod: (tenantId: string, path: string, mode: number) => Promise<void>;
+        utimes: (tenantId: string, path: string, mtime: Date) => Promise<void>;
+        symlink: (tenantId: string, target: string, linkPath: string) => Promise<void>;
+        readlink: (tenantId: string, path: string) => Promise<string>;
+        lstat: (tenantId: string, path: string) => Promise<VfsStat | undefined>;
+        listAllPaths: (_tenantId: string) => string[];
+        getUsage: (tenantId: string) => Promise<{
+            fileCount: number;
+            totalBytes: number;
+        }>;
+    };
+    private parseConversation;
+    private rowToSummary;
+    private rowToReminder;
+    protected toUint8Array(value: unknown): Uint8Array;
+    private ensureParentDirs;
+    private mkdirSingle;
+    private resolveSymlink;
+}
+
+declare class SqliteEngine extends SqlStorageEngine {
+    private db;
+    private readonly dbPath;
+    protected readonly executor: QueryExecutor;
+    constructor(options: {
+        workingDir: string;
+        agentId: string;
+        dbPath?: string;
+    });
+    protected onBeforeInit(): Promise<void>;
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+}
+
+declare class PostgresEngine extends SqlStorageEngine {
+    private sql;
+    private readonly urlEnv;
+    protected readonly executor: QueryExecutor;
+    /** In-memory path cache per tenant for sync getAllPaths(). */
+    private pathCache;
+    constructor(options: {
+        agentId: string;
+        urlEnv?: string;
+    });
+    protected onBeforeInit(): Promise<void>;
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    /** Refresh the path cache for a tenant (call before bash.exec()). */
+    refreshPathCache(tenantId: string): Promise<void>;
+    private patchVfs;
+    private query;
+    private addToPathCache;
+    private removeFromPathCache;
+}
+
+type StorageProvider = "memory" | "sqlite" | "postgresql" | "local";
+interface StorageFactoryOptions {
+    provider?: StorageProvider;
+    workingDir: string;
+    agentId: string;
+    /** Env var name for the PostgreSQL connection URL (default: DATABASE_URL). */
+    urlEnv?: string;
+    /** Override the SQLite database file path. */
+    dbPath?: string;
+}
+declare function createStorageEngine(options: StorageFactoryOptions): StorageEngine;
+
+declare function createConversationStoreFromEngine(engine: StorageEngine): ConversationStore;
+declare function createMemoryStoreFromEngine(engine: StorageEngine, tenantId?: string | null): MemoryStore;
+declare function createTodoStoreFromEngine(engine: StorageEngine): TodoStore;
+declare function createReminderStoreFromEngine(engine: StorageEngine): ReminderStore;
+
+declare class PonchoFsAdapter implements IFileSystem {
+    private engine;
+    private tenantId;
+    private limits;
+    constructor(engine: StorageEngine, tenantId: string, limits: {
+        maxFileSize: number;
+        maxTotalStorage: number;
+    });
+    readFile(path: string, _options?: {
+        encoding?: BufferEncoding | null;
+    } | BufferEncoding): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<Array<{
+        name: string;
+        isFile: boolean;
+        isDirectory: boolean;
+        isSymbolicLink: boolean;
+    }>>;
+    writeFile(path: string, content: FileContent, _options?: {
+        encoding?: BufferEncoding;
+    } | BufferEncoding): Promise<void>;
+    appendFile(path: string, content: FileContent, _options?: {
+        encoding?: BufferEncoding;
+    } | BufferEncoding): Promise<void>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    resolvePath(base: string, path: string): string;
+    realpath(path: string): Promise<string>;
+    getAllPaths(): string[];
+    chmod(path: string, mode: number): Promise<void>;
+    utimes(path: string, _atime: Date, mtime: Date): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    link(existingPath: string, newPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    lstat(path: string): Promise<FsStat>;
+}
+
+declare class BashEnvironmentManager {
+    private engine;
+    private limits;
+    private environments;
+    private readonly workingDir;
+    private readonly bashOptions;
+    constructor(engine: StorageEngine, limits: {
+        maxFileSize: number;
+        maxTotalStorage: number;
+    }, workingDir: string | null, bashConfig?: BashConfig, network?: NetworkConfig);
+    getOrCreate(tenantId: string): Bash;
+    getAdapter(tenantId: string): PonchoFsAdapter;
+    /** Refresh the PostgreSQL path cache before a bash.exec() call. */
+    refreshPathCache(tenantId: string): Promise<void>;
+    destroy(tenantId: string): void;
+    destroyAll(): void;
+}
+
+declare const createBashTool: (bashManager: BashEnvironmentManager) => ToolDefinition;
+
+interface TenantTokenPayload {
+    tenantId: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Verify a tenant JWT (HS256) signed with the given key.
+ * Returns the decoded payload on success, or undefined on any failure.
+ */
+declare function verifyTenantToken(signingKey: string, token: string): Promise<TenantTokenPayload | undefined>;
+
 declare const createSubagentTools: (manager: SubagentManager) => ToolDefinition[];
 
-export { type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, type ArchivedToolResult$1 as ArchivedToolResult, type BuiltInToolToggles, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type Conversation, type ConversationState, type ConversationStore, type ConversationSummary, type CronJobConfig, type HarnessOptions, type HarnessRunOutput, InMemoryConversationStore, InMemoryStateStore, LocalMcpBridge, LocalUploadStore, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentResult, type PonchoConfig, type ProviderConfig, type Reminder, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RuntimeRenderContext, S3UploadStore, STORAGE_SCHEMA_VERSION, type SkillContextEntry, type SkillMetadata, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type SubagentManager, type SubagentResult, type SubagentSpawnResult, type SubagentSummary, type TelemetryConfig, TelemetryEmitter, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type UploadStore, type UploadsConfig, VercelBlobUploadStore, buildAgentDirectoryName, buildSkillContextWindow, compactMessages, completeOpenAICodexDeviceAuth, createConversationStore, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryTools, createModelProvider, createReminderStore, createReminderTools, createSearchTools, createSkillTools, createStateStore, createSubagentTools, createUploadStore, createWriteTool, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, findSafeSplitPoint, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, jsonSchemaToZod, loadPonchoConfig, loadSkillContext, loadSkillInstructions, loadSkillMetadata, normalizeOtlp, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, ponchoDocsTool, readOpenAICodexSession, readSkillResource, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveMemoryConfig, resolveSkillDirs, resolveStateConfig, slugifyStorageComponent, startOpenAICodexDeviceAuth, writeOpenAICodexSession };
+export { type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type Conversation, type ConversationState, type ConversationStore, type ConversationSummary, type CronJobConfig, type HarnessOptions, type HarnessRunOutput, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type NetworkConfig, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentResult, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Reminder, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RuntimeRenderContext, S3UploadStore, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type SubagentManager, type SubagentResult, type SubagentSpawnResult, type SubagentSummary, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, buildAgentDirectoryName, buildSkillContextWindow, compactMessages, completeOpenAICodexDeviceAuth, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createUploadStore, createWriteTool, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, findSafeSplitPoint, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, jsonSchemaToZod, loadPonchoConfig, loadSkillContext, loadSkillInstructions, loadSkillMetadata, normalizeOtlp, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, ponchoDocsTool, readOpenAICodexSession, readSkillResource, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveSkillDirs, resolveStateConfig, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, writeOpenAICodexSession };