tautau-mcp 0.3.0 → 0.4.0

package/README.md

@@ -5,6 +5,8 @@ An MCP (Model Context Protocol) stdio server that gives LLM clients — Claude C
 - **YouTube links** → transcript (captions-first, returns in seconds)
 - **Podcast / direct-audio URLs** → transcript (server-side speech-to-text, long jobs poll automatically)
 - **Local audio files** (mp3/wav/m4a/ogg/webm/mp4, up to 25MB) → transcript
+- **Recording evidence** → bounded session transcripts, diagnostics, and collected assets
+- **Asset library** → authenticated asset metadata and safe inline text previews
 
 No API key, no account: usage is anonymous and quota-tracked per IP by the tautau service (5 lifetime URL transcripts, 5 lifetime dictations). When you hit the wall the tools say so and point at [signup](https://tautau.xyz/login) / [pricing](https://tautau.xyz/pricing) — a free account gets a daily allowance.
 
@@ -57,6 +59,7 @@ Restart the client after editing config. Verify with `get_quota` (see below).
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `TAUTAU_API_BASE` | `https://tautau.xyz` | API base URL — only override for self-hosted/dev deployments |
+| `TAUTAU_AUTH_FILE` | `~/.config/tautau/auth.json` | Override the local Firebase session file location |
 
 ## Tools
 
@@ -111,14 +114,52 @@ Returns the scan meta (page, status, bundle size, timings), the **service-side R
 
 Example: *"Fetch tautau scan 9f2c… and tell me why the voice command didn't click the button"*
 
+### `get_recording`
+
+Read a public recording capability and its session evidence. The required `recordingId` is a 32-character lowercase hex id. The response includes the recording link, transcript, collection references, and bounded console, network, interaction, and pin evidence. Signed bundle URLs are fetched for the request and are never returned or saved.
+
+### `list_assets`
+
+List the authenticated asset library, newest first.
+
+| Argument | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `limit` | number | no | Integer from 1 to 200; defaults to 50 |
+
+### `get_asset`
+
+Read one authenticated asset using its 32-character lowercase hex `assetId`. Ready assets include a current media URL. Text-like files (`text/plain`, `text/csv`, `application/json`, `application/xml`, and `image/svg+xml`) are included inline only when they are no larger than 32KiB. Binary data is never embedded in an MCP response.
+
 ### `auth_login` / `auth_status` / `auth_logout`
 
-`auth_login` opens your browser for Google/email sign-in (same Firebase auth as the web app). The page hands the tokens to a **loopback callback** the MCP server is listening on — tokens never leave your machine. The session is stored at `~/.config/tautau/auth.json` (mode 0600) and auto-refreshes. `auth_status` shows who you're signed in as; `auth_logout` deletes the session.
+`auth_login` opens your browser for Google/email sign-in (same Firebase auth as the web app). The page hands the tokens to a **loopback callback** the MCP server is listening on — tokens never leave your machine. The session is stored at `TAUTAU_AUTH_FILE` or, by default, `~/.config/tautau/auth.json` (mode 0600) and auto-refreshes. `auth_status` shows who you're signed in as; `auth_logout` deletes the session. `list_assets` and `get_asset` require this session.
 
 ### `list_scans`
 
 Requires `auth_login`. Lists your page scans, newest first (id, status, time, size, page). Pair with `get_scan` to debug: *"List my tautau scans and pull the latest one — why did the page command fail?"*
 
+### `suggest_page_action`
+
+Interpret a natural-language page command (*"click sign in"*, *"type hello into search"*) against a page snapshot and return ONE server-validated action (`click`/`input`/`select`/`scroll`/`none`, index bounds-checked — out-of-range coerces to `none` with a reason, never an error).
+
+| Argument | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `command` | string | yes | 1–500 chars |
+| `scanId` | string | no | Build the snapshot from this scan's bundle (preferred — same source triage uses) |
+| `snapshot` | string | no | Page text with `[n]` prefixes, ≤32KiB (when no scanId) |
+| `url` / `title` | string | no | Page overrides |
+
+Requires `auth_login` (page actions are uid-gated). Execute the returned action in your own browser, then re-scan and verify with `diff_scans` — the full loop is worked in `docs/agent-loop.md` in the repo.
+
+### `diff_scans`
+
+Diff two scan captures for QA: changed pages, added/removed headings and assets, new vs resolved console errors and failed requests. Anonymous (public capabilities).
+
+| Argument | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `scanIdA` | string | yes | Before scan (32-char hex) |
+| `scanIdB` | string | yes | After scan (32-char hex) |
+
 ## Quotas & anonymity
 
 - The server sends no credentials; tautau tracks anonymous usage by client IP.
@@ -133,12 +174,13 @@ Requires `auth_login`. Lists your page scans, newest first (id, status, time, si
 ```bash
 cd mcp
 npm install
-npm run smoke   # boots the server over stdio, lists tools, calls get_quota (read-only)
+npm run build
+npm run smoke   # boots the server over stdio and runs read-only probes
 ```
 
 From the repo root: `task mcp:smoke`.
 
-Plain ESM JavaScript, zero build step, one runtime dependency (`@modelcontextprotocol/sdk`). The smoke test never burns transcribe quota — only `get_quota` and tool-listing run.
+The typed recording and asset modules compile to `dist/` with strict NodeNext TypeScript. `npm start` builds before launching, and `npm publish` builds through `prepublishOnly`. The smoke test never burns transcribe quota. It only lists tools and calls `get_quota` plus safe not-found/auth checks.
 
 ## Marketplace listings
 

package/dist/agent-tools.d.ts

@@ -0,0 +1,57 @@
+import { ToolContext, ToolResult } from './tool-types.js';
+export declare function runSuggestPageAction(context: ToolContext, args: Record<string, unknown>): Promise<ToolResult>;
+export declare function runDiffScans(context: ToolContext, args: Record<string, unknown>): Promise<ToolResult>;
+export declare const agentToolDefinitions: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            command: {
+                type: string;
+                description: string;
+            };
+            scanId: {
+                type: string;
+                description: string;
+            };
+            snapshot: {
+                type: string;
+                description: string;
+            };
+            url: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+            scanIdA?: undefined;
+            scanIdB?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            scanIdA: {
+                type: string;
+                description: string;
+            };
+            scanIdB: {
+                type: string;
+                description: string;
+            };
+            command?: undefined;
+            scanId?: undefined;
+            snapshot?: undefined;
+            url?: undefined;
+            title?: undefined;
+        };
+        required: string[];
+    };
+})[];

