@hypercli.com/sdk 0.9.1

package/dist/workspaces.js

@@ -0,0 +1,653 @@
+/**
+ * Shared knowledge API - shared Markdown-backed file collections.
+ */
+import { requestWithRetry } from './http.js';
+import { APIError } from './errors.js';
+import { getAgentsApiBaseUrl } from './config.js';
+import { parseWorkspaceTomd } from './workspace-tomd.js';
+export { parseWorkspaceTomd, stripWorkspaceTomdGeneratedSections } from './workspace-tomd.js';
+// Node-only builtins are loaded through an opaque specifier so browser bundles
+// (console, desktop webview) never try to resolve them; the sync helpers below
+// throw a clear error when called outside Node.
+async function loadNodeBuiltin(moduleName) {
+    try {
+        return (await import(/* webpackIgnore: true */ moduleName));
+    }
+    catch {
+        throw new Error(`shared knowledge sync requires a Node.js runtime (${moduleName} is unavailable)`);
+    }
+}
+export function deriveWorkspacesApiBase(agentsApiBase) {
+    const raw = (agentsApiBase || getAgentsApiBaseUrl()).replace(/\/$/, '');
+    const url = new URL(raw.includes('://') ? raw : `https://${raw}`);
+    let path = url.pathname.replace(/\/$/, '');
+    if (path.endsWith('/workspaces')) {
+        return `${url.protocol}//${url.host}${path}`;
+    }
+    if (path.endsWith('/agents')) {
+        path = path.slice(0, -'/agents'.length);
+    }
+    return `${url.protocol}//${url.host}${path}/workspaces`;
+}
+function workspaceFromDict(data) {
+    return {
+        id: String(data?.id || ''),
+        name: data?.name || '',
+        slug: data?.slug || '',
+        description: data?.description ?? null,
+        displayName: data?.display_name ?? data?.displayName ?? null,
+        displaySlug: data?.display_slug ?? data?.displaySlug ?? null,
+        role: data?.role ?? data?.current_role ?? data?.currentRole ?? null,
+        createdAt: data?.created_at ?? data?.createdAt ?? null,
+        updatedAt: data?.updated_at ?? data?.updatedAt ?? null,
+    };
+}
+function grantFromDict(data) {
+    return {
+        id: String(data?.id || ''),
+        workspaceId: String(data?.workspace_id || data?.workspaceId || ''),
+        subjectType: data?.subject_type || data?.subjectType || '',
+        subjectId: data?.subject_id || data?.subjectId || '',
+        role: data?.role || '',
+        displayName: data?.display_name ?? data?.displayName ?? null,
+        displaySlug: data?.display_slug ?? data?.displaySlug ?? null,
+        isOwner: Boolean(data?.is_owner ?? data?.isOwner ?? false),
+        expiresAt: data?.expires_at ?? data?.expiresAt ?? null,
+        revokedAt: data?.revoked_at ?? data?.revokedAt ?? null,
+    };
+}
+const WORKSPACE_ROLE_STRENGTH = {
+    viewer: 1,
+    contributor: 2,
+    admin: 3,
+};
+function grantExpirationTimestamp(grant) {
+    if (grant.expiresAt === null)
+        return null;
+    if (typeof grant.expiresAt !== 'string') {
+        throw new Error(`Invalid expiration timestamp for workspace grant ${grant.id || '<unknown>'}: ${String(grant.expiresAt)}`);
+    }
+    const timestamp = Date.parse(grant.expiresAt);
+    if (!Number.isFinite(timestamp)) {
+        throw new Error(`Invalid expiration timestamp for workspace grant ${grant.id || '<unknown>'}: ${grant.expiresAt}`);
+    }
+    return timestamp;
+}
+function strongestWorkspaceRole(grants) {
+    let strongest = '';
+    let strongestValue = -1;
+    for (const grant of grants) {
+        const value = WORKSPACE_ROLE_STRENGTH[grant.role] ?? 0;
+        if (value > strongestValue || (value === strongestValue && grant.role < strongest)) {
+            strongest = grant.role;
+            strongestValue = value;
+        }
+    }
+    return strongest;
+}
+function agreedNonEmptyValue(values) {
+    const nonEmpty = new Set(values.filter((value) => typeof value === 'string' && value.length > 0));
+    return nonEmpty.size === 1 ? nonEmpty.values().next().value ?? null : null;
+}
+function workspaceAccessEntries(grants, capturedAt) {
+    const grouped = new Map();
+    for (const grant of grants) {
+        const expiresAt = grantExpirationTimestamp(grant);
+        if (grant.revokedAt !== null || (expiresAt !== null && expiresAt <= capturedAt))
+            continue;
+        const key = JSON.stringify([grant.workspaceId, grant.subjectType, grant.subjectId]);
+        let group = grouped.get(key);
+        if (!group) {
+            group = {
+                workspaceId: grant.workspaceId,
+                subjectType: grant.subjectType,
+                subjectId: grant.subjectId,
+                grants: [],
+            };
+            grouped.set(key, group);
+        }
+        group.grants.push(grant);
+    }
+    return Array.from(grouped.values(), (group) => ({
+        workspaceId: group.workspaceId,
+        subjectType: group.subjectType,
+        subjectId: group.subjectId,
+        role: strongestWorkspaceRole(group.grants),
+        displayName: agreedNonEmptyValue(group.grants.map((grant) => grant.displayName)),
+        displaySlug: agreedNonEmptyValue(group.grants.map((grant) => grant.displaySlug)),
+        grants: group.grants,
+    })).sort((left, right) => {
+        if (left.subjectType !== right.subjectType)
+            return left.subjectType < right.subjectType ? -1 : 1;
+        if (left.subjectId !== right.subjectId)
+            return left.subjectId < right.subjectId ? -1 : 1;
+        if (left.workspaceId !== right.workspaceId)
+            return left.workspaceId < right.workspaceId ? -1 : 1;
+        return 0;
+    });
+}
+function latestGrantExpiration(grants) {
+    if (grants.some((grant) => grant.expiresAt === null))
+        return null;
+    let latestValue = null;
+    let latestTimestamp = -Infinity;
+    for (const grant of grants) {
+        const value = grant.expiresAt;
+        const timestamp = grantExpirationTimestamp(grant);
+        if (timestamp > latestTimestamp || (timestamp === latestTimestamp && (latestValue === null || value > latestValue))) {
+            latestValue = value;
+            latestTimestamp = timestamp;
+        }
+    }
+    return latestValue;
+}
+function fileFromDict(data) {
+    return {
+        id: String(data?.id || ''),
+        workspaceId: String(data?.workspace_id || data?.workspaceId || ''),
+        path: data?.path || '',
+        displayName: data?.display_name || data?.displayName || '',
+        currentVersionId: data?.current_version_id || data?.currentVersionId || null,
+        fileState: data?.file_state || data?.fileState || '',
+        uploadStatus: data?.upload_status || data?.uploadStatus || null,
+        processingState: data?.processing_state || data?.processingState || null,
+        keywords: Array.isArray(data?.keywords) ? data.keywords.map(String) : [],
+        summary: data?.summary || null,
+    };
+}
+function fileSearchResultFromDict(data) {
+    return {
+        ...fileFromDict(data),
+        matchReasons: data?.match_reasons || data?.matchReasons || [],
+        keywordScore: Number(data?.keyword_score ?? data?.keywordScore ?? 0),
+        vectorScore: data?.vector_score !== undefined && data?.vector_score !== null
+            ? Number(data.vector_score)
+            : data?.vectorScore !== undefined && data?.vectorScore !== null
+                ? Number(data.vectorScore)
+                : null,
+        score: Number(data?.score ?? 0),
+    };
+}
+function searchPageFromDict(payload) {
+    if (Array.isArray(payload)) {
+        return { results: payload.map(fileSearchResultFromDict), nextCursor: null, hasMore: false };
+    }
+    const data = (payload && typeof payload === 'object' ? payload : {});
+    const rows = Array.isArray(data.items) ? data.items : Array.isArray(data.results) ? data.results : [];
+    const cursor = data.next_cursor ?? data.nextCursor;
+    return {
+        results: rows.map(fileSearchResultFromDict),
+        nextCursor: typeof cursor === 'string' && cursor ? cursor : null,
+        hasMore: (data.has_more ?? data.hasMore) === true,
+    };
+}
+function manifestFromDict(data) {
+    return {
+        workspaceId: String(data?.workspace_id || data?.workspaceId || ''),
+        workspaceName: data?.workspace_name || data?.workspaceName || '',
+        workspaceSlug: data?.workspace_slug || data?.workspaceSlug || '',
+        snapshotId: data?.snapshot_id || data?.snapshotId || '',
+        basePath: data?.base_path || data?.basePath || '',
+        markdownFiles: Array.isArray(data?.markdown_files) ? data.markdown_files : Array.isArray(data?.markdownFiles) ? data.markdownFiles : [],
+    };
+}
+function downloadUrlFromDict(data) {
+    return {
+        fileId: String(data?.file_id || data?.fileId || ''),
+        path: data?.path || '',
+        version: Number(data?.version || 0),
+        url: data?.url ?? null,
+        downloadCommand: data?.download_command || data?.downloadCommand || '',
+    };
+}
+async function responseErrorDetail(response) {
+    const text = await response.text();
+    if (!text)
+        return response.statusText;
+    try {
+        const payload = JSON.parse(text);
+        const detail = payload?.detail ?? payload?.message ?? payload?.error;
+        if (typeof detail === 'string')
+            return detail;
+        if (detail !== undefined && detail !== null)
+            return JSON.stringify(detail);
+        return text;
+    }
+    catch {
+        return text;
+    }
+}
+async function handleResponse(response) {
+    if (response.status >= 400) {
+        throw new APIError(response.status, await responseErrorDetail(response));
+    }
+    if (response.status === 204 || response.status === 205)
+        return undefined;
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    return JSON.parse(text);
+}
+async function handleBytesResponse(response) {
+    if (response.status >= 400) {
+        throw new APIError(response.status, await responseErrorDetail(response));
+    }
+    return new Uint8Array(await response.arrayBuffer());
+}
+function encodeRef(value) {
+    return encodeURIComponent(value);
+}
+function encodeFileRef(value) {
+    return normalizePosixPath(value)
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '')
+        .split('/')
+        .map(encodeURIComponent)
+        .join('/');
+}
+function workspaceMatchesEnsureOptions(workspace, options) {
+    if (options.match?.(workspace))
+        return true;
+    if (options.slug && workspace.slug === options.slug)
+        return true;
+    return !options.slug && workspace.name === options.name;
+}
+export class WorkspacesAPI {
+    apiBase;
+    apiKey;
+    timeout;
+    uploadTimeout;
+    constructor(apiKey, options = {}) {
+        if (!apiKey) {
+            throw new Error('API key required for shared knowledge');
+        }
+        this.apiKey = apiKey;
+        this.apiBase = (options.apiBase || deriveWorkspacesApiBase(options.agentsApiBase)).replace(/\/$/, '');
+        this.timeout = options.timeout ?? 30000;
+        this.uploadTimeout = options.uploadTimeout ?? Math.max(this.timeout, 120000);
+    }
+    headers(_subject = {}) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+        };
+        return headers;
+    }
+    authHeaders(_subject = {}) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        return headers;
+    }
+    async request(method, path, subject = {}, body) {
+        const response = await requestWithRetry({
+            method,
+            url: `${this.apiBase}${path}`,
+            headers: this.headers(subject),
+            body,
+            retries: method === 'GET' ? 3 : 1,
+            timeout: this.timeout,
+        });
+        return handleResponse(response);
+    }
+    async list(subject = {}) {
+        const data = await this.request('GET', '', subject);
+        return (data || []).map(workspaceFromDict);
+    }
+    async get(workspaceRef, subject = {}) {
+        const data = await this.request('GET', `/${encodeRef(workspaceRef)}`, subject);
+        return workspaceFromDict(data);
+    }
+    async accessSnapshot(workspaceRef, subject = {}) {
+        const workspace = await this.get(workspaceRef, subject);
+        const capturedTime = new Date();
+        const capturedAt = capturedTime.toISOString();
+        const currentRole = workspace.role;
+        if (currentRole !== 'admin') {
+            return {
+                workspace,
+                currentRole,
+                visibility: 'current-access-only',
+                capturedAt,
+                entries: null,
+                grants: null,
+            };
+        }
+        const grants = await this.listGrants(workspaceRef, subject);
+        return {
+            workspace,
+            currentRole,
+            visibility: 'all-direct-access',
+            capturedAt,
+            entries: workspaceAccessEntries(grants, capturedTime.getTime()),
+            grants,
+        };
+    }
+    async listAgentAssociations(workspaceRef, subject = {}) {
+        const snapshot = await this.accessSnapshot(workspaceRef, subject);
+        if (snapshot.visibility !== 'all-direct-access' || snapshot.entries === null) {
+            throw new Error('Workspace agent associations are available only to Workspace admins.');
+        }
+        return snapshot.entries
+            .filter((entry) => entry.subjectType === 'agent')
+            .map((entry) => ({
+            workspaceId: entry.workspaceId,
+            agentId: entry.subjectId,
+            role: entry.role,
+            expiresAt: latestGrantExpiration(entry.grants),
+        }));
+    }
+    async search(query, subject = {}, options = {}) {
+        const params = new URLSearchParams({ q: query, vector: String(options.vector ?? true) });
+        const data = await this.request('GET', `/search?${params.toString()}`, subject);
+        return (data || []).map(workspaceFromDict);
+    }
+    async create(body, subject = {}) {
+        const data = await this.request('POST', '', subject, body);
+        return workspaceFromDict(data);
+    }
+    async ensureWorkspace(options, subject = {}) {
+        const listed = await this.list(subject);
+        const existing = listed.find((workspace) => workspaceMatchesEnsureOptions(workspace, options));
+        if (existing)
+            return { workspace: existing, created: false };
+        try {
+            return {
+                workspace: await this.create({
+                    name: options.name,
+                    ...(options.slug !== undefined ? { slug: options.slug } : {}),
+                    ...(options.description !== undefined ? { description: options.description } : {}),
+                }, subject),
+                created: true,
+            };
+        }
+        catch (error) {
+            if (!(error instanceof APIError) || error.statusCode !== 409)
+                throw error;
+            const recovered = await this.list(subject);
+            const recoveredWorkspace = recovered.find((workspace) => workspaceMatchesEnsureOptions(workspace, options));
+            if (recoveredWorkspace)
+                return { workspace: recoveredWorkspace, created: false };
+            throw error;
+        }
+    }
+    async update(workspaceRef, body, subject = {}) {
+        const data = await this.request('PATCH', `/${encodeRef(workspaceRef)}`, subject, body);
+        return workspaceFromDict(data);
+    }
+    async delete(workspaceRef, subject = {}) {
+        await this.request('DELETE', `/${encodeRef(workspaceRef)}`, subject);
+    }
+    async grant(workspaceRef, body, subject = {}) {
+        const data = await this.request('POST', `/${encodeRef(workspaceRef)}/grants`, subject, {
+            subject_type: body.subjectType,
+            subject_id: body.subjectId,
+            role: body.role ?? 'viewer',
+            ...(body.displayName !== undefined ? { display_name: body.displayName } : {}),
+            ...(body.displaySlug !== undefined ? { display_slug: body.displaySlug } : {}),
+            ...(body.expiresAt !== undefined ? { expires_at: body.expiresAt } : {}),
+        });
+        return grantFromDict(data);
+    }
+    async listGrants(workspaceRef, subject = {}) {
+        const data = await this.request('GET', `/${encodeRef(workspaceRef)}/grants`, subject);
+        if (!Array.isArray(data)) {
+            throw new Error('Workspace grants response must be an array.');
+        }
+        return data.map(grantFromDict);
+    }
+    async updateGrant(workspaceRef, grantId, body, subject = {}) {
+        const data = await this.request('PATCH', `/${encodeRef(workspaceRef)}/grants/${encodeRef(grantId)}`, subject, {
+            ...(body.role !== undefined ? { role: body.role } : {}),
+            ...(body.expiresAt !== undefined ? { expires_at: body.expiresAt } : {}),
+        });
+        return grantFromDict(data);
+    }
+    /**
+     * Accept a workspace invite addressed to the signed-in user's email
+     * (`POST /invites/accept/{grant_id}`). The grant id arrives out-of-band via
+     * the invite email link; there is no pending-invites listing endpoint.
+     * Errors surface as APIError: 404 unknown grant, 403 wrong email or non-user
+     * caller, 409 revoked/expired/already-accepted.
+     */
+    async acceptInvite(grantId, subject = {}) {
+        const data = await this.request('POST', `/invites/accept/${encodeRef(grantId)}`, subject);
+        return grantFromDict(data);
+    }
+    async revokeGrant(workspaceRef, grantId, subject = {}) {
+        await this.request('DELETE', `/${encodeRef(workspaceRef)}/grants/${encodeRef(grantId)}`, subject);
+    }
+    async registerFile(workspaceRef, body, subject = {}) {
+        const data = await this.request('POST', `/${encodeRef(workspaceRef)}/files`, subject, {
+            path: body.path,
+            source_filename: body.sourceFilename,
+            source_content_type: body.sourceContentType,
+            source_size_bytes: body.sourceSizeBytes,
+            source_sha256: body.sourceSha256,
+            source_etag: body.sourceEtag,
+            keywords: body.keywords,
+        });
+        return fileFromDict(data);
+    }
+    async uploadFile(workspaceRef, file, options = {}, subject = {}) {
+        const formData = new FormData();
+        const filename = options.filename || (typeof File !== 'undefined' && file instanceof File ? file.name : 'upload');
+        formData.append('workspace', workspaceRef);
+        formData.append('file', file, filename);
+        if (options.path)
+            formData.append('path', options.path);
+        if (options.sourceEtag)
+            formData.append('source_etag', options.sourceEtag);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.uploadTimeout);
+        try {
+            const response = await fetch(`${this.apiBase}/upload`, {
+                method: 'POST',
+                headers: this.authHeaders(subject),
+                body: formData,
+                signal: controller.signal,
+            });
+            return fileFromDict(await handleResponse(response));
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    async getFile(workspaceRef, fileRef, subject = {}) {
+        const data = await this.request('GET', `/${encodeRef(workspaceRef)}/files/${encodeFileRef(fileRef)}`, subject);
+        return fileFromDict(data);
+    }
+    async updateFile(workspaceRef, fileRef, body, subject = {}) {
+        const data = await this.request('PATCH', `/${encodeRef(workspaceRef)}/files/${encodeFileRef(fileRef)}`, subject, {
+            ...(body.displayName !== undefined ? { display_name: body.displayName } : {}),
+            ...(body.keywords !== undefined ? { keywords: body.keywords } : {}),
+            ...(body.summary !== undefined ? { summary: body.summary } : {}),
+        });
+        return fileFromDict(data);
+    }
+    async regenerateFile(workspaceRef, fileRef, subject = {}) {
+        const data = await this.request('POST', `/${encodeRef(workspaceRef)}/files/${encodeFileRef(fileRef)}/regenerate`, subject);
+        return fileFromDict(data);
+    }
+    async waitUntilProcessed(workspaceRef, fileRef, subject = {}, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 300000;
+        const pollIntervalMs = options.pollIntervalMs ?? 2000;
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            const file = await this.getFile(workspaceRef, fileRef, subject);
+            if (file.fileState === 'processed' && file.processingState === 'processed') {
+                return file;
+            }
+            if (file.fileState === 'failed' || file.fileState === 'deleted' || file.processingState === 'failed' || file.processingState === 'deleted') {
+                throw new Error(`Shared knowledge file ${fileRef} is ${file.fileState} with processing ${file.processingState || 'unknown'}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+        throw new Error(`Shared knowledge file ${fileRef} did not process within ${timeoutMs}ms`);
+    }
+    async listFiles(workspaceRef, subject = {}) {
+        const data = await this.request('GET', `/${encodeRef(workspaceRef)}/files`, subject);
+        return (data || []).map(fileFromDict);
+    }
+    /**
+     * Search workspace files. `vector` is only sent when explicitly set —
+     * omitted defers to the backend default (`true`, keyword-only until the
+     * hybrid branch ships). `cursor`/`limit`/`pathPrefix` ride the query string for
+     * the paginated backend; today's route ignores them and answers with a bare
+     * array, which surfaces as `{ results, nextCursor: null, hasMore: false }`.
+     */
+    async searchFiles(workspaceRef, query, subject = {}, options = {}) {
+        const params = new URLSearchParams({ q: query });
+        if (options.vector !== undefined)
+            params.set('vector', String(options.vector));
+        if (options.cursor)
+            params.set('cursor', options.cursor);
+        if (options.limit !== undefined)
+            params.set('limit', String(options.limit));
+        if (options.pathPrefix)
+            params.set('path_prefix', options.pathPrefix);
+        const payload = await this.request('GET', `/${encodeRef(workspaceRef)}/files/search?${params.toString()}`, subject);
+        return searchPageFromDict(payload);
+    }
+    async manifest(workspaceRef, subject = {}) {
+        const data = await this.request('GET', `/${encodeRef(workspaceRef)}/manifest`, subject);
+        return manifestFromDict(data);
+    }
+    async downloadUrl(workspaceRef, fileRef, subject = {}) {
+        const data = await this.request('POST', `/download-url`, subject, { workspace: workspaceRef, path: fileRef });
+        return downloadUrlFromDict(data);
+    }
+    async downloadFileBytes(workspaceRef, fileRef, subject = {}, options = {}) {
+        const response = await requestWithRetry({
+            method: 'POST',
+            url: `${this.apiBase}/download`,
+            headers: this.headers(subject),
+            body: { workspace: workspaceRef, path: fileRef, raw: Boolean(options.raw), index: options.index ?? 1 },
+            timeout: this.timeout,
+        });
+        const path = fileRef;
+        return {
+            content: await handleBytesResponse(response),
+            path,
+            name: fileNameFromPath(path),
+        };
+    }
+    async deleteFile(workspaceRef, fileRef, subject = {}) {
+        await this.request('DELETE', `/${encodeRef(workspaceRef)}/files/${encodeFileRef(fileRef)}`, subject);
+    }
+    /**
+     * Get raw metadata for one file (`POST /workspaces/meta`).
+     */
+    async meta(workspaceRef, fileRef, subject = {}) {
+        return await this.request('POST', '/meta', subject, { workspace: workspaceRef, path: fileRef });
+    }
+    /**
+     * Write every Markdown projection for a workspace to
+     * `<outputDir>/<workspace_slug>/<path>.md` and return the written paths.
+     */
+    async syncManifest(workspaceRef, outputDir, subject = {}, options = {}) {
+        // Node-only: keep this module browser-importable by loading fs/path lazily
+        // with an opaque specifier so browser bundles skip these imports.
+        const fs = await loadNodeBuiltin('node:fs');
+        const path = await loadNodeBuiltin('node:path');
+        const manifest = await this.manifest(workspaceRef, subject);
+        const workspaceRoot = path.join(outputDir, manifest.workspaceSlug);
+        const written = [];
+        for (const markdownFile of manifest.markdownFiles) {
+            if (!markdownFile || typeof markdownFile !== 'object')
+                continue;
+            if (options.readyOnly && markdownFile.state !== 'processed')
+                continue;
+            const markdownPath = normalizePosixPath(String(markdownFile.path || ''));
+            if (!markdownPath) {
+                throw new Error('Workspace manifest markdown entry is missing a path');
+            }
+            const target = path.resolve(workspaceRoot, ...`${markdownPath}.md`.split('/').filter(Boolean));
+            const rootResolved = path.resolve(workspaceRoot);
+            if (target !== rootResolved && !target.startsWith(rootResolved + path.sep)) {
+                throw new Error(`Unsafe markdown path: ${markdownPath}.md`);
+            }
+            let body;
+            try {
+                const response = await requestWithRetry({
+                    method: 'POST',
+                    url: `${this.apiBase}/tomd`,
+                    headers: this.headers(subject),
+                    body: { workspace: workspaceRef, path: markdownFile.path, index: 1 },
+                    retries: options.readyOnly ? 1 : 3,
+                    timeout: this.timeout,
+                });
+                body = new TextDecoder().decode(await handleBytesResponse(response));
+            }
+            catch (error) {
+                if (options.readyOnly &&
+                    error instanceof APIError &&
+                    error.statusCode === 404 &&
+                    String(error.detail ?? '').toLowerCase().includes('workspace markdown not found')) {
+                    continue;
+                }
+                throw error;
+            }
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, body, 'utf8');
+            written.push(target);
+        }
+        return written;
+    }
+    /**
+     * Sync every shared Markdown collection to `<outputDir>/<slug>/...`.
+     * Returns a map from workspace slug to written file paths.
+     */
+    async syncAll(outputDir, subject = {}, options = {}) {
+        const synced = {};
+        for (const workspace of await this.list(subject)) {
+            synced[workspace.slug] = await this.syncManifest(workspace.id, outputDir, subject, options);
+        }
+        return synced;
+    }
+    async markdownFile(workspaceRef, fileRef, subject = {}) {
+        const manifest = await this.manifest(workspaceRef, subject);
+        const markdownFile = findMarkdownFile(manifest, fileRef);
+        const response = await requestWithRetry({
+            method: 'POST',
+            url: `${this.apiBase}/tomd`,
+            headers: this.headers(subject),
+            body: { workspace: workspaceRef, path: markdownFile.path || fileRef, index: 1 },
+            timeout: this.timeout,
+        });
+        const bytes = await handleBytesResponse(response);
+        return { markdownFile, markdown: new TextDecoder().decode(bytes) };
+    }
+    /**
+     * `markdownFile` with the `/tomd` document parsed: typed frontmatter plus
+     * the body (and `contentBody`, the body minus the sections the pipeline
+     * generates from the frontmatter). `markdownFile()` stays the raw-string
+     * variant.
+     */
+    async tomdDocument(workspaceRef, fileRef, subject = {}) {
+        const { markdownFile, markdown } = await this.markdownFile(workspaceRef, fileRef, subject);
+        return { markdownFile, markdown, ...parseWorkspaceTomd(markdown) };
+    }
+}
+function findMarkdownFile(manifest, fileRef) {
+    const normalizedRef = normalizePosixPath(fileRef);
+    for (const markdownFile of manifest.markdownFiles) {
+        if (!markdownFile || typeof markdownFile !== 'object')
+            continue;
+        if (fileRef === String(markdownFile.file_id || '')) {
+            return markdownFile;
+        }
+        if (normalizedRef === normalizePosixPath(String(markdownFile.path || ''))) {
+            return markdownFile;
+        }
+    }
+    throw new Error(`Shared knowledge Markdown file not found for ${fileRef}`);
+}
+function normalizePosixPath(path) {
+    return path.trim().replace(/\\/g, '/').replace(/^\.\/+/, '');
+}
+function fileNameFromPath(path) {
+    const normalized = normalizePosixPath(path).replace(/^\/+/, '').replace(/\/+$/, '');
+    return normalized.split('/').filter(Boolean).at(-1) || normalized || 'file';
+}
+//# sourceMappingURL=workspaces.js.map