@happyvertical/smrt-planner 0.57.11 → 0.57.13

package/dist/planner/PlannerLifecycle.svelte

@@ -1,7 +1,10 @@
 <script lang="ts">
-import { onMount } from 'svelte';
+import {
+  tryUseAdminShell,
+  tryUseShellTargets,
+} from '@happyvertical/smrt-svelte/workspace';
+import { onMount, tick } from 'svelte';
 import { aiState } from '../ai/instance.js';
-import { browserStorage } from '../cookbook/storage.js';
 import { cookbookStore } from '../cookbook/store.svelte.js';
 import { provideDataSource, tryUseDataSource } from '../data/context.js';
 import { createPlannerDataSource } from '../data/planner-source.js';
@@ -10,8 +13,10 @@ import { libraryState } from '../library/state.svelte.js';
 import { recipeState } from '../recipes/state.svelte.js';
 import { type LinkMode, setBasePath } from './app.svelte.js';
 import { createPlannerAssistant } from './assistant.js';
+import { createPlannerGuide } from './guide.js';
 import { plannerController, plannerRuntime } from './instance.js';
 import type { PlannerProps } from './types.js';
+import { workspaceStorage } from './workspace-storage.js';
 
 let {
   controller = plannerController,
@@ -19,15 +24,29 @@ let {
   inference,
   persistence = 'self',
   onready,
+  initialConversation,
+  cookbookOffers = true,
+  conversationalAction,
+  nativeAssistant = false,
   links = 'path',
 }: Pick<
   PlannerProps,
-  'controller' | 'basePath' | 'inference' | 'persistence' | 'onready'
+  | 'controller'
+  | 'basePath'
+  | 'inference'
+  | 'persistence'
+  | 'onready'
+  | 'initialConversation'
+  | 'cookbookOffers'
+  | 'conversationalAction'
 > & {
+  nativeAssistant?: boolean;
   /** `'hash'` in the complete `Planner`, whose pages are fragment routes. */
   links?: LinkMode;
 } = $props();
 
+const shell = tryUseAdminShell();
+const targets = tryUseShellTargets();
 const dataSource =
   tryUseDataSource() ?? provideDataSource(createPlannerDataSource());
 
@@ -38,11 +57,19 @@ $effect.pre(() => {
 });
 
 onMount(() => {
+  let mounted = true;
+  const guide = nativeAssistant
+    ? createPlannerGuide({
+        targets,
+        isMounted: () => mounted,
+        revealMenu: () => shell?.expandPanel('left'),
+      })
+    : undefined;
   const previous = plannerRuntime.onReplaced;
   plannerRuntime.onReplaced = () => dataSource.reset?.();
   if (persistence === 'self' && !cookbookStore.loaded) {
     libraryState.load();
-    cookbookStore.hydrate('', browserStorage());
+    cookbookStore.hydrate('', workspaceStorage());
   }
   const assistant = inference
     ? createPlannerAssistant(controller, inference)
@@ -57,9 +84,52 @@ onMount(() => {
       recipeState.ids.length > 0 || recipeState.features.length > 0,
     );
   }
-  onready?.({ controller, ...(assistant ? { assistant } : {}) });
+  // Guide lifetime observes the private epoch even without an inference UI.
+  // Only an enabled assistant grants public conversation/export capabilities.
+  const privateNative = nativeAssistant ? aiState.session.transport : undefined;
+  const native = inference ? privateNative : undefined;
+  let nativeEpoch = privateNative?.resetRevision;
+  const stopGuideReset = privateNative?.subscribeConversation(() => {
+    if (privateNative.resetRevision !== nativeEpoch) {
+      nativeEpoch = privateNative.resetRevision;
+      guide?.dismiss();
+    }
+  });
+  const previousOffers = aiState.session.cookbookOffers;
+  const previousHostTurn = aiState.session.hostTurn;
+  if (native) {
+    aiState.session.cookbookOffers = cookbookOffers;
+    aiState.session.hostTurn = conversationalAction;
+    if (initialConversation) native.seed(initialConversation);
+  }
+  onready?.({
+    controller,
+    ...(guide ? { guide } : {}),
+    workspaceStorage: workspaceStorage(),
+    ...(assistant ? { assistant } : {}),
+    ...(native
+      ? {
+          nativeAssistant: native,
+          openAssistant: async () => {
+            await tick();
+            return (
+              mounted &&
+              aiState.assistantReady &&
+              (shell?.openDockTool('assistant') ?? false)
+            );
+          },
+        }
+      : {}),
+  });
   return () => {
+    mounted = false;
+    guide?.dismiss();
+    stopGuideReset?.();
     plannerRuntime.onReplaced = previous;
+    if (native) {
+      aiState.session.cookbookOffers = previousOffers;
+      aiState.session.hostTurn = previousHostTurn;
+    }
   };
 });
 

package/dist/planner/PlannerLifecycle.svelte.d.ts

@@ -1,6 +1,7 @@
 import { type LinkMode } from './app.svelte.ts';
 import type { PlannerProps } from './types.ts';
-type $$ComponentProps = Pick<PlannerProps, 'controller' | 'basePath' | 'inference' | 'persistence' | 'onready'> & {
+type $$ComponentProps = Pick<PlannerProps, 'controller' | 'basePath' | 'inference' | 'persistence' | 'onready' | 'initialConversation' | 'cookbookOffers' | 'conversationalAction'> & {
+    nativeAssistant?: boolean;
     /** `'hash'` in the complete `Planner`, whose pages are fragment routes. */
     links?: LinkMode;
 };

package/dist/planner/PlannerLifecycle.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlannerLifecycle.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/planner/PlannerLifecycle.svelte.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,QAAQ,EAAe,MAAM,iBAAiB,CAAC;AAG7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9C,KAAK,gBAAgB,GAAI,IAAI,CAC5B,YAAY,EACZ,YAAY,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,CACpE,GAAG;IACF,2EAA2E;IAC3E,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB,CAAC;AAuEF,QAAA,MAAM,gBAAgB,sDAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"PlannerLifecycle.svelte.d.ts","sourceRoot":"","sources":["../../src/lib/planner/PlannerLifecycle.svelte.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,QAAQ,EAAe,MAAM,iBAAiB,CAAC;AAI7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG9C,KAAK,gBAAgB,GAAI,IAAI,CAC5B,YAAY,EACV,YAAY,GACZ,UAAU,GACV,WAAW,GACX,aAAa,GACb,SAAS,GACT,qBAAqB,GACrB,gBAAgB,GAChB,sBAAsB,CACzB,GAAG;IACF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB,CAAC;AAkIF,QAAA,MAAM,gBAAgB,sDAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}

package/dist/planner/bridge.d.ts

@@ -0,0 +1,73 @@
+import { type PromptCatalog } from '../core/catalog.ts';
+import type { BatchResult, CommandName, PlannerController, PlanSnapshot } from './commands/index.ts';
+import { type CommandTool } from './commands/schemas.ts';
+import type { PlannerGuideControl, PlannerGuideHandle, PlannerGuideResult } from './guide.ts';
+export interface PlannerBridgeSnapshot {
+    generation: string;
+    snapshot: PlanSnapshot;
+}
+export interface PlannerBridgeContext extends PlannerBridgeSnapshot {
+    catalog: PromptCatalog;
+    tools: readonly CommandTool[];
+}
+export interface PlannerBridgeRequest {
+    id: string;
+    generation: string;
+    expectedRevision: number;
+}
+export interface PlannerBridgeExecute extends PlannerBridgeRequest {
+    commands: readonly {
+        name: string;
+        input: unknown;
+    }[];
+}
+export interface PlannerBridgeApplyReply extends PlannerBridgeRequest {
+    reply: unknown;
+}
+export type PlannerBridgeResult = PlannerBridgeSnapshot & {
+    ok: boolean;
+    source: string;
+    id?: string;
+    result?: BatchResult;
+    content?: string;
+    spokenContent?: string;
+    sampleContextApplied?: boolean;
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+export interface PlannerCommandPortClient {
+    snapshot(): Promise<PlannerBridgeSnapshot>;
+    context(): Promise<PlannerBridgeContext>;
+    subscribe(listener: (state: PlannerBridgeSnapshot) => void): () => void;
+    execute(input: PlannerBridgeExecute): Promise<PlannerBridgeResult>;
+    applyReply(input: PlannerBridgeApplyReply): Promise<PlannerBridgeResult>;
+    guide(input: {
+        generation: string;
+        kind: 'arrival' | 'addition' | 'control';
+        control?: PlannerGuideControl;
+        requestId?: string;
+    }): Promise<PlannerGuideResult>;
+    dismissGuide(input: {
+        generation: string;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    dispose(): void;
+}
+/** Bind a dedicated, already-authorized port to the actual mounted controller. */
+export declare function bindPlannerCommandPort(options: {
+    port: MessagePort;
+    controller: PlannerController;
+    allowedCommands: readonly CommandName[];
+    /** Host-assigned provenance; never accepted from a model/request. */
+    source: string;
+    guide?: PlannerGuideHandle;
+}): {
+    invalidate(): void;
+    dispose(): void;
+};
+/** Client for a dedicated port; the host owns exact origin/source handshake checks. */
+export declare function connectPlannerCommandPort(port: MessagePort): PlannerCommandPortClient;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/planner/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/lib/planner/bridge.ts"],"names":[],"mappings":"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"}

package/dist/planner/bridge.js

@@ -0,0 +1,303 @@
+import { defaultCatalog } from "../core/catalog.js";
+import { COMMAND_NAMES, commandTools, } from "./commands/schemas.js";
+import { applyPlannerHostReply } from "./host-reply.js";
+const PROTOCOL = 'smrt-planner-commands';
+const VERSION = 1;
+const MAX_BYTES = 32768;
+const MAX_COMMANDS = 16;
+const MAX_RECEIPTS = 256;
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** Bind a dedicated, already-authorized port to the actual mounted controller. */
+export function bindPlannerCommandPort(options) {
+    const { port, controller, source } = options;
+    if (!source ||
+        source.length > 128 ||
+        options.allowedCommands.some((name) => !COMMAND_NAMES.includes(name)))
+        throw new Error('Invalid Planner command port policy.');
+    const allowed = new Set(options.allowedCommands);
+    let generation = crypto.randomUUID();
+    let disposed = false;
+    const receipts = new Map();
+    const state = () => ({
+        generation,
+        snapshot: controller.snapshot(),
+    });
+    const send = (message) => {
+        if (!disposed)
+            port.postMessage({
+                protocol: PROTOCOL,
+                version: VERSION,
+                ...message,
+            });
+    };
+    const fail = (code, message, id) => ({
+        ...state(),
+        ok: false,
+        source,
+        ...(id ? { id } : {}),
+        error: { code, message },
+        content: message,
+    });
+    function execute(raw, mode) {
+        if (!object(raw) ||
+            Object.keys(raw).some((key) => ![
+                'id',
+                'generation',
+                'expectedRevision',
+                mode === 'execute' ? 'commands' : 'reply',
+            ].includes(key)) ||
+            typeof raw.id !== 'string' ||
+            !raw.id ||
+            raw.id.length > 128 ||
+            typeof raw.generation !== 'string' ||
+            !Number.isSafeInteger(raw.expectedRevision) ||
+            Number(raw.expectedRevision) < 0)
+            return fail('invalid_input', 'Invalid Planner command envelope.');
+        const id = raw.id;
+        if (raw.generation !== generation)
+            return fail('stale_generation', 'This request belongs to an earlier Planner workspace.', id);
+        const fingerprint = JSON.stringify({ mode, ...raw });
+        const cached = receipts.get(id);
+        if (cached)
+            return cached.fingerprint === fingerprint
+                ? structuredClone(cached.value)
+                : fail('conflict', 'This request id was already used for different input.', id);
+        if (receipts.size >= MAX_RECEIPTS)
+            return fail('limit_reached', 'This command connection has reached its receipt limit. Reconnect before continuing.', id);
+        const before = controller.snapshot();
+        let value;
+        const commandId = `${generation}:${id}`;
+        if (mode === 'applyReply') {
+            const applied = applyPlannerHostReply({
+                controller,
+                allowedCommands: [...allowed],
+                id: commandId,
+                expectedRevision: raw.expectedRevision,
+                reply: raw.reply,
+            });
+            value = { ...state(), source, id, ...applied };
+        }
+        else {
+            const commands = raw.commands;
+            if (!Array.isArray(commands) ||
+                commands.length === 0 ||
+                commands.length > MAX_COMMANDS ||
+                commands.some((command) => !object(command) ||
+                    Object.keys(command).some((key) => !['name', 'input'].includes(key)) ||
+                    typeof command.name !== 'string' ||
+                    !allowed.has(command.name)))
+                return fail('forbidden', 'The request contains a command this host does not allow.', id);
+            const result = controller.batch({
+                id: commandId,
+                expectedRevision: raw.expectedRevision,
+                commands,
+            });
+            value = {
+                ...state(),
+                source,
+                id,
+                ok: result.ok,
+                result,
+                ...(!result.ok
+                    ? { error: result.error, content: result.error.message }
+                    : {}),
+            };
+        }
+        receipts.set(id, { fingerprint, value: structuredClone(value), before });
+        return value;
+    }
+    const listener = async (event) => {
+        const raw = event.data;
+        if (disposed ||
+            !object(raw) ||
+            raw.protocol !== PROTOCOL ||
+            !Number.isSafeInteger(raw.requestId))
+            return;
+        let value;
+        const requestGeneration = generation;
+        try {
+            if (new TextEncoder().encode(JSON.stringify(raw)).length > MAX_BYTES)
+                value = fail('invalid_input', 'Planner command message is too large.');
+            else if (raw.version !== VERSION)
+                value = fail('unsupported_version', 'Unsupported Planner command protocol.');
+            else if (raw.type === 'snapshot')
+                value = state();
+            else if (raw.type === 'context')
+                value = { ...state(), catalog: defaultCatalog, tools: commandTools };
+            else if (raw.type === 'guide') {
+                const input = raw.input;
+                if (!object(input) ||
+                    Object.keys(input).some((key) => !['generation', 'kind', 'requestId', 'control'].includes(key)) ||
+                    input.generation !== generation ||
+                    !['arrival', 'addition', 'control'].includes(String(input.kind)) ||
+                    (input.kind === 'control' &&
+                        !['build', 'export', 'chef', 'edit'].includes(String(input.control))) ||
+                    (input.kind !== 'control' && input.control !== undefined) ||
+                    !options.guide)
+                    value = {
+                        ok: false,
+                        reason: 'Guidance is unavailable for this workspace.',
+                    };
+                else if (input.kind === 'control')
+                    value = await options.guide.highlight({
+                        kind: 'control',
+                        control: input.control,
+                    });
+                else if (input.kind === 'arrival')
+                    value = await options.guide.highlight({ kind: 'arrival' });
+                else {
+                    const receipt = typeof input.requestId === 'string'
+                        ? receipts.get(input.requestId)
+                        : undefined;
+                    if (!receipt?.value.ok ||
+                        !receipt.value.result?.ok ||
+                        receipt.guided ||
+                        receipt.value.snapshot.revision !== controller.snapshot().revision)
+                        value = {
+                            ok: false,
+                            reason: 'No current unshown successful addition receipt is available.',
+                        };
+                    else {
+                        value = await options.guide.highlight({
+                            kind: 'addition',
+                            before: receipt.before,
+                            result: receipt.value.result,
+                        });
+                        if (value.ok)
+                            receipt.guided = true;
+                    }
+                }
+            }
+            else if (raw.type === 'dismissGuide') {
+                if (object(raw.input) && raw.input.generation === generation) {
+                    options.guide?.dismiss();
+                    value = { ok: true };
+                }
+                else
+                    value = { ok: false };
+            }
+            else if (raw.type === 'execute' || raw.type === 'applyReply')
+                value = execute(raw.input, raw.type);
+            else
+                value = fail('invalid_input', 'Unknown Planner command operation.');
+        }
+        catch {
+            value = fail('invalid_input', 'The Planner command could not be processed.');
+        }
+        if (raw.type === 'guide' && requestGeneration !== generation)
+            value = {
+                ok: false,
+                reason: 'The workspace changed before guidance was ready.',
+            };
+        send({ type: 'response', requestId: raw.requestId, value });
+    };
+    port.addEventListener('message', listener);
+    port.start();
+    const unsubscribe = controller.subscribe((snapshot) => send({ type: 'state', value: { generation, snapshot } }));
+    return {
+        invalidate() {
+            if (disposed)
+                return;
+            generation = crypto.randomUUID();
+            receipts.clear();
+            options.guide?.dismiss();
+            send({ type: 'state', value: state() });
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            options.guide?.dismiss();
+            unsubscribe();
+            port.removeEventListener('message', listener);
+            port.close();
+            receipts.clear();
+        },
+    };
+}
+/** Client for a dedicated port; the host owns exact origin/source handshake checks. */
+export function connectPlannerCommandPort(port) {
+    let next = 0;
+    let disposed = false;
+    let current;
+    const listeners = new Set();
+    const pending = new Map();
+    const listener = (event) => {
+        const message = event.data;
+        if (disposed ||
+            !object(message) ||
+            message.protocol !== PROTOCOL ||
+            message.version !== VERSION)
+            return;
+        if (message.type === 'response' && typeof message.requestId === 'number') {
+            const call = pending.get(message.requestId);
+            if (!call)
+                return;
+            clearTimeout(call.timer);
+            pending.delete(message.requestId);
+            call.resolve(message.value);
+        }
+        else if (message.type === 'state' && object(message.value)) {
+            current = message.value;
+            for (const subscriber of listeners)
+                subscriber(structuredClone(current));
+        }
+    };
+    port.addEventListener('message', listener);
+    port.start();
+    const request = (type, input) => {
+        if (disposed)
+            return Promise.reject(new Error('Planner command connection is disposed.'));
+        if (pending.size >= 32)
+            return Promise.reject(new Error('Too many pending Planner commands.'));
+        return new Promise((resolve, reject) => {
+            const requestId = ++next;
+            const timer = setTimeout(() => {
+                pending.delete(requestId);
+                reject(new Error('Planner command connection timed out.'));
+            }, 10000);
+            pending.set(requestId, { resolve, reject, timer });
+            try {
+                port.postMessage({
+                    protocol: PROTOCOL,
+                    version: VERSION,
+                    requestId,
+                    type,
+                    ...(input === undefined ? {} : { input }),
+                });
+            }
+            catch (error) {
+                clearTimeout(timer);
+                pending.delete(requestId);
+                reject(error);
+            }
+        });
+    };
+    return {
+        snapshot: () => request('snapshot'),
+        context: () => request('context'),
+        execute: (input) => request('execute', input),
+        applyReply: (input) => request('applyReply', input),
+        guide: (input) => request('guide', input),
+        dismissGuide: (input) => request('dismissGuide', input),
+        subscribe(subscriber) {
+            listeners.add(subscriber);
+            if (current)
+                subscriber(structuredClone(current));
+            return () => listeners.delete(subscriber);
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            port.removeEventListener('message', listener);
+            port.close();
+            listeners.clear();
+            for (const call of pending.values()) {
+                clearTimeout(call.timer);
+                call.reject(new Error('Planner command connection is disposed.'));
+            }
+            pending.clear();
+        },
+    };
+}

package/dist/planner/commands/adapter.d.ts

@@ -70,6 +70,8 @@ export interface AdapterEnv {
  * all drive the app through this one seam.
  */
 export interface PlannerController {
+    /** Forget project command history after an explicit workspace reset. */
+    resetWorkspace?(): void;
     /**
      * Run one command. Never throws: a bad command, unknown id or refused edit
      * comes back as `{ ok: false, error }` and leaves the app unchanged.

package/dist/planner/commands/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/lib/planner/commands/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/lib/planner/commands/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EAGnB,KAAK,aAAa,EAElB,KAAK,WAAW,EAEjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAe,QAAQ,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EACL,KAAK,WAAW,EAGhB,KAAK,aAAa,EAElB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAmBpB,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,MAAM,IAAI,YAAY,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;IAChC,oEAAoE;IACpE,UAAU,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,IAAI,CAAC,IAAI,OAAO,CAAC;IACjB,+EAA+E;IAC/E,OAAO,CAAC,IAAI,MAAM,GAAG,IAAI,CAAC;IAC1B,sEAAsE;IACtE,KAAK,CAAC,CACJ,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE;QACN,qEAAqE;QACrE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B;;;;WAIG;QACH,QAAQ,EAAE,OAAO,CAAC;QAClB,uEAAuE;QACvE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,2EAA2E;QAC3E,cAAc,EAAE,OAAO,CAAC;KACzB,GACA,IAAI,CAAC;IACR,+EAA+E;IAC/E,aAAa,CAAC,CAAC,QAAQ,EAAE,OAAO,GAAG,cAAc,CAAC;CACnD;AAED,wEAAwE;AACxE,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,GAAG,IAAI,CAAC,CAAC;IACT,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACrB;AAED,oBAAoB;AACpB,wBAAgB,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAQ3C;AAED,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9B,GAAG,CAAC,EAAE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAChC,mFAAmF;IACnF,KAAK,CAAC,EAAE;QAAE,KAAK,IAAI,IAAI,CAAC;QAAC,IAAI,IAAI,IAAI,CAAA;KAAE,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,cAAc,CAAC,IAAI,IAAI,CAAC;IACxB;;;OAGG;IACH,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC;IAClE,2EAA2E;IAC3E,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC;IAC3D;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAAC;IACnC,+CAA+C;IAC/C,QAAQ,IAAI,YAAY,CAAC;IACzB;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACnE;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD,uCAAuC;IACvC,QAAQ,IAAI,QAAQ,CAAC;IACrB,4EAA4E;IAC5E,IAAI,IAAI,aAAa,CAAC;IACtB,sDAAsD;IACtD,KAAK,IAAI,WAAW,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;IAC5C,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC;IAChD;;;OAGG;IACH,OAAO,IAAI,MAAM,CAAC;IAClB,gFAAgF;IAChF,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,aAAa,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AA4BD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,qBAAqB,GAC5B,cAAc,CAuqBhB"}

package/dist/planner/commands/adapter.js

@@ -565,6 +565,25 @@ export function createPlannerAdapter(config) {
         return run(untranslate(command), runOptions);
     };
     return {
+        resetWorkspace() {
+            sync();
+            const revision = engine.state().revision + 1;
+            engine = createCookbookEngine({
+                catalog,
+                state: {
+                    version: 1,
+                    revision,
+                    applied: resolvedApplied(),
+                    cookbook: (port?.read?.() ?? engine.cookbook()),
+                    journal: [],
+                },
+            });
+            outward.clear();
+            inward.clear();
+            syncError = null;
+            lastKey = signature(port?.read?.() ?? engine.cookbook(), resolvedApplied());
+            deliver();
+        },
         run: runWithUndo,
         batch,
         snapshot() {

package/dist/planner/export-context.d.ts

@@ -0,0 +1,6 @@
+import type { BrowserAssistantTransport } from '../assistant/transport.ts';
+import type { PlannerController } from './commands/index.ts';
+import type { PlannerExportContext } from './types.ts';
+/** Synchronous capture: no user edit or model completion can interleave it. */
+export declare function capturePlannerExport(controller: PlannerController, nativeAssistant?: BrowserAssistantTransport): PlannerExportContext;
+//# sourceMappingURL=export-context.d.ts.map

package/dist/planner/export-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-context.d.ts","sourceRoot":"","sources":["../../src/lib/planner/export-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,iBAAiB,EAC7B,eAAe,CAAC,EAAE,yBAAyB,GAC1C,oBAAoB,CAatB"}

package/dist/planner/export-context.js

@@ -0,0 +1,14 @@
+/** Synchronous capture: no user edit or model completion can interleave it. */
+export function capturePlannerExport(controller, nativeAssistant) {
+    if (nativeAssistant?.busy) {
+        throw new Error('Wait for the assistant to finish, or stop it, then try again.');
+    }
+    const result = controller.run({ name: 'export_cookbook', input: {} });
+    if (!result.ok)
+        throw new Error(result.error.message);
+    return structuredClone({
+        export: result.data,
+        revision: result.snapshot.revision,
+        conversation: nativeAssistant?.conversation() ?? [],
+    });
+}

package/dist/planner/guide.d.ts

@@ -0,0 +1,69 @@
+import type { ShellTargets } from '@happyvertical/smrt-svelte/workspace';
+import type { BatchResult, PlanSnapshot } from './commands/index.ts';
+export type PlannerGuideControl = 'build' | 'export' | 'chef' | 'edit';
+export declare const PLANNER_GUIDE_CONTROLS: {
+    build: {
+        targetId: string;
+        label: string;
+        description: string;
+    };
+    export: {
+        targetId: string;
+        label: string;
+        description: string;
+    };
+    chef: {
+        targetId: string;
+        label: string;
+        description: string;
+    };
+    edit: {
+        targetId: string;
+        label: string;
+        description: string;
+    };
+};
+export interface PlannerGuideResult {
+    ok: boolean;
+    targetId?: string;
+    label?: string;
+    description?: string;
+    reason?: string;
+}
+export interface PlannerGuideHandle {
+    highlight(input: {
+        kind: 'arrival';
+    } | {
+        kind: 'control';
+        control: PlannerGuideControl;
+    } | {
+        kind: 'addition';
+        before: PlanSnapshot;
+        result: BatchResult;
+    }): Promise<PlannerGuideResult>;
+    dismiss(): void;
+}
+/** Semantic target choice is based on actual before/after execution, never catalog order. */
+export declare function additionGuideTarget(before: PlanSnapshot, result: BatchResult): {
+    section: {
+        id: string;
+        label: string;
+        hidden: boolean;
+        items: {
+            id: string;
+            label: string;
+            hidden: boolean;
+        }[];
+    };
+    item: {
+        id: string;
+        label: string;
+        hidden: boolean;
+    };
+} | undefined;
+export declare function createPlannerGuide(options: {
+    targets?: ShellTargets;
+    isMounted: () => boolean;
+    revealMenu?: () => void;
+}): PlannerGuideHandle;
+//# sourceMappingURL=guide.d.ts.map