package/dist/agent-tools.js

@@ -0,0 +1,244 @@
+import { apiError, fail, isId, jsonResponse, newest, ok, redactText, redactUrl, MAX_EVIDENCE_ITEMS, MAX_METADATA_BYTES, } from './tool-types.js';
+// Agent action loop primitives: observe (get_scan) → suggest (this module)
+// → execute (the caller's own browser) → verify (diff_scans + re-scan).
+// suggest needs a signed-in session (PageAgentService is uid-gated);
+// diff works on public capabilities like get_scan.
+const MAX_SNAPSHOT_LINES = 100;
+const MAX_SNAPSHOT_BYTES = 8 * 1024;
+const MAX_LIST_ITEMS = 20;
+function asObj(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function asList(value) {
+    return Array.isArray(value) ? value.filter((v) => Boolean(v && typeof v === 'object')) : [];
+}
+async function scanBundle(context, id) {
+    let meta;
+    try {
+        meta = await context.fetch(`${context.apiBase}/api/scan/${encodeURIComponent(id)}`, { signal: AbortSignal.timeout(15_000) });
+    }
+    catch (error) {
+        return fail(`Could not reach ${context.apiBase}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!meta.ok)
+        return apiError(meta, context.apiBase);
+    const rawMeta = await jsonResponse(meta);
+    const sessionUrl = asObj(rawMeta).sessionUrl;
+    if (typeof sessionUrl !== 'string' || !sessionUrl)
+        return fail('Scan has no session bundle yet (still collecting?)');
+    try {
+        const res = await context.fetch(sessionUrl, { signal: AbortSignal.timeout(30_000) });
+        if (!res.ok)
+            return fail('Session bundle unreadable (link may have expired)');
+        const bundle = await jsonResponse(res);
+        if (!bundle || Array.isArray(bundle))
+            return fail('tautau returned an invalid session bundle');
+        return bundle;
+    }
+    catch (error) {
+        return fail(`Could not fetch session bundle: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Latest snapshot per URL pathname (same pairing rule as the /compare page). */
+function snapshotsByUrl(bundle) {
+    const out = new Map();
+    for (const snap of asList(bundle.snapshots)) {
+        const raw = typeof snap.url === 'string' ? snap.url : '';
+        let key = raw.split('?')[0];
+        try {
+            const u = new URL(raw);
+            key = `${u.origin}${u.pathname}`;
+        }
+        catch {
+            /* keep fallback */
+        }
+        out.set(key, snap);
+    }
+    return out;
+}
+/** [i]<tag> text lines over the latest interactive index (extension format). */
+function snapshotLines(bundle) {
+    const snaps = [...snapshotsByUrl(bundle).values()];
+    const snap = snaps[snaps.length - 1];
+    if (!snap)
+        return { lines: '', url: '', title: '' };
+    const interactive = asList(asObj(snap.outline).interactive).slice(0, MAX_SNAPSHOT_LINES);
+    const lines = interactive
+        .map((el) => {
+        const i = typeof el.i === 'number' ? el.i : '?';
+        const tag = typeof el.tag === 'string' ? el.tag : '?';
+        const text = typeof el.text === 'string' ? el.text.slice(0, 80) : '';
+        return `[${i}]<${tag}> ${text}`.trim();
+    })
+        .join('\n')
+        .slice(0, MAX_SNAPSHOT_BYTES);
+    return {
+        lines,
+        url: typeof snap.url === 'string' ? redactUrl(snap.url) : '',
+        title: typeof snap.title === 'string' ? redactText(snap.title, 200) : '',
+    };
+}
+export async function runSuggestPageAction(context, args) {
+    const command = typeof args.command === 'string' ? args.command.trim() : '';
+    if (!command || command.length > 500)
+        return fail('command must be 1..500 chars');
+    if (!context.authFetch)
+        return fail('Not signed in — run auth_login first (page actions need your account).');
+    let snapshot = typeof args.snapshot === 'string' ? args.snapshot : '';
+    let url = typeof args.url === 'string' ? args.url : '';
+    let title = typeof args.title === 'string' ? args.title : '';
+    const scanId = typeof args.scanId === 'string' ? args.scanId : '';
+    if (scanId) {
+        if (!isId(scanId))
+            return fail('scanId must be a 32-character lowercase hex id');
+        const bundle = await scanBundle(context, scanId);
+        if ('content' in bundle)
+            return bundle;
+        const built = snapshotLines(bundle);
+        if (!built.lines)
+            return fail('Scan bundle has no interactive snapshot to act on');
+        snapshot = built.lines;
+        url = url || built.url;
+        title = title || built.title;
+    }
+    if (!snapshot || snapshot.length > 32 * 1024)
+        return fail('snapshot is required (page text with [n] prefixes, ≤32KiB) — get it from get_scan or the page itself');
+    let res;
+    try {
+        res = await context.authFetch('/api/page-command', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ command, url, title, snapshot }),
+            signal: AbortSignal.timeout(60_000),
+        });
+    }
+    catch (error) {
+        return fail(`Could not reach ${context.apiBase}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!res)
+        return fail('Not signed in — run auth_login first.');
+    if (!res.ok)
+        return apiError(res, context.apiBase);
+    const body = await jsonResponse(res);
+    const action = asObj(body);
+    return ok({
+        action: typeof action.action === 'string' ? action.action : 'none',
+        index: typeof action.index === 'number' ? action.index : -1,
+        selector: typeof action.selector === 'string' ? action.selector : undefined,
+        text: typeof action.text === 'string' ? redactText(action.text, 500) : undefined,
+        direction: typeof action.direction === 'string' ? action.direction : undefined,
+        reason: typeof action.reason === 'string' ? redactText(action.reason, 500) : undefined,
+        provider: typeof action.provider === 'string' ? action.provider : undefined,
+    });
+}
+function textSet(events, pred) {
+    const out = new Set();
+    for (const e of events) {
+        const v = pred(e);
+        if (v)
+            out.add(v);
+    }
+    return out;
+}
+function diffSets(before, after) {
+    return {
+        added: [...after].filter((x) => !before.has(x)).slice(0, MAX_LIST_ITEMS),
+        removed: [...before].filter((x) => !after.has(x)).slice(0, MAX_LIST_ITEMS),
+    };
+}
+export async function runDiffScans(context, args) {
+    const a = typeof args.scanIdA === 'string' ? args.scanIdA : '';
+    const b = typeof args.scanIdB === 'string' ? args.scanIdB : '';
+    if (!isId(a) || !isId(b))
+        return fail('scanIdA and scanIdB must be 32-character lowercase hex ids');
+    if (a === b)
+        return fail('scanIdA and scanIdB are the same scan');
+    const [bundleA, bundleB] = await Promise.all([scanBundle(context, a), scanBundle(context, b)]);
+    if ('content' in bundleA)
+        return bundleA;
+    if ('content' in bundleB)
+        return bundleB;
+    const snapsA = snapshotsByUrl(bundleA);
+    const snapsB = snapshotsByUrl(bundleB);
+    const urls = [...new Set([...snapsA.keys(), ...snapsB.keys()])].sort();
+    const pages = [];
+    let assetsAdded = 0;
+    let assetsRemoved = 0;
+    for (const url of urls) {
+        const before = snapsA.get(url);
+        const after = snapsB.get(url);
+        if (!before || !after) {
+            pages.push({ url, onlyIn: !before ? 'after' : 'before' });
+            continue;
+        }
+        const head = (s) => asList(asObj(s.outline).headings).map((h) => `h${typeof h.level === 'number' ? h.level : '?'}: ${typeof h.text === 'string' ? h.text.slice(0, 80) : ''}`);
+        const headings = diffSets(new Set(head(before)), new Set(head(after)));
+        const assetNames = (s) => asList(s.assets).map((x) => (typeof x.name === 'string' ? x.name : '')).filter(Boolean);
+        const assets = diffSets(new Set(assetNames(before)), new Set(assetNames(after)));
+        assetsAdded += assets.added.length;
+        assetsRemoved += assets.removed.length;
+        const changed = headings.added.length > 0 || headings.removed.length > 0 || assets.added.length > 0 || assets.removed.length > 0 ||
+            (typeof before.title === 'string' ? before.title : '') !== (typeof after.title === 'string' ? after.title : '');
+        if (changed)
+            pages.push({ url, headingsAdded: headings.added, headingsRemoved: headings.removed, assetsAdded: assets.added, assetsRemoved: assets.removed });
+    }
+    const errText = (e) => {
+        if ((e.kind === 'console' && e.level === 'error') || e.kind === 'error') {
+            return typeof e.text === 'string' ? redactText(e.text.trim(), MAX_METADATA_BYTES) : null;
+        }
+        return null;
+    };
+    const failText = (e) => {
+        if (e.kind !== 'network')
+            return null;
+        if (typeof e.status === 'number' && e.status < 400)
+            return null;
+        return `${typeof e.method === 'string' ? e.method.toUpperCase() : 'GET'} ${typeof e.url === 'string' ? redactUrl(e.url) : '(unknown)'} → ${typeof e.status === 'number' ? e.status : 'failed'}`;
+    };
+    const errors = diffSets(textSet(asList(bundleA.events), errText), textSet(asList(bundleB.events), errText));
+    const failures = diffSets(textSet(asList(bundleA.events), failText), textSet(asList(bundleB.events), failText));
+    return ok({
+        scans: { a, b },
+        summary: {
+            pagesChanged: pages.length,
+            assetsAdded,
+            assetsRemoved,
+            newErrors: errors.added.length,
+            newFailures: failures.added.length,
+        },
+        pages: newest(pages, MAX_EVIDENCE_ITEMS).items,
+        newConsoleErrors: errors.added,
+        resolvedConsoleErrors: errors.removed,
+        newFailedRequests: failures.added,
+        resolvedFailedRequests: failures.removed,
+    });
+}
+export const agentToolDefinitions = [
+    {
+        name: 'suggest_page_action',
+        description: 'Interpret a natural-language page command ("click sign in", "type hello into search") against a page snapshot and return ONE structured action (click/input/select/scroll/none with index bounds-checked). Needs auth_login. Prefer scanId (snapshot built from the scan bundle); or pass snapshot text with [n] prefixes directly.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'Voice-style command, 1..500 chars' },
+                scanId: { type: 'string', description: 'Scan id to build the snapshot from (optional if snapshot given)' },
+                snapshot: { type: 'string', description: 'Page text with [n] prefixes, ≤32KiB (optional if scanId given)' },
+                url: { type: 'string', description: 'Page URL override' },
+                title: { type: 'string', description: 'Page title override' },
+            },
+            required: ['command'],
+        },
+    },
+    {
+        name: 'diff_scans',
+        description: 'Diff two scan captures for QA: changed pages, added/removed headings and assets, new vs resolved console errors and failed requests. Anonymous (public capabilities).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scanIdA: { type: 'string', description: 'Before scan id (32-hex)' },
+                scanIdB: { type: 'string', description: 'After scan id (32-hex)' },
+            },
+            required: ['scanIdA', 'scanIdB'],
+        },
+    },
+];

package/dist/asset-tools.d.ts

@@ -0,0 +1,32 @@
+import { ToolContext, ToolResult } from './tool-types.js';
+export declare function runListAssets(context: ToolContext, args: Record<string, unknown>): Promise<ToolResult>;
+export declare function runGetAsset(context: ToolContext, args: Record<string, unknown>): Promise<ToolResult>;
+export declare const assetToolDefinitions: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            limit: {
+                type: string;
+                description: string;
+            };
+            assetId?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            assetId: {
+                type: string;
+                description: string;
+            };
+            limit?: undefined;
+        };
+        required: string[];
+    };
+})[];

package/dist/asset-tools.js

@@ -0,0 +1,195 @@
+import { apiError, DEFAULT_ASSET_LIST, fail, fitMetadata, jsonResponse, MAX_ASSET_LIST, MAX_TEXT_BYTES, numberValue, ok, parseAssetLimit, redactUrl, requireId, truncateUtf8, } from './tool-types.js';
+const INLINE_TYPES = new Set(['text/plain', 'text/csv', 'application/json', 'application/xml', 'image/svg+xml']);
+function pathForAsset(id) {
+    return `/api/assets/${encodeURIComponent(id)}`;
+}
+function mediaPathForAsset(id) {
+    return `${pathForAsset(id)}/media`;
+}
+function assetMetadata(raw) {
+    const source = raw && typeof raw === 'object' ? raw : {};
+    const result = {
+        id: typeof source.id === 'string' ? source.id : '',
+        type: typeof source.type === 'string' ? source.type.slice(0, 256) : '',
+        status: typeof source.status === 'string' ? source.status.slice(0, 64) : '',
+        createdAt: typeof source.createdAt === 'string' ? source.createdAt.slice(0, 128) : '',
+    };
+    const bytes = numberValue(source.bytes);
+    if (bytes !== undefined)
+        result.bytes = bytes;
+    const sourceUrl = redactUrl(source.url);
+    if (sourceUrl)
+        result.sourceUrl = sourceUrl;
+    if (typeof source.domain === 'string' && source.domain)
+        result.sourceDomain = source.domain.slice(0, 2048);
+    if (typeof source.mediaUrl === 'string' && source.status === 'ready')
+        result.mediaUrl = source.mediaUrl;
+    const fitted = fitMetadata(result);
+    return { value: fitted.value, truncated: fitted.truncated };
+}
+async function requireOwner(context, path) {
+    if (!context.authFetch)
+        return fail('This tool requires auth_login. Run auth_login first.');
+    try {
+        const response = await context.authFetch(path, { signal: AbortSignal.timeout(15_000) });
+        if (!response)
+            return fail('Not signed in. Run auth_login first.');
+        return response;
+    }
+    catch (error) {
+        return fail(`Could not reach ${context.apiBase}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function runListAssets(context, args) {
+    const limit = parseAssetLimit(args.limit);
+    if (typeof limit !== 'number')
+        return limit;
+    const response = await requireOwner(context, `/api/assets?limit=${limit}`);
+    if (!('status' in response))
+        return response;
+    if (!response.ok)
+        return apiError(response, context.apiBase);
+    const body = await jsonResponse(response);
+    const rawAssets = Array.isArray(body)
+        ? body
+        : body && typeof body === 'object' && Array.isArray(body.assets)
+            ? body.assets
+            : null;
+    if (!rawAssets)
+        return fail('tautau returned an invalid asset list');
+    // The owner endpoint is newest-first; preserve that order while applying the
+    // requested result bound.
+    const bounded = rawAssets.length > limit
+        ? { items: rawAssets.slice(0, Math.min(limit, MAX_ASSET_LIST)), truncated: true }
+        : { items: rawAssets, truncated: false };
+    const assets = bounded.items.map((asset) => assetMetadata(asset));
+    const result = {
+        assets: assets.map((asset) => asset.value),
+        count: assets.length,
+        originalCount: rawAssets.length,
+    };
+    if (bounded.truncated || assets.some((asset) => asset.truncated))
+        result.truncated = true;
+    return ok(result);
+}
+async function currentMediaUrl(context, id) {
+    if (!context.authFetch)
+        return {};
+    try {
+        const response = await context.authFetch(mediaPathForAsset(id), {
+            redirect: 'manual',
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!response)
+            return {};
+        return { url: response.headers.get('location') || undefined, response };
+    }
+    catch {
+        return {};
+    }
+}
+async function readInlineText(response) {
+    const contentType = (response.headers.get('content-type') || '').split(';', 1)[0].trim().toLowerCase();
+    if (!INLINE_TYPES.has(contentType))
+        return { truncated: false, bytes: 0 };
+    if (!response.body) {
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        const text = new TextDecoder().decode(bytes);
+        return { text: truncateUtf8(text, MAX_TEXT_BYTES), truncated: bytes.byteLength > MAX_TEXT_BYTES, bytes: bytes.byteLength };
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    try {
+        while (total <= MAX_TEXT_BYTES) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            const chunk = next.value;
+            const remaining = MAX_TEXT_BYTES + 1 - total;
+            chunks.push(chunk.slice(0, remaining));
+            total += chunk.byteLength;
+            if (total > MAX_TEXT_BYTES) {
+                truncated = true;
+                break;
+            }
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    const bytes = new Uint8Array(Math.min(total, MAX_TEXT_BYTES + 1));
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk.slice(0, bytes.length - offset), offset);
+        offset += Math.min(chunk.byteLength, bytes.length - offset);
+    }
+    const text = new TextDecoder().decode(bytes);
+    return { text: truncateUtf8(text, MAX_TEXT_BYTES), truncated, bytes: total };
+}
+export async function runGetAsset(context, args) {
+    const id = requireId(args.assetId, 'assetId');
+    if (typeof id !== 'string')
+        return id;
+    const response = await requireOwner(context, pathForAsset(id));
+    if (!('status' in response))
+        return response;
+    if (!response.ok)
+        return apiError(response, context.apiBase);
+    const body = await jsonResponse(response);
+    const rawAsset = body && !Array.isArray(body) && body.asset ? body.asset : body;
+    if (!rawAsset || typeof rawAsset !== 'object')
+        return fail('tautau returned an invalid asset response');
+    const metadata = assetMetadata(rawAsset);
+    // Owner metadata may contain an older signed URL. Always use the dedicated
+    // media route for the URL returned by this tool.
+    delete metadata.value.mediaUrl;
+    const result = { asset: metadata.value };
+    let truncated = metadata.truncated;
+    const source = rawAsset;
+    const type = typeof source.type === 'string' ? source.type.split(';', 1)[0].trim().toLowerCase() : '';
+    const declaredBytes = numberValue(source.bytes);
+    if (source.status === 'ready') {
+        const media = await currentMediaUrl(context, id);
+        if (media.url)
+            result.asset.mediaUrl = media.url;
+        if (INLINE_TYPES.has(type) && (declaredBytes === undefined || declaredBytes <= MAX_TEXT_BYTES) && media.url) {
+            try {
+                const inlineResponse = await context.fetch(media.url, { signal: AbortSignal.timeout(15_000) });
+                if (inlineResponse.ok) {
+                    const inline = await readInlineText(inlineResponse);
+                    if (inline.text !== undefined)
+                        result.text = inline.text;
+                    result.originalByteCount = declaredBytes ?? inline.bytes;
+                    truncated ||= inline.truncated;
+                }
+            }
+            catch {
+                // Metadata and the current media URL remain useful if inline reading fails.
+            }
+        }
+    }
+    if (truncated)
+        result.truncated = true;
+    return ok(result);
+}
+export const assetToolDefinitions = [
+    {
+        name: 'list_assets',
+        description: 'List your tautau asset library with bounded owner metadata. Requires auth_login.',
+        inputSchema: {
+            type: 'object',
+            properties: { limit: { type: 'number', description: `Maximum results, from 1 to ${MAX_ASSET_LIST}; default ${DEFAULT_ASSET_LIST}` } },
+        },
+    },
+    {
+        name: 'get_asset',
+        description: 'Read one owner asset with bounded metadata and a current media URL. Requires auth_login; binary bytes are never inline.',
+        inputSchema: {
+            type: 'object',
+            properties: { assetId: { type: 'string', description: '32-character lowercase hex asset id' } },
+            required: ['assetId'],
+        },
+    },
+];

package/dist/recording-tools.d.ts

@@ -0,0 +1,32 @@
+import { ToolContext, ToolResult } from './tool-types.js';
+export declare function runGetRecording(context: ToolContext, args: Record<string, unknown>): Promise<ToolResult>;
+export declare function runGetScan(context: ToolContext, args: Record<string, unknown>): Promise<ToolResult>;
+export declare const recordingToolDefinitions: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            recordingId: {
+                type: string;
+                description: string;
+            };
+            scanId?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            scanId: {
+                type: string;
+                description: string;
+            };
+            recordingId?: undefined;
+        };
+        required?: undefined;
+    };
+})[];