@jini-ai/vibecoding 0.4.0

package/dist/react/session.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @module react/session
+ *
+ * `VibecodingSession` — the one stateful object this package's React layer adds on top of
+ * `../core`'s `EditTarget` + `EditHistory`. Everything else in `./react` (the hook, the tool
+ * registrations, the presentational components) reads and drives an artifact through this seam
+ * rather than touching `EditTarget`/`EditHistory` directly, for one reason: a tool call arrives
+ * from the chat's execution path, not from a React event handler, so the thing tool handlers call
+ * into cannot be React state — it has to be a plain, subscribable object a `useSyncExternalStore`
+ * hook can also read. This is the same shape React itself recommends for external stores; nothing
+ * here is React-specific, but it lives under `./react` because "chat + preview surface" is exactly
+ * what it exists to support (see this package's README's `./react` row).
+ *
+ * ## Why part content is cached rather than re-read on every render
+ *
+ * `EditTarget.readPart` is a host call — for the `html` target it is cheap (a string slice), but
+ * the port makes no such promise for every target (a filesystem or sandbox-backed host could hit a
+ * network round trip per part). Re-reading every listed part's content on every `refresh()` would
+ * turn "the operator opened the file viewer" into an O(part count) fan-out of host calls, and
+ * nothing here can assume that count stays small — see `../core/target.ts`'s own doc on why
+ * `listParts` is the allowlist, not a bound on its size. So `refresh()` only calls `listParts()`;
+ * content is fetched lazily, per id, through `readPart()`, and cached. Every mutating operation
+ * below (`applyEdits`, `undo`, `redo`, `restoreSnapshot`) already knows the exact before/after
+ * content it just wrote — `../core/apply.ts`'s `ProposedEdit`, `../core/history.ts`'s
+ * `PartChange.before`/`.after` — so the cache is updated from that data directly instead of
+ * re-reading the part it just wrote back from the host.
+ */
+import type { ApplyOutcome, PartId, PartRef, Snapshot } from '../core/types.js';
+import type { EditTarget } from '../core/target.js';
+import { type ProposedEdit } from '../core/apply.js';
+import { type EditHistory, type EditHistoryOptions, type HistoryEntry } from '../core/history.js';
+export interface VibecodingSessionArgs {
+    /** The host's artifact port. See `../core/target.ts`. */
+    readonly target: EditTarget;
+}
+export interface VibecodingSessionOptions {
+    /** Forwarded to `createEditHistory`. See `../core/history.ts`'s `EditHistoryOptions`. */
+    readonly historyOptions?: EditHistoryOptions;
+}
+/**
+ * Immutable, point-in-time read of a session. `getSnapshot()` returns the same object reference
+ * until something actually changes — required for `useSyncExternalStore`, which re-renders a
+ * subscriber whenever the reference it reads changes, not whenever it is merely called again.
+ */
+export interface VibecodingSessionSnapshot {
+    /** `'idle'` until the first `refresh()` resolves; `'error'` reflects the most recent failure, not
+     *  a permanently wedged session — a subsequent successful call returns it to `'ready'`. */
+    readonly status: 'idle' | 'loading' | 'ready' | 'error';
+    /** Every part the host currently advertises, in `EditTarget.listParts()`'s own order. */
+    readonly parts: readonly PartRef[];
+    /** Cached content, keyed by part id. A part absent from this map has not been read yet — see
+     *  this module's doc for why content is lazy rather than eagerly fetched for every part. */
+    readonly partContent: ReadonlyMap<PartId, string>;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    /** The most recent operation's failure message, if any. Cleared by the next successful call. */
+    readonly lastError: string | undefined;
+}
+export interface ApplyEditsResult {
+    readonly outcomes: readonly ApplyOutcome[];
+    /** See `../core/apply.ts`'s `correctionsFor` — the subset a caller feeds back to the model. */
+    readonly corrections: readonly {
+        readonly id: PartId;
+        readonly reason: string;
+    }[];
+}
+export interface VibecodingSession {
+    /** The underlying port, for a caller (or test) that needs it directly — e.g. to read the whole
+     *  document a host-specific target stores, which is outside this generic session's vocabulary. */
+    readonly target: EditTarget;
+    /** The underlying undo/redo stack, for a caller that needs `.entries()` for a history UI. */
+    readonly history: EditHistory;
+    getSnapshot(): VibecodingSessionSnapshot;
+    /** Returns an unsubscribe function; the React hook adapts this object API for React. */
+    subscribe(args: {
+        readonly listener: () => void;
+    }): () => void;
+    /** Re-lists parts from the host. Does not re-read content — see this module's doc. */
+    refresh(): Promise<void>;
+    /** Cached content for `id`, fetching once from the host on first request. */
+    readPart(args: {
+        readonly id: PartId;
+    }): Promise<string>;
+    /** Applies `edits` as one undoable transaction and updates the cache from the edits themselves. */
+    applyEdits(requiredArgs: {
+        readonly edits: readonly ProposedEdit[];
+    }, optionalArgs?: {
+        readonly label?: string;
+    }): Promise<ApplyEditsResult>;
+    undo(): Promise<HistoryEntry | null>;
+    redo(): Promise<HistoryEntry | null>;
+    takeSnapshot(): Promise<Snapshot>;
+    restoreSnapshot(args: {
+        readonly snapshot: Snapshot;
+    }): Promise<HistoryEntry | null>;
+}
+/**
+ * Builds a session over the required `target` port, with its own private `EditHistory`.
+ * History settings belong to the optional second object.
+ *
+ * The returned session starts in `'idle'` with no parts listed — call `refresh()` (or let
+ * `useVibecodingSession` do it on mount) to populate it. Nothing here triggers I/O eagerly, so
+ * constructing a session has no side effect a caller needs to clean up.
+ *
+ * @complexity Construction is O(1). See each method for its own cost.
+ */
+export declare function createVibecodingSession({ target }: VibecodingSessionArgs, options?: VibecodingSessionOptions): VibecodingSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/react/session.js

