@trydreamstate/cli 1.0.0

package/dist/skillInstaller.d.ts

@@ -0,0 +1,50 @@
+export declare const SKILL_INSTALL_AGENTS: readonly ["codex", "claude-code", "cursor"];
+export type SkillInstallAgent = typeof SKILL_INSTALL_AGENTS[number];
+export interface HostedSkill {
+    id: string;
+    name: string;
+    description: string;
+    body: string;
+    frontmatter?: Record<string, string | string[]>;
+    documents?: Array<{
+        name: string;
+        content: string;
+    }>;
+}
+export interface SkillInstallOptions {
+    agents: readonly SkillInstallAgent[];
+    homeDirectory?: string;
+    project?: boolean;
+    copy?: boolean;
+    cwd?: string;
+    workspaceId?: string;
+    indexVersion?: string;
+}
+export declare function canonicalSkillsDirectory(homeDirectory?: string, project?: boolean, cwd?: string): string;
+export declare function skillInstallDirectory(agent: SkillInstallAgent, homeDirectory?: string, project?: boolean, cwd?: string): string;
+export declare function renderSkillMarkdown(skill: HostedSkill, provenance: {
+    workspaceId: string;
+    indexVersion: string;
+}): string;
+export declare function installSkills(skills: readonly HostedSkill[], options: SkillInstallOptions): Promise<{
+    files: string[];
+    lockSkills: Record<string, {
+        source: string;
+        sourceType: 'hosted';
+        computedHash: string;
+    }>;
+}>;
+export declare function routerSkill(packsList: unknown): HostedSkill;
+export declare function inspectSkillInstallers(agents: readonly SkillInstallAgent[], homeDirectory?: string, project?: boolean, cwd?: string): Promise<Array<{
+    agent: SkillInstallAgent;
+    directory: string;
+    writable: boolean;
+    canonical_directory: string;
+    symlinks: Array<{
+        name: string;
+        target: string;
+        correct: boolean;
+    }>;
+    provenance_age_ms: number | null;
+}>>;
+//# sourceMappingURL=skillInstaller.d.ts.map

package/dist/skillInstaller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillInstaller.d.ts","sourceRoot":"","sources":["../src/skillInstaller.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,oBAAoB,6CAA8C,CAAC;AAChF,MAAM,MAAM,iBAAiB,GAAG,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAEpE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAChD,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAKD,wBAAgB,wBAAwB,CAAC,aAAa,SAAY,EAAE,OAAO,UAAQ,EAAE,GAAG,SAAgB,GAAG,MAAM,CAEhH;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,iBAAiB,EAAE,aAAa,SAAY,EAAE,OAAO,UAAQ,EAAE,GAAG,SAAgB,GAAG,MAAM,CAKvI;AAiBD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAazH;AA8BD,wBAAsB,aAAa,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,QAAQ,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAe1N;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW,CAO3D;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,EAAE,aAAa,SAAY,EAAE,OAAO,UAAQ,EAAE,GAAG,SAAgB,GAAG,OAAO,CAAC,KAAK,CAAC;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAAC,CAkC1W"}

package/dist/skillInstaller.js

