sfora-cli 0.15.0 → 0.17.0

package/dist/local-core/skill-sync.d.ts

@@ -0,0 +1,132 @@
+import type { SkillCloudBinding, SkillRevision } from './skill-domain.js';
+import type { SkillStore } from './skill-store.js';
+import { type SkillBundle, type inspectSkillTarget } from './skills.js';
+export interface SkillCloudScope {
+    deployment: string;
+    accountId: string;
+    organizationId: string;
+}
+export interface PublishedSkillSnapshot {
+    remote: SkillCloudBinding['remote'];
+    accountId: string;
+    locator: SkillCloudBinding['locator'];
+    revision: SkillRevision;
+    draftRevision: number;
+    hasDraft: boolean;
+    draftHash?: string;
+    supportsIdentityGuards?: boolean;
+    bundle: SkillBundle;
+}
+export type SkillTransferPlan = ReturnType<typeof planSkillTransfer>;
+/** A new installation needs an explicitly selected empty destination, not a guessed name match. */
+export declare function planSkillInstallation(remote: PublishedSkillSnapshot, destination: string, target: Awaited<ReturnType<typeof inspectSkillTarget>>): {
+    schemaVersion: 1;
+    kind: "skill-install-preview";
+    source: {
+        accountId: string;
+        deployment: string;
+        organizationId: string;
+        skillId: string;
+        projectId: string;
+    };
+    locator: {
+        project: string;
+        name: string;
+    };
+    destination: string;
+    expected: {
+        remote: {
+            hash: string;
+            contentPolicy: "bundle-v1";
+            cloudVersion?: number;
+        };
+        targetState: "file" | "link" | "unavailable" | "managed" | "unmanaged" | "modified" | "missing";
+        localHash: string | null;
+    };
+    ownership: "unknown" | "managed" | "unmanaged";
+    outcome: string;
+    blockers: string[];
+    files: {
+        path: string;
+        kind: "added";
+        after: {
+            hash: string;
+            size: number;
+            executable: boolean;
+        };
+    }[];
+};
+export type SkillContentState = {
+    state: 'available';
+    bundle: SkillBundle;
+} | {
+    state: 'missing';
+    reason: string;
+} | {
+    state: 'unavailable';
+    reason: string;
+};
+export type SkillSyncStatus = 'local-only' | 'synced' | 'local-changed' | 'remote-changed' | 'conflict' | 'missing' | 'unknown' | 'unavailable';
+export declare function assertSkillBindingScope(binding: SkillCloudBinding, scope: SkillCloudScope): void;
+export declare function validatePublishedSkillSnapshot(snapshot: PublishedSkillSnapshot): void;
+export declare function assertSkillBindingSnapshot(binding: SkillCloudBinding, snapshot: PublishedSkillSnapshot): void;
+/** Adoption is explicit. Matching names, install receipts and stale observations cannot establish a baseline. */
+export declare class SkillBindingService {
+    readonly store: SkillStore;
+    constructor(store: SkillStore);
+    list(): Promise<SkillCloudBinding[]>;
+    adopt(localSkillId: string, snapshot: PublishedSkillSnapshot, verifiedLocal: SkillBundle): Promise<SkillCloudBinding>;
+}
+/** Pure three-way comparison. Unavailable input is never interpreted as deletion or synchronization. */
+export declare function compareSkillStates(local: SkillContentState, remote: SkillContentState | undefined, baseline?: SkillRevision): SkillSyncStatus;
+/** Review artifact only. A future executor must revalidate every token and record a durable operation. */
+export declare function planSkillTransfer(input: {
+    direction: 'push' | 'pull';
+    binding: SkillCloudBinding;
+    location: {
+        id: string;
+        path: string;
+        skillId: string;
+    };
+    local: SkillContentState;
+    remote: PublishedSkillSnapshot;
+    ownership: 'managed' | 'unmanaged' | 'unknown';
+}): {
+    schemaVersion: 1;
+    kind: "skill-transfer-preview";
+    direction: "push" | "pull";
+    status: SkillSyncStatus;
+    outcome: string;
+    blockers: string[];
+    binding: SkillCloudBinding;
+    location: {
+        id: string;
+        path: string;
+        skillId: string;
+    };
+    ownership: "unknown" | "managed" | "unmanaged";
+    expected: {
+        localHash: string | null;
+        remote: {
+            hash: string;
+            contentPolicy: "bundle-v1";
+            cloudVersion?: number;
+        };
+        draftRevision: number;
+    };
+    files: {
+        before: {
+            hash: string;
+            size: number;
+            executable: boolean;
+        } | null;
+        after: {
+            hash: string;
+            size: number;
+            executable: boolean;
+        } | null;
+        path: string;
+        kind: "added" | "removed" | "modified";
+    }[];
+};
+export type SkillInstallPlan = ReturnType<typeof planSkillInstallation>;