@@ -0,0 +1,160 @@
+import { applyEdits as applyEditsToTarget, correctionsFor } from '../core/apply.js';
+import { createEditHistory } from '../core/history.js';
+const READY_ERROR = undefined;
+/**
+ * Builds a session over the required `target` port, with its own private `EditHistory`.
+ * History settings belong to the optional second object.
+ *
+ * The returned session starts in `'idle'` with no parts listed — call `refresh()` (or let
+ * `useVibecodingSession` do it on mount) to populate it. Nothing here triggers I/O eagerly, so
+ * constructing a session has no side effect a caller needs to clean up.
+ *
+ * @complexity Construction is O(1). See each method for its own cost.
+ */
+export function createVibecodingSession({ target }, options = {}) {
+    const history = createEditHistory({ target }, options.historyOptions);
+    const listeners = new Set();
+    const partContent = new Map();
+    let current = {
+        status: 'idle',
+        parts: [],
+        partContent,
+        canUndo: history.canUndo(),
+        canRedo: history.canRedo(),
+        lastError: READY_ERROR,
+    };
+    /** Replaces `current` with a fresh object carrying `patch`, then notifies subscribers. A fresh
+     *  `partContent` Map reference is handed out only when the map's contents actually changed
+     *  (callers pass a new Map in `patch` for that case); reusing the same Map reference otherwise
+     *  is what keeps an unrelated status change (e.g. `'loading'` -> `'ready'`) from invalidating a
+     *  component's memoized read of `partContent`. */
+    function commit(patch) {
+        current = { ...current, ...patch };
+        for (const listener of listeners)
+            listener();
+    }
+    /**
+     * Runs `work`, tagging the session `'loading'` -> `'ready'`/`'error'` and always returning
+     * control to the caller — a rejection is recorded as `lastError` AND rethrown, so a component
+     * can render `lastError` passively while a tool handler that needs to fail loudly still can.
+     *
+     * `work` returns its data `patch` alongside its `result` rather than calling `commit` itself, so
+     * the success path here can fold that patch into the SAME commit as the `'ready'` status
+     * transition — one notification per operation instead of two, which matters to a
+     * `useSyncExternalStore` subscriber re-rendering on every commit.
+     */
+    async function run(work) {
+        commit({ status: 'loading' });
+        try {
+            const { result, patch } = await work();
+            commit({ ...patch, status: 'ready', lastError: READY_ERROR });
+            return result;
+        }
+        catch (thrown) {
+            const message = thrown instanceof Error ? thrown.message : String(thrown);
+            commit({ status: 'error', lastError: message });
+            throw thrown;
+        }
+    }
+    /** Mirrors a replayed change in the cache. Undoing creation keeps empty content because the
+     *  target's upsert port has no delete operation; see `../core/history.ts`. */
+    function cacheChange(change, side) {
+        partContent.set(change.id, side === 'after' ? change.after : change.before);
+    }
+    return {
+        target,
+        history,
+        getSnapshot: () => current,
+        subscribe({ listener }) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        refresh: () => run(async () => {
+            const parts = await target.listParts();
+            const known = new Set(parts.map((p) => p.id));
+            // Drop cached content for parts the host no longer lists — stale content for an
+            // unaddressable id would otherwise linger forever with nothing to invalidate it.
+            for (const id of partContent.keys())
+                if (!known.has(id))
+                    partContent.delete(id);
+            return {
+                result: undefined,
+                patch: { parts, partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() },
+            };
+        }),
+        readPart: ({ id }) => run(async () => {
+            const cached = partContent.get(id);
+            if (cached !== undefined)
+                return { result: cached, patch: {} };
+            const content = await target.readPart({ id });
+            partContent.set(id, content);
+            return { result: content, patch: { partContent: new Map(partContent) } };
+        }),
+        applyEdits: ({ edits }, options = {}) => run(async () => {
+            const outcomes = await history.transaction({ work: (recording) => applyEditsToTarget({ target: recording, edits }) }, options);
+            // Outcomes are aligned with proposals, including repeated ids. Matching only by id
+            // would cache the first proposal instead of the last successful write for that part.
+            // This pass is O(edits.length), with no additional reads through the target port.
+            for (const [index, outcome] of outcomes.entries()) {
+                if (outcome.status !== 'applied')
+                    continue;
+                const edit = edits[index];
+                if (edit)
+                    partContent.set(edit.id, edit.content);
+            }
+            const parts = await target.listParts();
+            return {
+                result: { outcomes, corrections: correctionsFor({ outcomes }) },
+                patch: {
+                    parts,
+                    partContent: new Map(partContent),
+                    canUndo: history.canUndo(),
+                    canRedo: history.canRedo(),
+                },
+            };
+        }),
+        undo: () => run(async () => {
+            const entry = await history.undo();
+            if (!entry)
+                return { result: entry, patch: {} };
+            // Undo replays in reverse order. Repeated ids must leave the earliest before value
+            // cached, matching what history wrote to the target.
+            for (const change of [...entry.changes].reverse())
+                cacheChange(change, 'before');
+            return {
+                result: entry,
+                patch: { partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() },
+            };
+        }),
+        redo: () => run(async () => {
+            const entry = await history.redo();
+            if (!entry)
+                return { result: entry, patch: {} };
+            for (const change of entry.changes)
+                cacheChange(change, 'after');
+            return {
+                result: entry,
+                patch: { partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() },
+            };
+        }),
+        takeSnapshot: () => run(async () => ({ result: await target.snapshot(), patch: {} })),
+        restoreSnapshot: ({ snapshot }) => run(async () => {
+            const entry = await history.restore({ snapshot });
+            if (!entry)
+                return { result: entry, patch: {} };
+            for (const change of entry.changes)
+                cacheChange(change, 'after');
+            const parts = await target.listParts();
+            return {
+                result: entry,
+                patch: {
+                    parts,
+                    partContent: new Map(partContent),
+                    canUndo: history.canUndo(),
+                    canRedo: history.canRedo(),
+                },
+            };
+        }),
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/react/tools.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @module react/tools
+ *
+ * Turns one `VibecodingSession` (`./session.js`) into the chat-callable control surface the user's
+ * vision describes: "tools in the vibecoding package that let us control everything from chat."
+ * Every tool here is declared as an `@jini-ai/core` `ToolDescriptor` — the kernel's own
+ * discoverable-tool shape (`id`, `description`, `inputSchema`, `readOnly`, ...) — so a host wires
+ * these into a real `ToolRegistry` and a chat surface enumerates them via `registry.list({})` rather
+ * than importing a hardcoded list of vibecoding-specific function names.
+ *
+ * ## Two ways to run these tools, because `@jini-ai/core`'s registry deliberately hides handlers
+ *
+ * `ToolRegistry` (`@jini-ai/core`) never lets a caller retrieve a registered handler directly —
+ * only `authorizeToolInvocation` can, and that function is exported from `@jini-ai/core/composition`
+ * for `@jini-ai/daemon`'s `ToolExecutor` alone (see that file's own module doc: "the one and only
+ * intended caller"). That is the right boundary for a real backend, but it means a browser host
+ * with no daemon in front of it — the common case for `./react`, a chat surface running client-side
+ * — has no way to actually invoke a tool it just registered.
+ *
+ * So this module exposes two views over the same underlying definitions:
+ *
+ * - {@link createVibecodingToolRegistrations} — real `ToolRegistration`s, ready for
+ *   `registry.register(...)` on any `@jini-ai/core` `ToolRegistry`. This is what makes the tools
+ *   genuinely discoverable and, once a real daemon sits in front of this session, genuinely
+ *   executable through `ToolExecutor`'s authorized path.
+ * - {@link createVibecodingToolRunner} — the same tool ids and descriptors, plus a `run({ toolId, input })`
+ *   a host without a daemon calls directly. This is not a bypass of the registry's authorization
+ *   design: these tools have no principal/run/authorization concept of their own to bypass — every
+ *   one of them acts on a single in-process `VibecodingSession` the host itself already holds, and
+ *   the actual security boundary (which parts are addressable, and whether a proposed edit may
+ *   land) is enforced by `EditTarget.validate` inside `session.applyEdits` regardless of which of
+ *   these two paths reached it. A host that DOES have a daemon and wants centralized authorization
+ *   registers through the first path instead and never calls `run` at all.
+ */
+import { type ToolDescriptor, type ToolPolicy, type ToolRegistration } from '@jini-ai/core';
+import type { VibecodingSession } from './session.js';
+/** Stable tool ids, exported so a host building a catalog (composer menu, MCP tool list, ...) from
+ *  `ToolRegistry.list({})` can still branch on a known id where it needs to (e.g. to route
+ *  `propose_edits`'s result into a "corrections" UI) without restating the string literal. */
+export declare const VIBECODING_TOOL_IDS: {
+    readonly LIST_PARTS: "vibecoding.list_parts";
+    readonly READ_PART: "vibecoding.read_part";
+    readonly PROPOSE_EDITS: "vibecoding.propose_edits";
+    readonly UNDO: "vibecoding.undo";
+    readonly REDO: "vibecoding.redo";
+};
+export interface CreateVibecodingToolRegistrationsOptions {
+    /** Overrides {@link ALLOW_ALWAYS} for every registration this call produces. */
+    readonly policy?: ToolPolicy;
+}
+/** Required port shared by the registration and direct-runner factories. */
+export interface VibecodingToolArgs {
+    readonly session: VibecodingSession;
+}
+/**
+ * Builds `ToolRegistration`s ready for `registry.register(...)` on any `@jini-ai/core`
+ * `ToolRegistry`. This is the "must register there, not be bespoke" seam: a chat surface backed by
+ * a real daemon enumerates these through `registry.list({})` and runs them through
+ * `ToolExecutor`/`authorizeToolInvocation`, never through a hardcoded switch on tool name.
+ *
+ * @param requiredArgs - the artifact session port every tool call acts on.
+ * @param options - see {@link CreateVibecodingToolRegistrationsOptions}.
+ * @returns one `ToolRegistration` per tool in `VIBECODING_TOOL_IDS`, in that constant's order.
+ * @complexity O(1) — five fixed registrations.
+ */
+export declare function createVibecodingToolRegistrations({ session }: VibecodingToolArgs, options?: CreateVibecodingToolRegistrationsOptions): ToolRegistration[];
+export interface VibecodingToolRunner {
+    /** The same descriptors {@link createVibecodingToolRegistrations} would register — a host with no
+     *  `ToolRegistry` in play yet (e.g. building a composer catalog directly) reads this instead of
+     *  standing up a registry purely to call `.list({})` once. */
+    readonly descriptors: readonly ToolDescriptor[];
+    /** Runs one tool by id directly against the bound session. Rejects with `ToolInputError` for a
+     *  malformed `input`, with `RangeError` for an unknown `toolId`, or with whatever `session`'s own
+     *  operation rejects with (see `./session.js`). */
+    run(args: {
+        readonly toolId: string;
+        readonly input: unknown;
+    }): Promise<unknown>;
+}
+/**
+ * The no-daemon path — see this module's doc for why one is needed at all. Builds one runner over
+ * `session` that a browser-only host (no `@jini-ai/daemon` in front of it) can call directly from,
+ * e.g., a composer's `onDiscoverySelect` or a mock chat transport.
+ *
+ * @param requiredArgs - the artifact session port every tool call acts on.
+ * @returns descriptors plus a `run` dispatcher — see {@link VibecodingToolRunner}.
+ * @complexity `run` is O(n) in tool count (currently 5) to resolve `toolId`, then whatever the
+ *  resolved handler costs.
+ */
+export declare function createVibecodingToolRunner({ session }: VibecodingToolArgs): VibecodingToolRunner;
+//# sourceMappingURL=tools.d.ts.map

package/dist/react/tools.js

@@ -0,0 +1,246 @@
+/**
+ * @module react/tools
+ *
+ * Turns one `VibecodingSession` (`./session.js`) into the chat-callable control surface the user's
+ * vision describes: "tools in the vibecoding package that let us control everything from chat."
+ * Every tool here is declared as an `@jini-ai/core` `ToolDescriptor` — the kernel's own
+ * discoverable-tool shape (`id`, `description`, `inputSchema`, `readOnly`, ...) — so a host wires
+ * these into a real `ToolRegistry` and a chat surface enumerates them via `registry.list({})` rather
+ * than importing a hardcoded list of vibecoding-specific function names.
+ *
+ * ## Two ways to run these tools, because `@jini-ai/core`'s registry deliberately hides handlers
+ *
+ * `ToolRegistry` (`@jini-ai/core`) never lets a caller retrieve a registered handler directly —
+ * only `authorizeToolInvocation` can, and that function is exported from `@jini-ai/core/composition`
+ * for `@jini-ai/daemon`'s `ToolExecutor` alone (see that file's own module doc: "the one and only
+ * intended caller"). That is the right boundary for a real backend, but it means a browser host
+ * with no daemon in front of it — the common case for `./react`, a chat surface running client-side
+ * — has no way to actually invoke a tool it just registered.
+ *
+ * So this module exposes two views over the same underlying definitions:
+ *
+ * - {@link createVibecodingToolRegistrations} — real `ToolRegistration`s, ready for
+ *   `registry.register(...)` on any `@jini-ai/core` `ToolRegistry`. This is what makes the tools
+ *   genuinely discoverable and, once a real daemon sits in front of this session, genuinely
+ *   executable through `ToolExecutor`'s authorized path.
+ * - {@link createVibecodingToolRunner} — the same tool ids and descriptors, plus a `run({ toolId, input })`
+ *   a host without a daemon calls directly. This is not a bypass of the registry's authorization
+ *   design: these tools have no principal/run/authorization concept of their own to bypass — every
+ *   one of them acts on a single in-process `VibecodingSession` the host itself already holds, and
+ *   the actual security boundary (which parts are addressable, and whether a proposed edit may
+ *   land) is enforced by `EditTarget.validate` inside `session.applyEdits` regardless of which of
+ *   these two paths reached it. A host that DOES have a daemon and wants centralized authorization
+ *   registers through the first path instead and never calls `run` at all.
+ */
+import { ToolInputError, } from '@jini-ai/core';
+/** Stable tool ids, exported so a host building a catalog (composer menu, MCP tool list, ...) from
+ *  `ToolRegistry.list({})` can still branch on a known id where it needs to (e.g. to route
+ *  `propose_edits`'s result into a "corrections" UI) without restating the string literal. */
+export const VIBECODING_TOOL_IDS = {
+    LIST_PARTS: 'vibecoding.list_parts',
+    READ_PART: 'vibecoding.read_part',
+    PROPOSE_EDITS: 'vibecoding.propose_edits',
+    UNDO: 'vibecoding.undo',
+    REDO: 'vibecoding.redo',
+};
+/** A proposed edit in one `vibecoding.propose_edits` call is capped so a single model turn cannot
+ *  ask this session to rewrite an unbounded number of parts in one transaction — see the
+ *  Programmer pre-check on service-backed collections this module was written against. Chosen
+ *  generously above any realistic single-turn edit count rather than tuned to one; a host needing
+ *  fewer or more can still bound its own model prompt independently. */
+const MAX_EDITS_PER_INVOCATION = 50;
+/** No-argument tools still declare an (empty) object schema rather than omitting `inputSchema`, so
+ *  a model sees explicitly that `{}` is the correct call shape instead of guessing. */
+const EMPTY_INPUT_SCHEMA = { type: 'object', additionalProperties: false };
+const READ_PART_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        id: { type: 'string', description: 'A part id from a prior vibecoding.list_parts call.' },
+    },
+    required: ['id'],
+    additionalProperties: false,
+};
+const PROPOSE_EDITS_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        edits: {
+            type: 'array',
+            minItems: 1,
+            maxItems: MAX_EDITS_PER_INVOCATION,
+            items: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string', description: 'A part id from a prior vibecoding.list_parts call.' },
+                    content: { type: 'string', description: "The part's full replacement content." },
+                },
+                required: ['id', 'content'],
+                additionalProperties: false,
+            },
+        },
+        label: {
+            type: 'string',
+            description: 'Optional human-facing description of this turn, shown in undo history.',
+        },
+    },
+    required: ['edits'],
+    additionalProperties: false,
+};
+/** Narrows `input` to a plain record, the same first check every handler below needs before
+ *  reading a named field out of a value that arrived as `unknown` model-authored JSON. */
+function requireInputRecord(input, toolId) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new ToolInputError({ message: `${toolId}: expected an input object` });
+    }
+    return input;
+}
+function requireString(record, key, toolId) {
+    const value = record[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new ToolInputError({ message: `${toolId}: "${key}" must be a non-empty string` });
+    }
+    return value;
+}
+/** Validates the `edits` array's shape without trusting any of it — `content` may legitimately be
+ *  an empty string (clearing a part), so only `edits` itself and each entry's `id` are non-empty
+ *  checked. */
+function requireProposedEdits(record, toolId) {
+    const raw = record.edits;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new ToolInputError({ message: `${toolId}: "edits" must be a non-empty array` });
+    }
+    if (raw.length > MAX_EDITS_PER_INVOCATION) {
+        throw new ToolInputError({ message: `${toolId}: "edits" carries ${raw.length} entries, over the ${MAX_EDITS_PER_INVOCATION}-entry limit per call` });
+    }
+    return raw.map((entry, index) => {
+        const entryRecord = requireInputRecord(entry, `${toolId}.edits[${index}]`);
+        const id = requireString(entryRecord, 'id', `${toolId}.edits[${index}]`);
+        const content = entryRecord.content;
+        if (typeof content !== 'string') {
+            throw new ToolInputError({ message: `${toolId}.edits[${index}]: "content" must be a string` });
+        }
+        return { id, content };
+    });
+}
+/**
+ * Builds the five tool definitions bound to `session`. Package-private: hosts reach these only
+ * through {@link createVibecodingToolRegistrations} or {@link createVibecodingToolRunner}, which is
+ * what keeps "how a definition is invoked" a single decision made in one of those two places rather
+ * than duplicated per tool.
+ *
+ * @complexity O(1) to build the array; each handler's own cost is documented on its descriptor.
+ */
+function buildVibecodingToolDefinitions(session) {
+    return [
+        {
+            descriptor: {
+                id: VIBECODING_TOOL_IDS.LIST_PARTS,
+                description: 'List every editable part of the artifact currently being authored.',
+                inputSchema: EMPTY_INPUT_SCHEMA,
+                readOnly: true,
+                timeoutMs: 10_000,
+            },
+            handler: async () => {
+                await session.refresh();
+                return session.getSnapshot().parts;
+            },
+        },
+        {
+            descriptor: {
+                id: VIBECODING_TOOL_IDS.READ_PART,
+                description: "Read one part's current content by id.",
+                inputSchema: READ_PART_INPUT_SCHEMA,
+                readOnly: true,
+                timeoutMs: 10_000,
+            },
+            handler: async (input) => {
+                const record = requireInputRecord(input, VIBECODING_TOOL_IDS.READ_PART);
+                const id = requireString(record, 'id', VIBECODING_TOOL_IDS.READ_PART);
+                return { id, content: await session.readPart({ id }) };
+            },
+        },
+        {
+            descriptor: {
+                id: VIBECODING_TOOL_IDS.PROPOSE_EDITS,
+                description: 'Propose replacement content for one or more parts, as a single undoable turn. Each edit ' +
+                    'is validated before anything is written; a rejected edit leaves the artifact untouched ' +
+                    'and its reason is returned for the next turn.',
+                inputSchema: PROPOSE_EDITS_INPUT_SCHEMA,
+                readOnly: false,
+                timeoutMs: 15_000,
+            },
+            handler: async (input) => {
+                const record = requireInputRecord(input, VIBECODING_TOOL_IDS.PROPOSE_EDITS);
+                const edits = requireProposedEdits(record, VIBECODING_TOOL_IDS.PROPOSE_EDITS);
+                const label = record.label === undefined ? undefined : requireString(record, 'label', VIBECODING_TOOL_IDS.PROPOSE_EDITS);
+                return session.applyEdits({ edits }, label === undefined ? {} : { label });
+            },
+        },
+        {
+            descriptor: {
+                id: VIBECODING_TOOL_IDS.UNDO,
+                description: 'Revert the most recent proposed-edits turn.',
+                inputSchema: EMPTY_INPUT_SCHEMA,
+                readOnly: false,
+                timeoutMs: 10_000,
+            },
+            handler: async () => ({ entry: await session.undo() }),
+        },
+        {
+            descriptor: {
+                id: VIBECODING_TOOL_IDS.REDO,
+                description: 'Re-apply the most recently undone turn.',
+                inputSchema: EMPTY_INPUT_SCHEMA,
+                readOnly: false,
+                timeoutMs: 10_000,
+            },
+            handler: async () => ({ entry: await session.redo() }),
+        },
+    ];
+}
+/** Grants every call — see this module's doc for why tool-level authorization has nothing to add
+ *  beyond `EditTarget.validate`'s own allowlist check for a session with no principal concept of
+ *  its own. A host with per-principal restrictions passes its own `ToolPolicy` via
+ *  `createVibecodingToolRegistrations`'s `options.policy` instead of relying on this default. */
+const ALLOW_ALWAYS = { authorize: () => 'allow' };
+/**
+ * Builds `ToolRegistration`s ready for `registry.register(...)` on any `@jini-ai/core`
+ * `ToolRegistry`. This is the "must register there, not be bespoke" seam: a chat surface backed by
+ * a real daemon enumerates these through `registry.list({})` and runs them through
+ * `ToolExecutor`/`authorizeToolInvocation`, never through a hardcoded switch on tool name.
+ *
+ * @param requiredArgs - the artifact session port every tool call acts on.
+ * @param options - see {@link CreateVibecodingToolRegistrationsOptions}.
+ * @returns one `ToolRegistration` per tool in `VIBECODING_TOOL_IDS`, in that constant's order.
+ * @complexity O(1) — five fixed registrations.
+ */
+export function createVibecodingToolRegistrations({ session }, options = {}) {
+    const policy = options.policy ?? ALLOW_ALWAYS;
+    return buildVibecodingToolDefinitions(session).map(({ descriptor, handler }) => ({
+        descriptor,
+        policy,
+        handler: (ctx) => handler(ctx.input),
+    }));
+}
+/**
+ * The no-daemon path — see this module's doc for why one is needed at all. Builds one runner over
+ * `session` that a browser-only host (no `@jini-ai/daemon` in front of it) can call directly from,
+ * e.g., a composer's `onDiscoverySelect` or a mock chat transport.
+ *
+ * @param requiredArgs - the artifact session port every tool call acts on.
+ * @returns descriptors plus a `run` dispatcher — see {@link VibecodingToolRunner}.
+ * @complexity `run` is O(n) in tool count (currently 5) to resolve `toolId`, then whatever the
+ *  resolved handler costs.
+ */
+export function createVibecodingToolRunner({ session }) {
+    const definitions = buildVibecodingToolDefinitions(session);
+    return {
+        descriptors: definitions.map((d) => d.descriptor),
+        async run({ toolId, input }) {
+            const definition = definitions.find((d) => d.descriptor.id === toolId);
+            if (!definition)
+                throw new RangeError(`no vibecoding tool registered with id "${toolId}"`);
+            return definition.handler(input);
+        },
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/react/use-vibecoding-session.d.ts

@@ -0,0 +1,30 @@
+import type { VibecodingSession, VibecodingSessionSnapshot } from './session.js';
+export interface UseVibecodingSessionArgs {
+    readonly session: VibecodingSession;
+}
+export interface UseVibecodingSessionResult extends VibecodingSessionSnapshot {
+    readonly session: VibecodingSession;
+    readonly refresh: () => Promise<void>;
+    readonly readPart: VibecodingSession['readPart'];
+    readonly applyEdits: VibecodingSession['applyEdits'];
+    readonly undo: VibecodingSession['undo'];
+    readonly redo: VibecodingSession['redo'];
+}
+/**
+ * Subscribes to `session` and triggers its first `refresh()` on mount (and again if `session`
+ * itself changes identity — a host swapping in a different artifact mid-session gets a fresh list
+ * rather than a stale one left over from the previous session). Re-running `refresh()` a second
+ * time for the same session instance is the caller's own choice via the returned `refresh`.
+ *
+ * A `refresh()` rejection is intentionally swallowed here rather than thrown from the effect —
+ * `session.getSnapshot().lastError` already carries it (see `./session.js`), and an effect that
+ * threw would only produce an uncatchable render-cycle error for a failure the snapshot already
+ * reports. A caller that wants to react to it reads `lastError` or calls `refresh()` itself and
+ * awaits/catches that promise directly.
+ *
+ * @param requiredArgs - the session port created by `createVibecodingSession`.
+ * @returns the current snapshot plus the session's actions, bound to `session`.
+ * @complexity O(1) beyond whatever `session`'s own methods cost — see `./session.js`.
+ */
+export declare function useVibecodingSession({ session }: UseVibecodingSessionArgs): UseVibecodingSessionResult;
+//# sourceMappingURL=use-vibecoding-session.d.ts.map