@@ -0,0 +1,189 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_INSTALL_AGENTS = void 0;
+exports.canonicalSkillsDirectory = canonicalSkillsDirectory;
+exports.skillInstallDirectory = skillInstallDirectory;
+exports.renderSkillMarkdown = renderSkillMarkdown;
+exports.installSkills = installSkills;
+exports.routerSkill = routerSkill;
+exports.inspectSkillInstallers = inspectSkillInstallers;
+const promises_1 = require("node:fs/promises");
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const index_1 = require("./index");
+exports.SKILL_INSTALL_AGENTS = ['codex', 'claude-code', 'cursor'];
+const allowedTools = 'Bash(dreamstate *), Bash(jq *)';
+const safeId = /^[a-z0-9][a-z0-9_-]*$/i;
+function canonicalSkillsDirectory(homeDirectory = (0, node_os_1.homedir)(), project = false, cwd = process.cwd()) {
+    return project ? (0, node_path_1.join)(cwd, '.agents', 'skills') : (0, node_path_1.join)(homeDirectory, '.agents', 'skills');
+}
+function skillInstallDirectory(agent, homeDirectory = (0, node_os_1.homedir)(), project = false, cwd = process.cwd()) {
+    // Codex and Cursor both read the shared .agents/skills directory; only Claude
+    // Code needs its own directory, which links back into the shared one.
+    if (agent !== 'claude-code')
+        return canonicalSkillsDirectory(homeDirectory, project, cwd);
+    return (0, node_path_1.join)(project ? cwd : homeDirectory, '.claude', 'skills');
+}
+function yamlValue(value) { return JSON.stringify(value); }
+function skillName(id) {
+    if (!safeId.test(id))
+        throw new index_1.CliUsageError('Dreamstate API returned an invalid skill id.');
+    return id === 'router' ? 'dreamstate' : `dreamstate-${id}`;
+}
+function commandGuide(packs) {
+    return `## How to run this in Dreamstate\n\nUse \`dreamstate whoami --json\` (MCP \`whoami\`) to verify workspace. Route ambiguous work with \`dreamstate packs route --goal "<goal>" --json\` (MCP \`packs_route\`). Discover actions with \`dreamstate tools search --goal "<goal>" --json\` (MCP \`tools_search\`), inspect exact input with \`dreamstate tools get <capability_id> --json\` (MCP \`tools_get\`), then execute with \`dreamstate tools run <capability_id> --params '{...}' --mode <dry_run|live> --json\` (MCP \`tools_run\`). Check asynchronous work with \`dreamstate runs get <run_id> --json\` (MCP \`runs_get\`).\n\nGoals: ${packs.length ? packs.join(', ') : 'not declared'}.`;
+}
+function packs(frontmatter) {
+    const value = frontmatter.packs;
+    return Array.isArray(value) ? value : typeof value === 'string' ? value.split(',').map((item) => item.trim()).filter(Boolean) : [];
+}
+function renderSkillMarkdown(skill, provenance) {
+    const name = skillName(skill.id);
+    const source = skill.frontmatter ?? {};
+    const frontmatter = {
+        ...source,
+        name,
+        description: skill.description,
+        'allowed-tools': allowedTools,
+    };
+    const lines = Object.entries(frontmatter).flatMap(([key, value]) => Array.isArray(value)
+        ? [`${key}: [${value.map(yamlValue).join(', ')}]`]
+        : [`${key}: ${yamlValue(value)}`]);
+    return `---\n${lines.join('\n')}\n---\n\n${commandGuide(packs(frontmatter))}\n\n${skill.body.trim()}\n\n<!-- dreamstate provenance: workspace=${provenance.workspaceId} issued=${new Date().toISOString()} skills=${provenance.indexVersion} -->\n`;
+}
+function hash(value) { return (0, node_crypto_1.createHash)('sha256').update(value).digest('hex'); }
+async function writeHostedSkill(root, skill, provenance) {
+    const name = skillName(skill.id);
+    const directory = (0, node_path_1.join)(root, name);
+    const markdown = renderSkillMarkdown(skill, provenance);
+    await (0, promises_1.mkdir)(directory, { recursive: true, mode: 0o700 });
+    const file = (0, node_path_1.join)(directory, 'SKILL.md');
+    await (0, promises_1.writeFile)(file, markdown, { encoding: 'utf8', mode: 0o600 });
+    for (const document of skill.documents ?? []) {
+        if (!safeId.test(document.name.replace(/\.[a-z0-9]+$/i, '')))
+            continue;
+        await (0, promises_1.writeFile)((0, node_path_1.join)(directory, document.name), document.content, { encoding: 'utf8', mode: 0o600 });
+    }
+    return { file, name, computedHash: hash(markdown) };
+}
+async function linkAgentSkill(agentRoot, canonicalDirectory, name, copy) {
+    const targetDirectory = (0, node_path_1.join)(agentRoot, name);
+    await (0, promises_1.mkdir)(agentRoot, { recursive: true, mode: 0o700 });
+    await (0, promises_1.rm)(targetDirectory, { recursive: true, force: true });
+    if (copy) {
+        await (0, promises_1.mkdir)(targetDirectory, { recursive: true, mode: 0o700 });
+        await (0, promises_1.writeFile)((0, node_path_1.join)(targetDirectory, 'SKILL.md'), await (0, promises_1.readFile)((0, node_path_1.join)(canonicalDirectory, name, 'SKILL.md')), { encoding: 'utf8', mode: 0o600 });
+    }
+    else {
+        await (0, promises_1.symlink)((0, node_path_1.relative)(agentRoot, (0, node_path_1.join)(canonicalDirectory, name)), targetDirectory, 'dir');
+    }
+    return (0, node_path_1.join)(targetDirectory, 'SKILL.md');
+}
+async function installSkills(skills, options) {
+    const home = options.homeDirectory ?? (0, node_os_1.homedir)();
+    const cwd = options.cwd ?? process.cwd();
+    const canonical = canonicalSkillsDirectory(home, Boolean(options.project), cwd);
+    await (0, promises_1.mkdir)(canonical, { recursive: true, mode: 0o700 });
+    const provenance = { workspaceId: options.workspaceId ?? 'unknown', indexVersion: options.indexVersion ?? 'unknown' };
+    const entries = await Promise.all(skills.map((skill) => writeHostedSkill(canonical, skill, provenance)));
+    const files = entries.map((entry) => entry.file);
+    for (const agent of options.agents.filter((agent) => agent === 'claude-code')) {
+        const root = skillInstallDirectory(agent, home, Boolean(options.project), cwd);
+        for (const entry of entries)
+            files.push(await linkAgentSkill(root, canonical, entry.name, Boolean(options.copy)));
+    }
+    const lockSkills = Object.fromEntries(entries.map((entry, index) => [entry.name, { source: skills[index].id, sourceType: 'hosted', computedHash: entry.computedHash }]));
+    if (options.project)
+        await (0, promises_1.writeFile)((0, node_path_1.join)(cwd, 'skills-lock.json'), `${JSON.stringify({ version: 1, skills: lockSkills }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    return { files, lockSkills };
+}
+function routerSkill(packsList) {
+    const root = packsList && typeof packsList === 'object' ? packsList : {};
+    const records = Array.isArray(root.data?.packs) ? root.data.packs : [];
+    const goals = records.map((item) => item && typeof item === 'object' ? item : {})
+        .filter((item) => typeof item.id === 'string');
+    const lines = goals.map((pack) => `- ${pack.id}: ${pack.owns ?? 'Dreamstate capability pack.'}${pack.not_for ? ` ${pack.not_for}` : ''}`).join('\n');
+    return { id: 'router', name: 'Dreamstate', description: 'Route work to Dreamstate capability skills.', body: `# Dreamstate router\n\nPrefer narrower \`dreamstate-*\` skill when one fits. Otherwise route with \`dreamstate packs route --goal "<goal>" --json\` (MCP \`packs_route\`), search tools scoped by the returned pack with \`dreamstate tools search --goal "<goal>" --toolset <pack_id> --json\` (MCP \`tools_search\`), fetch exact schema with \`dreamstate tools get <capability_id> --json\` (MCP \`tools_get\`), then run it with \`dreamstate tools run <capability_id> --params '{...}' --json\` (MCP \`tools_run\`).\n\n## Goals\n\n${lines || 'No packs returned by GET /packs.'}`, frontmatter: { packs: goals.map((pack) => pack.id) } };
+}
+async function inspectSkillInstallers(agents, homeDirectory = (0, node_os_1.homedir)(), project = false, cwd = process.cwd()) {
+    const canonical = canonicalSkillsDirectory(homeDirectory, project, cwd);
+    let canonicalExists = false;
+    try {
+        canonicalExists = (await (0, promises_1.stat)(canonical)).isDirectory();
+    }
+    catch { /* absent */ }
+    return Promise.all(agents.map(async (agent) => {
+        const directory = skillInstallDirectory(agent, homeDirectory, project, cwd);
+        let writable = false;
+        try {
+            writable = (await (0, promises_1.stat)(directory)).isDirectory();
+        }
+        catch {
+            try {
+                await (0, promises_1.access)((0, node_path_1.dirname)(directory), node_fs_1.constants.W_OK);
+                writable = true;
+            }
+            catch { /* unavailable */ }
+        }
+        const symlinks = [];
+        if (agent === 'claude-code') {
+            try {
+                for (const name of await (await Promise.resolve().then(() => __importStar(require('node:fs/promises')))).readdir(directory)) {
+                    const path = (0, node_path_1.join)(directory, name);
+                    const state = await (0, promises_1.lstat)(path);
+                    if (state.isSymbolicLink()) {
+                        const target = await (await Promise.resolve().then(() => __importStar(require('node:fs/promises')))).readlink(path);
+                        symlinks.push({ name, target, correct: (0, node_path_1.join)(directory, target) === (0, node_path_1.join)(canonical, name) });
+                    }
+                }
+            }
+            catch { /* absent */ }
+        }
+        let provenance_age_ms = null;
+        if (canonicalExists) {
+            try {
+                const router = await (0, promises_1.readFile)((0, node_path_1.join)(canonical, 'dreamstate', 'SKILL.md'), 'utf8');
+                const issued = router.match(/<!-- dreamstate provenance: workspace=[^\s]+ issued=([^\s]+) skills=[^>]+ -->/);
+                const timestamp = issued?.[1] ? Date.parse(issued[1]) : Number.NaN;
+                provenance_age_ms = Number.isFinite(timestamp) ? Date.now() - timestamp : null;
+            }
+            catch { /* absent */ }
+        }
+        return { agent, directory, writable, canonical_directory: canonical, symlinks, provenance_age_ms };
+    }));
+}

package/dist/tableFilePreview.d.ts

@@ -0,0 +1,12 @@
+export type LocalTableFileKind = 'csv' | 'json' | 'jsonl' | 'xlsx';
+export interface LocalTableFilePreview {
+    file_kind: LocalTableFileKind;
+    headers: string[];
+    sample_rows: Array<Record<string, string>>;
+    suggested_mapping: Record<string, string>;
+    truncated: boolean;
+    writes: false;
+}
+export declare function inferLocalTableFileKind(filePath: string, format?: string): LocalTableFileKind;
+export declare function previewLocalTableFile(filePath: string, format?: string): Promise<LocalTableFilePreview>;
+//# sourceMappingURL=tableFilePreview.d.ts.map

package/dist/tableFilePreview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tableFilePreview.d.ts","sourceRoot":"","sources":["../src/tableFilePreview.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAEnE,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3C,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC;CACf;AAgBD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAK7F;AAoOD,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAgB7G"}

package/dist/tableFilePreview.js

@@ -0,0 +1,303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferLocalTableFileKind = inferLocalTableFileKind;
+exports.previewLocalTableFile = previewLocalTableFile;
+const promises_1 = require("node:fs/promises");
+const node_zlib_1 = require("node:zlib");
+const SAMPLE_ROWS = 5;
+const TEXT_PREVIEW_BYTES = 1_000_000;
+const XLSX_PREVIEW_BYTES = 20_000_000;
+const MAPPABLE_FIELDS = [
+    'external_id', 'name', 'first_name', 'last_name', 'company',
+    'title', 'headline', 'email', 'linkedin_url', 'profile_url', 'avatar_url',
+];
+function normalizeHeaderKey(value) {
+    return value.trim().toLowerCase().replace(/[\s_-]+/g, '');
+}
+function suggestedMapping(headers) {
+    const byNormalized = new Map(MAPPABLE_FIELDS.map((field) => [normalizeHeaderKey(field), field]));
+    const mapping = {};
+    for (const header of headers) {
+        const match = byNormalized.get(normalizeHeaderKey(header));
+        if (match)
+            mapping[header] = match;
+    }
+    return mapping;
+}
+function inferLocalTableFileKind(filePath, format) {
+    if (format === 'csv' || format === 'json' || format === 'jsonl' || format === 'xlsx')
+        return format;
+    const extension = filePath.split('.').pop()?.toLowerCase();
+    if (extension === 'json' || extension === 'jsonl' || extension === 'xlsx')
+        return extension;
+    return 'csv';
+}
+function finish(kind, headers, dataRows, truncated) {
+    const usable = headers.map((header) => header.trim());
+    if (usable.length === 0 || usable.every((header) => header.length === 0)) {
+        throw new Error('File has no header row');
+    }
+    const sample = dataRows.slice(0, SAMPLE_ROWS).map((row) => {
+        const record = {};
+        usable.forEach((header, index) => {
+            if (header.length === 0)
+                return;
+            record[header] = row[index] ?? '';
+        });
+        return record;
+    });
+    return {
+        file_kind: kind,
+        headers: usable.filter((header) => header.length > 0),
+        sample_rows: sample,
+        suggested_mapping: suggestedMapping(usable),
+        truncated: truncated || dataRows.length > SAMPLE_ROWS,
+        writes: false,
+    };
+}
+function parseCsv(text) {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let quoted = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (quoted) {
+            if (char === '"') {
+                if (text[index + 1] === '"') {
+                    field += '"';
+                    index += 1;
+                }
+                else
+                    quoted = false;
+            }
+            else
+                field += char;
+            continue;
+        }
+        if (char === '"') {
+            quoted = true;
+            continue;
+        }
+        if (char === ',') {
+            row.push(field);
+            field = '';
+            continue;
+        }
+        if (char === '\n') {
+            row.push(field);
+            field = '';
+            if (!(row.length === 1 && row[0] === ''))
+                rows.push(row);
+            row = [];
+            continue;
+        }
+        if (char !== '\r')
+            field += char;
+    }
+    const endedClean = !quoted && field.length === 0 && row.length === 0;
+    if (field.length > 0 || row.length > 0) {
+        row.push(field);
+        if (!(row.length === 1 && row[0] === ''))
+            rows.push(row);
+    }
+    return { rows, endedClean };
+}
+function previewDelimited(kind, text, clipped) {
+    const parsed = parseCsv(text);
+    const rows = parsed.rows;
+    if (clipped && !parsed.endedClean)
+        rows.pop();
+    if (rows.length === 0)
+        throw new Error('File has no header row');
+    const [headers, ...dataRows] = rows;
+    return finish(kind, headers ?? [], dataRows, clipped);
+}
+function cellString(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return '';
+}
+function previewObjects(kind, records) {
+    const objects = records.filter((record) => record && typeof record === 'object' && !Array.isArray(record));
+    if (objects.length === 0)
+        throw new Error('JSON import expects an object or an array of objects');
+    const headers = [];
+    for (const record of objects.slice(0, SAMPLE_ROWS + 1)) {
+        for (const key of Object.keys(record)) {
+            if (!headers.includes(key))
+                headers.push(key);
+        }
+    }
+    const dataRows = objects.map((record) => headers.map((header) => cellString(record[header])));
+    return finish(kind, headers, dataRows, objects.length > SAMPLE_ROWS);
+}
+function previewJson(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`JSON preview could not parse the file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (Array.isArray(parsed))
+        return previewObjects('json', parsed);
+    if (parsed && typeof parsed === 'object')
+        return previewObjects('json', [parsed]);
+    throw new Error('JSON import expects an object or an array of objects');
+}
+function previewJsonl(text, clipped) {
+    const lines = text.split(/\r?\n/);
+    if (clipped)
+        lines.pop();
+    const records = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            records.push(JSON.parse(trimmed));
+        }
+        catch (error) {
+            throw new Error(`JSONL preview could not parse a line: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (records.length > SAMPLE_ROWS)
+            break;
+    }
+    return previewObjects('jsonl', records);
+}
+function decodeXml(value) {
+    return value
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+function unzipEntries(buffer) {
+    const eocdMin = Math.max(0, buffer.length - 22 - 65535);
+    let eocd = -1;
+    for (let index = buffer.length - 22; index >= eocdMin; index -= 1) {
+        if (buffer.readUInt32LE(index) === 0x06054b50) {
+            eocd = index;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new Error('xlsx file has no zip directory');
+    const out = new Map();
+    let offset = buffer.readUInt32LE(eocd + 16);
+    const entryCount = buffer.readUInt16LE(eocd + 10);
+    for (let index = 0; index < entryCount && offset + 46 <= buffer.length; index += 1) {
+        if (buffer.readUInt32LE(offset) !== 0x02014b50)
+            break;
+        const method = buffer.readUInt16LE(offset + 10);
+        const compressedSize = buffer.readUInt32LE(offset + 20);
+        const nameLength = buffer.readUInt16LE(offset + 28);
+        const extraLength = buffer.readUInt16LE(offset + 30);
+        const commentLength = buffer.readUInt16LE(offset + 32);
+        const localOffset = buffer.readUInt32LE(offset + 42);
+        const name = buffer.toString('utf8', offset + 46, offset + 46 + nameLength);
+        offset += 46 + nameLength + extraLength + commentLength;
+        if (!/xl\/(sharedStrings\.xml|worksheets\/sheet\d+\.xml)$/.test(name))
+            continue;
+        if (localOffset + 30 > buffer.length)
+            throw new Error('xlsx local header is outside the file');
+        const localNameLength = buffer.readUInt16LE(localOffset + 26);
+        const localExtraLength = buffer.readUInt16LE(localOffset + 28);
+        const dataStart = localOffset + 30 + localNameLength + localExtraLength;
+        const compressed = buffer.subarray(dataStart, dataStart + compressedSize);
+        if (method === 0)
+            out.set(name, Buffer.from(compressed));
+        else if (method === 8)
+            out.set(name, (0, node_zlib_1.inflateRawSync)(compressed));
+        else
+            throw new Error(`Unsupported xlsx compression method ${method}`);
+    }
+    return out;
+}
+function columnIndex(ref) {
+    const letters = /^[A-Z]+/i.exec(ref)?.[0] ?? '';
+    let index = 0;
+    for (const char of letters.toUpperCase())
+        index = index * 26 + (char.charCodeAt(0) - 64);
+    return index - 1;
+}
+function xmlTexts(fragment) {
+    return [...fragment.matchAll(/<(?:[\w-]+:)?t\b[^>]*>([\s\S]*?)<\/(?:[\w-]+:)?t>/g)]
+        .map((match) => decodeXml(match[1] ?? ''))
+        .join('');
+}
+function sharedStringTable(xml) {
+    return [...xml.matchAll(/<(?:[\w-]+:)?si\b[^>]*>([\s\S]*?)<\/(?:[\w-]+:)?si>/g)]
+        .map((match) => xmlTexts(match[1] ?? ''));
+}
+function previewXlsx(buffer) {
+    const entries = unzipEntries(buffer);
+    const sheetName = [...entries.keys()]
+        .filter((name) => /xl\/worksheets\/sheet\d+\.xml$/.test(name))
+        .sort()[0];
+    if (!sheetName)
+        throw new Error('xlsx preview could not find a worksheet');
+    const sheet = entries.get(sheetName).toString('utf8');
+    const sharedName = [...entries.keys()].find((name) => name.endsWith('xl/sharedStrings.xml'));
+    const shared = sharedName ? sharedStringTable(entries.get(sharedName).toString('utf8')) : [];
+    const grid = new Map();
+    for (const rowMatch of sheet.matchAll(/<(?:[\w-]+:)?row\b([^>]*)>([\s\S]*?)<\/(?:[\w-]+:)?row>/g)) {
+        const rowRef = /\br="(\d+)"/.exec(rowMatch[1] ?? '');
+        const rowNumber = rowRef ? Number(rowRef[1]) : grid.size + 1;
+        if (rowNumber > SAMPLE_ROWS + 1)
+            continue;
+        const cells = new Map();
+        for (const cellMatch of (rowMatch[2] ?? '').matchAll(/<(?:[\w-]+:)?c\b([^>]*)(?:\/>|>([\s\S]*?)<\/(?:[\w-]+:)?c>)/g)) {
+            const attrs = cellMatch[1] ?? '';
+            const ref = /\br="([A-Z]+\d+)"/i.exec(attrs);
+            const type = /\bt="([^"]+)"/.exec(attrs)?.[1] ?? '';
+            const body = cellMatch[2] ?? '';
+            const column = columnIndex(ref?.[1] ?? '');
+            if (column < 0)
+                continue;
+            let value = '';
+            if (type === 's') {
+                const index = Number(/<(?:[\w-]+:)?v\b[^>]*>([\s\S]*?)<\/(?:[\w-]+:)?v>/.exec(body)?.[1] ?? '');
+                value = shared[index] ?? '';
+            }
+            else if (type === 'inlineStr')
+                value = xmlTexts(body);
+            else
+                value = decodeXml(/<(?:[\w-]+:)?v\b[^>]*>([\s\S]*?)<\/(?:[\w-]+:)?v>/.exec(body)?.[1] ?? '');
+            cells.set(column, value);
+        }
+        grid.set(rowNumber, cells);
+    }
+    const rowNumbers = [...grid.keys()].sort((left, right) => left - right);
+    if (rowNumbers.length === 0)
+        throw new Error('File has no header row');
+    const width = Math.max(...[...grid.values()].map((cells) => Math.max(-1, ...cells.keys()))) + 1;
+    const toRow = (cells) => Array.from({ length: width }, (_, index) => cells?.get(index) ?? '');
+    const [headerNumber, ...dataNumbers] = rowNumbers;
+    const rowCount = [...sheet.matchAll(/<(?:[\w-]+:)?row\b/g)].length;
+    return finish('xlsx', toRow(grid.get(headerNumber)), dataNumbers.map((number) => toRow(grid.get(number))), rowCount > SAMPLE_ROWS + 1);
+}
+async function previewLocalTableFile(filePath, format) {
+    const kind = inferLocalTableFileKind(filePath, format);
+    if (kind === 'xlsx') {
+        const file = await (0, promises_1.readFile)(filePath);
+        if (file.length > XLSX_PREVIEW_BYTES)
+            throw new Error('xlsx preview refused a file larger than 20MB');
+        return previewXlsx(file);
+    }
+    const handle = await (0, promises_1.readFile)(filePath);
+    const clipped = handle.length > TEXT_PREVIEW_BYTES;
+    const text = handle.subarray(0, TEXT_PREVIEW_BYTES).toString('utf8');
+    if (kind === 'json') {
+        if (clipped)
+            throw new Error('JSON preview refused a file larger than 1MB');
+        return previewJson(text);
+    }
+    if (kind === 'jsonl')
+        return previewJsonl(text, clipped);
+    return previewDelimited(kind, text, clipped);
+}

package/dist/turnCache.d.ts

@@ -0,0 +1,8 @@
+export declare const TURN_REUSE_MS: number;
+type CacheWarning = (error: NodeJS.ErrnoException) => void;
+export declare function turnCachePath(credentialsPath: string): string;
+export declare function reusableTurnToken(path: string, baseUrl: string, apiKey: string, capabilityId: string, now?: number, onWarning?: CacheWarning): Promise<string | null>;
+export declare function rememberTurnToken(path: string, baseUrl: string, apiKey: string, capabilityId: string, token: string, now?: number, onWarning?: CacheWarning): Promise<void>;
+export declare function forgetTurnToken(path: string, baseUrl: string, apiKey: string, capabilityId: string, onWarning?: CacheWarning): Promise<void>;
+export {};
+//# sourceMappingURL=turnCache.d.ts.map

package/dist/turnCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnCache.d.ts","sourceRoot":"","sources":["../src/turnCache.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,aAAa,QAAa,CAAC;AAGxC,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,KAAK,IAAI,CAAC;AAE3D,wBAAgB,aAAa,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAE7D;AA2BD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,SAAa,EAAE,SAAS,CAAC,EAAE,YAAY,GAC9G,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAa,EAAE,SAAS,CAAC,EAAE,YAAY,GAC7H,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,YAAY,GAC5F,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/turnCache.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TURN_REUSE_MS = void 0;
+exports.turnCachePath = turnCachePath;
+exports.reusableTurnToken = reusableTurnToken;
+exports.rememberTurnToken = rememberTurnToken;
+exports.forgetTurnToken = forgetTurnToken;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+// A paid capability's first live call is refused with quote_required and the
+// server binds a quote to that call's tool_turn_token. Only a rerun carrying
+// the SAME token can spend. Each CLI invocation is a new process, so fetching
+// a fresh token per run made every paid capability unrunnable from the CLI
+// (2026-09-23: tables.table_sources.run refused four times in a row), while
+// the refusal itself told the user the CLI reuses the turn for 10 minutes.
+// The server turn lives 10 minutes; reuse for 9 so a cached token never
+// expires mid-request.
+exports.TURN_REUSE_MS = 9 * 60_000;
+function turnCachePath(credentialsPath) {
+    return (0, node_path_1.join)((0, node_path_1.dirname)(credentialsPath), 'turns.json');
+}
+function entryKey(baseUrl, apiKey, capabilityId) {
+    // The key fingerprint keeps two workspaces on one machine from sharing a turn.
+    const fingerprint = (0, node_crypto_1.createHash)('sha256').update(apiKey).digest('hex').slice(0, 16);
+    return `${baseUrl} ${fingerprint} ${capabilityId}`;
+}
+async function load(path, onWarning) {
+    try {
+        const parsed = JSON.parse(await (0, promises_1.readFile)(path, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            onWarning?.(error);
+        return {};
+    }
+}
+async function persist(path, entries, onWarning) {
+    try {
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+        await (0, promises_1.writeFile)(path, JSON.stringify(entries), { mode: 0o600 });
+    }
+    catch (error) {
+        onWarning?.(error);
+    }
+}
+async function reusableTurnToken(path, baseUrl, apiKey, capabilityId, now = Date.now(), onWarning) {
+    const entry = (await load(path, onWarning))[entryKey(baseUrl, apiKey, capabilityId)];
+    return entry && typeof entry.token === 'string' && now - entry.at < exports.TURN_REUSE_MS ? entry.token : null;
+}
+async function rememberTurnToken(path, baseUrl, apiKey, capabilityId, token, now = Date.now(), onWarning) {
+    const entries = await load(path, onWarning);
+    for (const [key, entry] of Object.entries(entries)) {
+        if (!entry || now - entry.at >= exports.TURN_REUSE_MS)
+            delete entries[key];
+    }
+    entries[entryKey(baseUrl, apiKey, capabilityId)] = { token, at: now };
+    await persist(path, entries, onWarning);
+}
+async function forgetTurnToken(path, baseUrl, apiKey, capabilityId, onWarning) {
+    const entries = await load(path, onWarning);
+    const key = entryKey(baseUrl, apiKey, capabilityId);
+    if (!(key in entries))
+        return;
+    delete entries[key];
+    await persist(path, entries, onWarning);
+}