package/dist/local-core/skill-sync.js

@@ -0,0 +1,111 @@
+import { randomUUID } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { diffSkillBundles, validateSkillBundle } from './skills.js';
+/** A new installation needs an explicitly selected empty destination, not a guessed name match. */
+export function planSkillInstallation(remote, destination, target) {
+    validatePublishedSkillSnapshot(remote);
+    if (!isAbsolute(destination))
+        throw new Error('Installation destination must be absolute.');
+    const blockers = target.state === 'missing' ? [] : ['Destination is occupied or unavailable. Choose a new folder, or explicitly bind and review an update.'];
+    return { schemaVersion: 1, kind: 'skill-install-preview', source: { ...remote.remote, accountId: remote.accountId }, locator: { ...remote.locator }, destination,
+        expected: { remote: { ...remote.revision }, targetState: target.state, localHash: target.hash ?? null }, ownership: target.ownership,
+        outcome: blockers.length ? 'blocked' : 'reviewable', blockers,
+        files: remote.bundle.files.map(f => ({ path: f.path, kind: 'added', after: { hash: f.sha256, size: f.size, executable: f.executable } })) };
+}
+export function assertSkillBindingScope(binding, scope) {
+    if (binding.accountId !== scope.accountId || binding.remote.deployment !== scope.deployment || binding.remote.organizationId !== scope.organizationId) {
+        throw new Error('Skill binding belongs to a different account, organization or deployment. Explicitly link the intended destination.');
+    }
+}
+export function validatePublishedSkillSnapshot(snapshot) {
+    validateSkillBundle(snapshot.bundle);
+    if (snapshot.revision.contentPolicy !== 'bundle-v1' || snapshot.revision.hash !== snapshot.bundle.hash
+        || !Number.isSafeInteger(snapshot.revision.cloudVersion) || Number(snapshot.revision.cloudVersion) < 1
+        || !Number.isSafeInteger(snapshot.draftRevision) || snapshot.draftRevision < 0 || typeof snapshot.hasDraft !== 'boolean') {
+        throw new Error('Published skill revision does not match its verified bundle.');
+    }
+}
+export function assertSkillBindingSnapshot(binding, snapshot) {
+    validatePublishedSkillSnapshot(snapshot);
+    assertSkillBindingScope(binding, { ...snapshot.remote, accountId: snapshot.accountId });
+    if (binding.remote.skillId !== snapshot.remote.skillId || binding.remote.projectId !== snapshot.remote.projectId) {
+        throw new Error('Cloud lookup resolved to a different skill identity. No binding was changed.');
+    }
+}
+/** Adoption is explicit. Matching names, install receipts and stale observations cannot establish a baseline. */
+export class SkillBindingService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async list() { return (await this.store.read()).bindings; }
+    async adopt(localSkillId, snapshot, verifiedLocal) {
+        validatePublishedSkillSnapshot(snapshot);
+        validateSkillBundle(verifiedLocal);
+        return this.store.transaction(c => {
+            if (!c.identities.some(i => i.id === localSkillId))
+                throw new Error('Local skill identity not found. Refresh the inventory first.');
+            const existing = c.bindings.find(b => b.localSkillId === localSkillId && b.accountId === snapshot.accountId
+                && b.remote.deployment === snapshot.remote.deployment && b.remote.organizationId === snapshot.remote.organizationId && b.remote.projectId === snapshot.remote.projectId);
+            if (existing)
+                assertSkillBindingSnapshot(existing, snapshot);
+            const binding = existing ?? { id: randomUUID(), localSkillId, remote: { ...snapshot.remote }, accountId: snapshot.accountId, locator: { ...snapshot.locator } };
+            binding.locator = { ...snapshot.locator };
+            // Differing bytes retain the last confirmed baseline, or remain unknown.
+            if (verifiedLocal.hash === snapshot.revision.hash)
+                binding.baseline = { ...snapshot.revision };
+            if (!existing)
+                c.bindings.push(binding);
+            return structuredClone(binding);
+        });
+    }
+}
+/** Pure three-way comparison. Unavailable input is never interpreted as deletion or synchronization. */
+export function compareSkillStates(local, remote, baseline) {
+    if (local.state === 'available')
+        validateSkillBundle(local.bundle);
+    if (remote?.state === 'available')
+        validateSkillBundle(remote.bundle);
+    if (local.state === 'unavailable' || remote?.state === 'unavailable')
+        return 'unavailable';
+    if (local.state === 'missing' || remote?.state === 'missing')
+        return 'missing';
+    if (!remote)
+        return 'local-only';
+    if (!baseline || baseline.contentPolicy !== 'bundle-v1' || !/^[a-f0-9]{64}$/.test(baseline.hash))
+        return 'unknown';
+    if (local.bundle.hash === remote.bundle.hash)
+        return 'synced';
+    if (local.bundle.hash === baseline.hash)
+        return 'remote-changed';
+    if (remote.bundle.hash === baseline.hash)
+        return 'local-changed';
+    return 'conflict';
+}
+/** Review artifact only. A future executor must revalidate every token and record a durable operation. */
+export function planSkillTransfer(input) {
+    const { binding, local, remote, direction, location, ownership } = input;
+    assertSkillBindingSnapshot(binding, remote);
+    if (location.skillId !== binding.localSkillId)
+        throw new Error('Location does not belong to the bound local skill.');
+    const status = compareSkillStates(local, { state: 'available', bundle: remote.bundle }, binding.baseline);
+    const blockers = [];
+    if (!['synced', direction === 'push' ? 'local-changed' : 'remote-changed'].includes(status))
+        blockers.push(`Cannot ${direction} automatically from ${status}; review the divergence first.`);
+    if (status !== 'synced' && direction === 'pull' && ownership !== 'managed')
+        blockers.push('Replacing local files requires verified Sfora ownership or an explicitly chosen new destination.');
+    if (status !== 'synced' && direction === 'push' && remote.hasDraft)
+        blockers.push('The cloud contains an unpublished draft; review it before replacing it.');
+    const before = direction === 'push' ? remote.bundle : local.state === 'available' ? local.bundle : undefined;
+    const after = direction === 'pull' ? remote.bundle : local.state === 'available' ? local.bundle : undefined;
+    const files = before && after ? diffSkillBundles(before, after).map(change => {
+        const metadata = (bundle) => { const f = bundle.files.find(f => f.path === change.path); return f ? { hash: f.sha256, size: f.size, executable: f.executable } : null; };
+        return { ...change, before: metadata(before), after: metadata(after) };
+    }) : [];
+    return {
+        schemaVersion: 1, kind: 'skill-transfer-preview', direction, status,
+        outcome: blockers.length ? 'blocked' : status === 'synced' ? 'no-op' : 'reviewable', blockers,
+        binding: structuredClone(binding), location: { ...location }, ownership,
+        expected: { localHash: local.state === 'available' ? local.bundle.hash : null, remote: { ...remote.revision }, draftRevision: remote.draftRevision }, files,
+    };
+}

package/dist/local-core/skills.d.ts

@@ -33,7 +33,33 @@ export declare function validateSkillName(name: string): void;
 export declare function validateSkillPath(path: string): void;
 export declare function skillBundleHash(files: SkillFile[]): string;
 export declare function validateSkillBundle(bundle: SkillBundle): void;
+/** The longest `description` a SKILL.md may carry (the Agent Skills format's limit). */
+export declare const SKILL_DESCRIPTION_MAX = 1024;
+/**
+ * The top-level scalar keys of a SKILL.md frontmatter block, or `null` when the
+ * file does not open with one. A deliberately small YAML reader: plain, quoted
+ * and block (`|`, `>`) scalars, plus indented continuation lines. Nested maps
+ * (`metadata:`) are skipped. It never throws; a value it cannot read is absent.
+ */
+export declare function readSkillFrontmatter(markdown: string): Record<string, string> | null;
+/**
+ * What is wrong with a bundle's SKILL.md frontmatter, as sentences; empty when
+ * nothing is. `name` must be present and equal the folder name, `description`
+ * present, non-empty and at most {@link SKILL_DESCRIPTION_MAX} characters.
+ * Kept apart from {@link validateSkillBundle} on purpose: that one gates every
+ * read (scan, inventory, uninstall, cloud download), and many existing skills
+ * have no frontmatter at all. This one gates what Sfora itself publishes or
+ * ships: `skills push` and `skills packet install`.
+ */
+export declare function skillFrontmatterProblems(bundle: SkillBundle): string[];
+/**
+ * Throws every {@link skillFrontmatterProblems} finding, followed by the exact
+ * block to write, with the folder name filled in: a skill that pushed fine
+ * before this check existed is fixed with one edit.
+ */
+export declare function validateSkillFrontmatter(bundle: SkillBundle): void;
 export declare function readSkillBundle(directory: string, name?: string): Promise<SkillBundle>;
+/** Legacy array API; the shared discovery engine owns all traversal. */
 export declare function scanLocalSkills(roots?: string[]): Promise<Array<{
     path: string;
     name: string;
@@ -41,5 +67,14 @@ export declare function scanLocalSkills(roots?: string[]): Promise<Array<{
     error?: string;
 }>>;
 export declare function diffSkillBundles(local: SkillBundle, incoming: SkillBundle): SkillDifference[];
+export declare function readInstallation(destination: string): Promise<SkillInstallation | undefined>;
+/** A receipt is historical intent. Classify today's filesystem object before trusting it. */
+export declare function inspectSkillTarget(directory: string): Promise<{
+    state: 'missing' | 'link' | 'file' | 'managed' | 'modified' | 'unmanaged' | 'unavailable';
+    ownership: 'managed' | 'unmanaged' | 'unknown';
+    hash?: string;
+    receipt?: SkillInstallation;
+    reason?: string;
+}>;
 export declare function installSkillBundle(bundle: SkillBundle, targetRoot: string, source?: string, sourceVersion?: number): Promise<SkillInstallation>;
 export declare function uninstallSkill(directory: string): Promise<void>;

package/dist/local-core/skills.js

@@ -1,7 +1,6 @@
 import { constants } from "node:fs";
-import { chmod, lstat, mkdir, open, readdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, open, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { atomicWrite, LocalConflictError, sha256, withLocalLock } from "./files.js";
 export const SKILL_LIMITS = { files: 1000, fileBytes: 5 * 1024 * 1024, totalBytes: 20 * 1024 * 1024 };
@@ -52,6 +51,99 @@ export function validateSkillBundle(bundle) {
     if (skillBundleHash(bundle.files) !== bundle.hash)
         throw new Error("Invalid skill bundle hash.");
 }
+/** The longest `description` a SKILL.md may carry (the Agent Skills format's limit). */
+export const SKILL_DESCRIPTION_MAX = 1024;
+/**
+ * The top-level scalar keys of a SKILL.md frontmatter block, or `null` when the
+ * file does not open with one. A deliberately small YAML reader: plain, quoted
+ * and block (`|`, `>`) scalars, plus indented continuation lines. Nested maps
+ * (`metadata:`) are skipped. It never throws; a value it cannot read is absent.
+ */
+export function readSkillFrontmatter(markdown) {
+    const m = /^?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(markdown);
+    if (!m)
+        return null;
+    const lines = m[1].split(/\r?\n/);
+    const out = {};
+    for (let i = 0; i < lines.length; i++) {
+        const key = /^([A-Za-z_][\w-]*):(?:[ \t]+(.*))?$/.exec(lines[i]);
+        if (!key)
+            continue;
+        const given = (key[2] ?? "").trim();
+        const raw = /^["']/.test(given) ? given : given.replace(/[ \t]+#.*$/, "").trim();
+        const body = [];
+        while (i + 1 < lines.length && (/^[ \t]+\S/.test(lines[i + 1]) || (lines[i + 1].trim() === "" && /^[|>]/.test(raw))))
+            body.push(lines[++i]);
+        let value;
+        if (/^[|>][+-]?$/.test(raw)) {
+            const indent = Math.min(...body.filter(l => l.trim()).map(l => /^[ \t]*/.exec(l)[0].length));
+            const text = body.map(l => l.slice(Number.isFinite(indent) ? indent : 0));
+            value = raw.startsWith("|") ? text.join("\n") : text.map(l => l.trim()).join(" ").replace(/ {2,}/g, " ");
+        }
+        else if (!raw && body.length)
+            continue; // a nested map, not a scalar
+        else {
+            value = [raw, ...body.map(l => l.trim())].filter(Boolean).join(" ");
+            const q = /^(["'])([\s\S]*)\1$/.exec(value);
+            if (q)
+                value = q[1] === "'" ? q[2].replace(/''/g, "'") : q[2].replace(/\\"/g, '"');
+        }
+        out[key[1]] = value.trim();
+    }
+    return out;
+}
+/**
+ * What is wrong with a bundle's SKILL.md frontmatter, as sentences; empty when
+ * nothing is. `name` must be present and equal the folder name, `description`
+ * present, non-empty and at most {@link SKILL_DESCRIPTION_MAX} characters.
+ * Kept apart from {@link validateSkillBundle} on purpose: that one gates every
+ * read (scan, inventory, uninstall, cloud download), and many existing skills
+ * have no frontmatter at all. This one gates what Sfora itself publishes or
+ * ships: `skills push` and `skills packet install`.
+ */
+export function skillFrontmatterProblems(bundle) {
+    const file = bundle.files.find(f => f.path === "SKILL.md");
+    if (!file)
+        return ["A skill must contain SKILL.md."];
+    const fm = readSkillFrontmatter(Buffer.from(file.contentBase64, "base64").toString("utf8"));
+    if (!fm)
+        return [`${bundle.name}/SKILL.md has no frontmatter: open it with a --- block carrying name and description.`];
+    const problems = [];
+    if (!fm.name)
+        problems.push(`${bundle.name}/SKILL.md frontmatter has no name.`);
+    else if (fm.name !== bundle.name)
+        problems.push(`${bundle.name}/SKILL.md frontmatter name '${fm.name}' differs from its folder name '${bundle.name}'.`);
+    if (!fm.description)
+        problems.push(`${bundle.name}/SKILL.md frontmatter has no description.`);
+    else if (fm.description.length > SKILL_DESCRIPTION_MAX)
+        problems.push(`${bundle.name}/SKILL.md description is ${fm.description.length} characters; the limit is ${SKILL_DESCRIPTION_MAX}.`);
+    return problems;
+}
+/**
+ * Throws every {@link skillFrontmatterProblems} finding, followed by the exact
+ * block to write, with the folder name filled in: a skill that pushed fine
+ * before this check existed is fixed with one edit.
+ */
+export function validateSkillFrontmatter(bundle) {
+    const problems = skillFrontmatterProblems(bundle);
+    if (!problems.length)
+        return;
+    const file = bundle.files.find(f => f.path === "SKILL.md");
+    const hasBlock = !!file && readSkillFrontmatter(Buffer.from(file.contentBase64, "base64").toString("utf8")) !== null;
+    throw new Error([
+        ...problems,
+        hasBlock
+            ? `Its frontmatter block must carry these two fields (keep any others):`
+            : `Add this at the very top of ${bundle.name}/SKILL.md:`,
+        "",
+        ...(hasBlock ? [] : ["---"]),
+        `name: ${bundle.name}`,
+        `description: Use when <the situation this skill is for>. Skip when <when it is not>.`,
+        ...(hasBlock ? [] : ["---"]),
+        "",
+        `name must equal the folder name; description is one line of at most ${SKILL_DESCRIPTION_MAX} characters.`,
+    ].join("\n"));
+}
 export async function readSkillBundle(directory, name = basename(resolve(directory))) {
     validateSkillName(name);
     if ((await lstat(directory)).isSymbolicLink())
@@ -99,38 +191,13 @@ export async function readSkillBundle(directory, name = basename(resolve(directo
     validateSkillBundle(bundle);
     return bundle;
 }
-export async function scanLocalSkills(roots = [join(homedir(), ".agents/skills"), join(homedir(), ".codex/skills"), join(homedir(), ".claude/skills")]) {
-    const results = [];
-    for (const root of roots) {
-        let entries;
-        try {
-            entries = await readdir(root, { withFileTypes: true });
-        }
-        catch (e) {
-            if (e.code === "ENOENT")
-                continue;
-            throw e;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name.startsWith("."))
-                continue;
-            const path = join(root, entry.name);
-            try {
-                await lstat(join(path, "SKILL.md"));
-            }
-            catch {
-                continue;
-            }
-            try {
-                const bundle = await readSkillBundle(path);
-                results.push({ path, name: bundle.name, hash: bundle.hash });
-            }
-            catch (e) {
-                results.push({ path, name: entry.name, error: e instanceof Error ? e.message : String(e) });
-            }
-        }
-    }
-    return results;
+/** Legacy array API; the shared discovery engine owns all traversal. */
+export async function scanLocalSkills(roots) {
+    const { discoverSkills } = await import("./skill-discovery.js");
+    const result = await discoverSkills(roots?.map(path => ({ path, label: "Chosen folder", depth: 4 })));
+    if (result.warnings.length)
+        throw new Error(result.warnings.join("\n"));
+    return result.skills;
 }
 export function diffSkillBundles(local, incoming) {
     validateSkillBundle(local);
@@ -147,10 +214,24 @@ export function diffSkillBundles(local, incoming) {
     });
 }
 function recordPath(destination) { return join(dirname(destination), `.${basename(destination)}.sfora-install.json`); }
-async function readInstallation(destination) {
+export async function readInstallation(destination) {
     try {
-        const record = JSON.parse(await readFile(recordPath(destination), "utf8"));
-        if (record.schemaVersion !== 1 || record.path !== destination)
+        const handle = await open(recordPath(destination), constants.O_RDONLY | constants.O_NOFOLLOW);
+        let raw;
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.size > 65536)
+                throw new Error('Invalid installation record file.');
+            raw = await handle.readFile('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+        const record = JSON.parse(raw);
+        if (record.schemaVersion !== 1 || record.path !== destination || record.name !== basename(destination)
+            || !/^[a-f0-9]{64}$/.test(record.hash) || !Number.isSafeInteger(record.installedAt) || record.installedAt < 0
+            || (record.source !== undefined && (typeof record.source !== 'string' || record.source.length > 8192))
+            || (record.sourceVersion !== undefined && (!Number.isSafeInteger(record.sourceVersion) || record.sourceVersion < 1)))
             throw new Error("Unsupported or mismatched installation record.");
         return record;
     }
@@ -160,6 +241,30 @@ async function readInstallation(destination) {
         throw e;
     }
 }
+/** A receipt is historical intent. Classify today's filesystem object before trusting it. */
+export async function inspectSkillTarget(directory) {
+    try {
+        const destination = join(await realpath(dirname(resolve(directory))), basename(directory));
+        const info = await lstat(destination).catch(e => { if (e.code === 'ENOENT')
+            return null; throw e; });
+        if (!info)
+            return { state: 'missing', ownership: 'unknown' };
+        if (info.isSymbolicLink())
+            return { state: 'link', ownership: 'unmanaged', reason: 'A link cannot be replaced using a copy installation receipt.' };
+        if (!info.isDirectory())
+            return { state: 'file', ownership: 'unmanaged', reason: 'The target is no longer a skill directory.' };
+        const bundle = await readSkillBundle(destination);
+        const receipt = await readInstallation(destination);
+        if (!receipt)
+            return { state: 'unmanaged', ownership: 'unmanaged', hash: bundle.hash };
+        if (receipt.hash !== bundle.hash)
+            return { state: 'modified', ownership: 'unmanaged', hash: bundle.hash, receipt, reason: 'The managed copy has local changes.' };
+        return { state: 'managed', ownership: 'managed', hash: bundle.hash, receipt };
+    }
+    catch (error) {
+        return { state: 'unavailable', ownership: 'unknown', reason: error.message };
+    }
+}
 export async function installSkillBundle(bundle, targetRoot, source, sourceVersion) {
     validateSkillBundle(bundle);
     if (sourceVersion !== undefined && (!Number.isSafeInteger(sourceVersion) || sourceVersion < 1))

package/dist/mcp-description.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `bash` tool's description for a cloud workspace, shared by the npm stdio
+ * server (`sfora --mcp`) and the hosted one (the app's POST /mcp), which run
+ * the same shell (card #811: the two had drifted, and the hosted text taught a
+ * board column that does not exist). Only what persists differs: the stdio
+ * server keeps one shell, so cwd and env carry over; each hosted call is a
+ * fresh shell at `/`.
+ */
+export declare function cloudToolDescription({ stateless }: {
+    stateless: boolean;
+}): string;

package/dist/mcp-description.js

@@ -0,0 +1,29 @@
+/**
+ * The `bash` tool's description for a cloud workspace, shared by the npm stdio
+ * server (`sfora --mcp`) and the hosted one (the app's POST /mcp), which run
+ * the same shell (card #811: the two had drifted, and the hosted text taught a
+ * board column that does not exist). Only what persists differs: the stdio
+ * server keeps one shell, so cwd and env carry over; each hosted call is a
+ * fresh shell at `/`.
+ */
+export function cloudToolDescription({ stateless }) {
+    const persistence = stateless
+        ? "Calls are stateless — always use absolute paths."
+        : "cwd and environment persist across calls.";
+    return `Run a bash command against the sfora workspace — a Unix-style view where every post, task, and doc is a markdown file:
+  - /projects/<slug>/posts/<file>.md            published posts
+  - /projects/<slug>/drafts/<file>.md           your drafts
+  - /projects/<slug>/board/<NN-stage>/<NNNN>.md tasks (kanban cards), by stage
+  - /projects/<slug>/library/documents/<file>.md workspace documents (writable)
+  - /projects/<slug>/library/files/<file>        uploaded files (read-only)
+  - /projects/<slug>/library/repositories/<repo> project source trees (read-only)
+  - /projects/<slug>/pulls/<number>.md          pull requests (diff + linked work), read-only
+  - /projects/<slug>/plan.md                    the goal + open questions (write to set the goal)
+  - /projects/<slug>/asks.md                    coordination asks, read-only
+  - /inbox/mentions.md                          unread mentions
+  - /me/api-key                                 your identity
+Every board is the same four fixed columns — 01-triage / 02-todo / 03-in-progress / 04-done. There is no column management; move a card into 04-done to close it. Question cards (kind: question) map their stage to the plan: triage = fuzzy, todo = up for grabs, in-progress = claimed, done = decided.
+Examples: 'ls /projects', 'cat /projects/web/board/02-todo/*.md', 'grep -ri TODO /projects', 'echo "# Fix login\\nstatus: active" > /projects/web/board/02-todo/fix.md', 'mv /projects/web/board/02-todo/0003-*.md /projects/web/board/04-done/'.
+Write a file to create or update the entity (frontmatter sets fields like status/priority/assignees/due). ${persistence}
+Chat: 'typing <room> [--for <secs>]' shows the room you are working on a reply (agents; 30s by default, run again to extend); it ends when you send there, or with 'typing <room> --stop'.`;
+}

package/dist/mcp-server.d.ts

@@ -1,5 +1,7 @@
 /**
- * MCP stdio server exposing a single `bash` tool. Each tool call runs the
+ * MCP stdio server exposing a `bash` tool — plus, against the cloud, the
+ * `attachments` list and `attachment` fetch (card #822), which return a post's
+ * images as image content a vision client can see. Each bash call runs the
  * command through one persistent {@link createSforaShell} instance, with cwd/env
  * carried across calls (just-bash doesn't persist them itself), so an agent's
  * `cd` and `export` survive between tool invocations.
@@ -15,4 +17,6 @@ export interface RunMcpServerOptions {
     /** Terminal client slug for write attribution (`X-Sfora-Client`). */
     clientLabel?: string;
 }
+/** The shell the server runs commands in. Exported for the transport-header test (card #815). */
+export declare function createMcpShell(options: RunMcpServerOptions): import("./index.js").SforaShell | import("./index.js").LocalShell;
 export declare function runMcpServer(options: RunMcpServerOptions): Promise<void>;

package/dist/mcp-server.js

@@ -1,5 +1,7 @@
 /**
- * MCP stdio server exposing a single `bash` tool. Each tool call runs the
+ * MCP stdio server exposing a `bash` tool — plus, against the cloud, the
+ * `attachments` list and `attachment` fetch (card #822), which return a post's
+ * images as image content a vision client can see. Each bash call runs the
  * command through one persistent {@link createSforaShell} instance, with cwd/env
  * carried across calls (just-bash doesn't persist them itself), so an agent's
  * `cd` and `export` survive between tool invocations.
@@ -10,21 +12,10 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { createSforaShell, createLocalShell } from "./index.js";
-const TOOL_DESCRIPTION = `Run a bash command against the sfora workspace — a Unix-style view where every post, task, and doc is a markdown file:
-  - /projects/<slug>/posts/<file>.md            published posts
-  - /projects/<slug>/drafts/<file>.md           your drafts
-  - /projects/<slug>/board/<NN-stage>/<NNNN>.md tasks (kanban cards), by stage
-  - /projects/<slug>/library/documents/<file>.md workspace documents (writable)
-  - /projects/<slug>/library/files/<file>        uploaded files (read-only)
-  - /projects/<slug>/library/repositories/<repo> project source trees (read-only)
-  - /projects/<slug>/pulls/<number>.md          pull requests (diff + linked work), read-only
-  - /projects/<slug>/plan.md                    the goal + open questions (write to set the goal)
-  - /projects/<slug>/asks.md                    coordination asks, read-only
-  - /inbox/mentions.md                          unread mentions
-  - /me/api-key                                 your identity
-Every board is the same four fixed columns — 01-triage / 02-todo / 03-in-progress / 04-done. There is no column management; move a card into 04-done to close it. Question cards (kind: question) map their stage to the plan: triage = fuzzy, todo = up for grabs, in-progress = claimed, done = decided.
-Examples: 'ls /projects', 'cat /projects/web/board/02-todo/*.md', 'grep -ri TODO /projects', 'echo "# Fix login\\nstatus: active" > /projects/web/board/02-todo/fix.md', 'mv /projects/web/board/02-todo/0003-*.md /projects/web/board/04-done/'.
-Write a file to create or update the entity (frontmatter sets fields like status/priority/assignees/due). cwd and environment persist across calls.`;
+import { ATTACHMENT_TOOLS, attachmentToolResult, isAttachmentTool } from "./attachments.js";
+import { cloudToolDescription } from "./mcp-description.js";
+// The cloud description is shared with the hosted /mcp route (card #811).
+const TOOL_DESCRIPTION = cloudToolDescription({ stateless: false });
 const LOCAL_TOOL_DESCRIPTION = `Run a bash command against the local sfora workspace (a .sfora/ directory of plain markdown files, git-versioned with the repo):
   - /board/<NN-stage>/<NNNN>-<slug>.md tasks (kanban cards), by stage — 'mv' between stage dirs moves a task
   - /posts/<YYYY-MM-DD>-<slug>.md      posts
@@ -32,15 +23,25 @@ const LOCAL_TOOL_DESCRIPTION = `Run a bash command against the local sfora works
 Every board is the same four fixed columns — 01-triage / 02-todo / 03-in-progress / 04-done. There is no column management; moving a card into 04-done marks it done.
 Examples: 'ls /board/02-todo', 'cat /board/02-todo/*.md', 'grep -ri TODO /', 'echo "# Fix login\\nstatus: active" > /board/02-todo/fix-login.md', 'mv /board/02-todo/0003-*.md /board/04-done/'.
 Frontmatter sets task fields (status/priority/labels/assignees/due). cwd and environment persist across calls.`;
-export async function runMcpServer(options) {
-    const { bash } = options.localRoot
+/** The shell the server runs commands in. Exported for the transport-header test (card #815). */
+export function createMcpShell(options) {
+    return options.localRoot
         ? createLocalShell(options.localRoot)
         : createSforaShell({
             baseUrl: options.baseUrl,
             apiKey: options.apiKey,
             org: options.org,
             clientLabel: options.clientLabel,
+            // Card #815 (D11): this server's calls are MCP, not terminal commands.
+            transport: "mcp",
         });
+}
+export async function runMcpServer(options) {
+    // A local workspace has no attachments, so only the cloud shell's client
+    // answers the attachment tools.
+    const shell = createMcpShell(options);
+    const { bash } = shell;
+    const client = "client" in shell ? shell.client : null;
     // Persistent shell state across tool calls.
     let cwd = "/";
     let env;
@@ -61,9 +62,18 @@ export async function runMcpServer(options) {
                     required: ["command"],
                 },
             },
+            ...(client ? ATTACHMENT_TOOLS : []),
         ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (client && isAttachmentTool(request.params.name)) {
+            const args = (request.params.arguments ?? {});
+            return attachmentToolResult(client, {
+                path: args.path,
+                // `attachments` lists; only `attachment` fetches by id.
+                id: request.params.name === "attachment" ? (args.id ?? "") : undefined,
+            });
+        }
         if (request.params.name !== "bash") {
             return {
                 content: [