@dxos/plugin-assistant 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/hooks/useProcessEphemeralStatus.ts

@@ -0,0 +1,192 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom';
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Stream from 'effect/Stream';
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import { Capabilities } from '@dxos/app-framework';
+import { useOptionalCapability } from '@dxos/app-framework/ui';
+import { Process, ServiceResolver, type Trace } from '@dxos/compute';
+import { ProcessManager } from '@dxos/compute-runtime';
+import { type Space } from '@dxos/react-client/echo';
+
+import { resolveEphemeralStatusUpdate } from '#execution-graph';
+
+const atomEmpty = Atom.make(() => [] as const);
+
+const ACTIVE_PROCESS_STATES = new Set<Process.State>([Process.State.RUNNING, Process.State.HYBERNATING]);
+
+/** Durable trace lines that represent finished work, not in-flight status. */
+export const isTerminalActivityLine = (line: string): boolean =>
+  line.endsWith(' - Success') || line.endsWith(' - Error') || line === 'Agent completed request';
+
+const collectDescendantPids = (processes: readonly Process.Info[], rootPid: string): Set<string> => {
+  const pids = new Set([rootPid]);
+  let expanded = true;
+  while (expanded) {
+    expanded = false;
+    for (const process of processes) {
+      const pid = String(process.pid);
+      const parentPid = process.parentPid ? String(process.parentPid) : undefined;
+      if (parentPid && pids.has(parentPid) && !pids.has(pid)) {
+        pids.add(pid);
+        expanded = true;
+      }
+    }
+  }
+  return pids;
+};
+
+const resolveSubscribePids = (agentPid: Process.ID, processes: readonly Process.Info[]): Process.ID[] => {
+  const rootPid = String(agentPid);
+  const descendants = collectDescendantPids(processes, rootPid);
+  const activePids = processes
+    .filter((process) => descendants.has(String(process.pid)) && ACTIVE_PROCESS_STATES.has(process.state))
+    .map((process) => process.pid);
+
+  if (activePids.length > 0) {
+    return activePids;
+  }
+
+  return [agentPid];
+};
+
+const attachActiveHandle = (
+  processManager: ProcessManager.Manager,
+  pid: Process.ID,
+): Effect.Effect<ProcessManager.Handle<any, any, never> | undefined> =>
+  Effect.gen(function* () {
+    const maxAttempts = 15;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const handle = yield* processManager.attach(pid).pipe(Effect.catchAll(() => Effect.succeed(undefined)));
+      if (handle && ACTIVE_PROCESS_STATES.has(handle.status.state)) {
+        return handle;
+      }
+      if (handle) {
+        return undefined;
+      }
+      yield* Effect.sleep(100);
+    }
+    return undefined;
+  });
+
+/**
+ * Subscribes to ephemeral trace events for a delegated sub-agent process subtree
+ * and surfaces the latest pending text or tool-call block as a status line.
+ */
+export const useProcessEphemeralStatus = (
+  agentPid: Process.ID | undefined,
+  space: Space | undefined,
+): string | undefined => {
+  // Optional capabilities: the live status is a progressive enhancement, so the component still
+  // renders (e.g. in standalone stories) when there is no plugin manager / process runtime.
+  const runtime = useOptionalCapability(Capabilities.ProcessManagerRuntime);
+  const monitor = useOptionalCapability(Capabilities.ProcessMonitor);
+  const processes = useAtomValue(monitor?.processTreeAtom ?? atomEmpty);
+  const [status, setStatus] = useState<string | undefined>();
+  const fibersRef = useRef<Fiber.RuntimeFiber<void, unknown>[]>([]);
+
+  const subscribePidsKey = useMemo(() => {
+    if (!agentPid) {
+      return '';
+    }
+    return resolveSubscribePids(agentPid, processes)
+      .map((pid) => String(pid))
+      .sort()
+      .join('|');
+  }, [agentPid, processes]);
+
+  useEffect(() => {
+    if (!agentPid || !space?.id || !runtime || !subscribePidsKey) {
+      setStatus(undefined);
+      return;
+    }
+
+    const pids = subscribePidsKey.split('|').map((pid) => Process.ID.make(pid));
+    let disposed = false;
+    let replaying = true;
+    let replayStatus: string | undefined;
+    const endReplay = () => {
+      replaying = false;
+      if (!disposed) {
+        setStatus(replayStatus);
+      }
+    };
+    queueMicrotask(endReplay);
+    fibersRef.current = [];
+
+    const handleEphemeralMessage = (message: Trace.Message) => {
+      const update = resolveEphemeralStatusUpdate(message);
+      if (update === 'unchanged') {
+        return;
+      }
+
+      if (replaying) {
+        replayStatus = update.line;
+        return;
+      }
+      setStatus(update.line);
+    };
+
+    const layer = ServiceResolver.provide({ space: space.id }, ProcessManager.ProcessManagerService);
+
+    const subscribe = (pid: Process.ID) =>
+      Effect.gen(function* () {
+        // `attachActiveHandle` polls, so a teardown can land mid-resolve; bail before forking a
+        // daemon that the cleanup pass below would never see (and thus never interrupt).
+        if (disposed) {
+          return;
+        }
+        const processManager = yield* ProcessManager.ProcessManagerService;
+        const handle = yield* attachActiveHandle(processManager, pid);
+        if (!handle || disposed) {
+          return;
+        }
+
+        // `forkDaemon` keeps the stream fiber alive after `runPromise(forEach)` returns;
+        // scoped `fork` is interrupted when the subscribe effect's parent scope closes.
+        const fiber = yield* handle.subscribeEphemeral().pipe(
+          Stream.runForEach((message) =>
+            Effect.sync(() => {
+              if (disposed) {
+                return;
+              }
+              handleEphemeralMessage(message);
+            }),
+          ),
+          Effect.forkDaemon,
+        );
+        if (disposed) {
+          yield* Fiber.interrupt(fiber);
+          return;
+        }
+        fibersRef.current.push(fiber);
+      });
+
+    void runtime
+      .runPromise(
+        Effect.forEach(pids, subscribe, { concurrency: 'unbounded', discard: true }).pipe(Effect.provide(layer)),
+      )
+      .catch(() => {
+        if (!disposed) {
+          setStatus(undefined);
+        }
+      });
+
+    return () => {
+      disposed = true;
+      const fibers = fibersRef.current;
+      fibersRef.current = [];
+      for (const fiber of fibers) {
+        void runtime.runPromise(Fiber.interrupt(fiber).pipe(Effect.provide(layer)));
+      }
+    };
+  }, [agentPid, runtime, space?.id, subscribePidsKey]);
+
+  return status;
+};

package/src/hooks/useReferencesProvider.ts

@@ -20,7 +20,7 @@ export const useReferencesProvider = (space?: Space): ReferencesProvider | undef
     return {
       getReferences: async ({ query }) => {
         // TODO(burdon): Previously we filtered by types declared by the artifact definitions.
-        // const schemas = blueprints.map((blueprint) => blueprint.schema).flat();
+        // const schemas = skills.map((skill) => skill.schema).flat();
         // const objects = await space.db
         //   .query(Filter.or(...schemas.map((schema) => Filter.type(schema as Type.Schema))))
         //   .run();

package/src/hooks/useSkillRegistry.ts

@@ -0,0 +1,125 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { type AiContext } from '@dxos/assistant';
+import { Skill } from '@dxos/compute';
+import { type Database, Filter, Obj, Ref, type Registry } from '@dxos/echo';
+import { useQuery } from '@dxos/react-client/echo';
+import { distinctBy } from '@dxos/util';
+
+export const useSkills = ({ registry, db }: { registry?: Registry.Registry; db?: Database.Database }) => {
+  const [registrySkills, setRegistrySkills] = useState<Skill.Skill[]>(
+    () => registry?.query(Filter.type(Skill.Skill)).runSync() ?? [],
+  );
+
+  useEffect(() => {
+    if (!registry) {
+      setRegistrySkills([]);
+      return;
+    }
+    setRegistrySkills(registry.query(Filter.type(Skill.Skill)).runSync());
+    return registry.changed.on(() => {
+      setRegistrySkills(registry.query(Filter.type(Skill.Skill)).runSync());
+    });
+  }, [registry]);
+
+  const spaceSkills = useQuery(db, Filter.type(Skill.Skill));
+  return useMemo(() => {
+    const skills = distinctBy([...registrySkills, ...spaceSkills], (b) => Obj.getMeta(b).key);
+    skills.sort(({ name: a }, { name: b }) => a.localeCompare(b));
+    return skills;
+  }, [registrySkills, spaceSkills]);
+};
+
+/**
+ * Create reactive map of active skills (by key).
+ */
+export const useActiveSkills = ({ context }: { context?: AiContext.Binder }) => {
+  const [active, setActive] = useState<Map<string, Skill.Skill>>(new Map());
+
+  useEffect(() => {
+    if (!context) {
+      setActive(new Map());
+      return;
+    }
+
+    const updateActive = () => {
+      const skills = context.getSkills();
+      setActive(
+        new Map(
+          skills
+            .map((skill) => [Obj.getMeta(skill).key, skill] as const)
+            .filter((entry): entry is readonly [string, Skill.Skill] => entry[0] !== undefined),
+        ),
+      );
+    };
+
+    // Set initial value.
+    updateActive();
+
+    // Subscribe to changes.
+    return context.subscribeSkills(updateActive);
+  }, [context]);
+
+  return active;
+};
+
+// TODO(burdon): Move logic into binder.
+export const useSkillHandlers = ({
+  db,
+  context,
+  registry,
+}: {
+  db: Database.Database;
+  context?: AiContext.Binder;
+  registry?: Registry.Registry;
+}) => {
+  const onUpdateSkill = useCallback(
+    async (key: string, checked: boolean) => {
+      if (!context) {
+        return;
+      }
+
+      if (checked) {
+        // Check if the skill is in the registry — if so, bind via its key URI directly
+        // (no DB clone needed). Fall back to an existing DB copy for user-forked skills.
+        const registrySkill = registry
+          ?.query(Filter.type(Skill.Skill))
+          .runSync()
+          .find((b) => Obj.getMeta(b).key === key);
+
+        if (registrySkill) {
+          await context.bind({ skills: [Ref.fromURI(Skill.registryURI(key))] });
+        } else {
+          // User-forked skill (in DB but not in registry): bind via DB ref.
+          const objects = await db.query(Filter.type(Skill.Skill)).run();
+          const storedSkill = objects.find((skill) => Obj.getMeta(skill).key === key);
+          if (storedSkill) {
+            await context.bind({ skills: [Ref.make(storedSkill)] });
+          }
+        }
+      } else {
+        // Unbind: try registry ref first, then DB ref.
+        const registrySkill = registry
+          ?.query(Filter.type(Skill.Skill))
+          .runSync()
+          .find((b) => Obj.getMeta(b).key === key);
+        if (registrySkill) {
+          await context.unbind({ skills: [Ref.fromURI(Skill.registryURI(key))] });
+        } else {
+          const objects = await db.query(Filter.type(Skill.Skill)).run();
+          const storedSkill = objects.find((skill) => Obj.getMeta(skill).key === key);
+          if (storedSkill) {
+            await context.unbind({ skills: [Ref.make(storedSkill)] });
+          }
+        }
+      }
+    },
+    [db, context, registry],
+  );
+
+  return { onUpdateSkill };
+};

package/src/hooks/useTraceMessages.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom';
+import { useAtomValue } from '@effect-atom/atom-react';
+import { pipe } from 'effect/Function';
+import { useMemo } from 'react';
+
+import { Trace } from '@dxos/compute';
+import { Filter, Query } from '@dxos/echo';
+import { FeedTraceSink } from '@dxos/functions-runtime';
+import { type Space } from '@dxos/react-client/echo';
+
+const atomEmpty = Atom.make(() => [] as const);
+
+/**
+ * Atom of raw trace messages for a space — the input to `buildExecutionGraph`.
+ */
+export const getTraceMessagesAtom = (space: Space): Atom.Atom<readonly Trace.Message[]> =>
+  pipe(
+    space.db.query(FeedTraceSink.query).atom,
+    Atom.map(
+      (feeds) =>
+        // TODO(dmaretskyi): Single query with limit(1) and feed traversal when query supports it.
+        space.db.query(
+          feeds.length > 0
+            ? Query.type(Trace.Message).from(feeds[0])
+            : (Query.select(Filter.nothing()) as Query.Query<never>),
+        ).atom,
+    ),
+    (atom) => Atom.make((get) => get(get(atom))),
+  );
+
+/**
+ * Subscribes to the space invocation trace feed.
+ */
+export const useTraceMessages = (space?: Space): readonly Trace.Message[] => {
+  const atom = useMemo(() => (space ? getTraceMessagesAtom(space) : atomEmpty), [space]);
+  return useAtomValue(atom);
+};

package/src/index.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './blueprints';
+export * from './skills';
 export * from './meta';
 export * from './paths';
 export * from './types';

package/src/meta.ts

@@ -4,40 +4,12 @@
 
 import { Plugin } from '@dxos/app-framework';
 import { DXN } from '@dxos/keys';
-import { trim } from '@dxos/util';
 
-export const meta = Plugin.makeMeta({
-  key: DXN.make('org.dxos.plugin.assistant'),
-  name: 'Assistant',
-  author: 'DXOS',
-  description: trim`
-    AssistantPlugin brings a conversational AI assistant into DXOS Composer, letting users chat naturally
-    with objects in their spaces. Every Chat is a first-class ECHO object — messages are persisted,
-    replicated across peers in real time, and can be bound to any document or collection as a companion
-    panel that appears alongside the primary view.
+import config from '../dx.config';
 
-    AI capabilities are delivered through a flexible multi-provider model layer. Users can route requests
-    to the DXOS Edge service, a locally running Ollama instance, or LM Studio, and switch providers at
-    any time in Settings. Each provider can be configured with a preferred model, and the runtime
-    automatically falls back when a provider is unavailable.
+export const meta = Plugin.getMetaFromConfig(config);
 
-    Blueprints give every chat a specialised identity. Built-in blueprints cover general assistance,
-    web browsing, database interaction, web search, Discord and Linear integration, autonomous agents,
-    planning, memory, automation, and a wizard for authoring new blueprints. Binding a blueprint
-    changes the system instructions and the tool set exposed to the model in a single step.
-
-    Tool execution runs through the DXOS compute runtime so every AI action — opening a document,
-    searching the web, querying a database — produces a structured execution trace. The optional
-    TracePanel visualises that trace as a commit graph or raw JSON, giving developers full observability
-    into what the model did and why.
-  `,
-  icon: 'ph--sparkle--regular',
-  iconHue: 'sky',
-  source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-assistant',
-  spec: 'PLUGIN.mdl',
-});
-
-export const ASSISTANT_DIALOG = DXN.make(`${meta.id}.assistantDialog`);
+export const ASSISTANT_DIALOG = DXN.make(`${meta.profile.key}.assistantDialog`);
 
 /** Companion variant identifier for the assistant chat panel. */
 export const ASSISTANT_COMPANION_VARIANT = 'assistant-chat';

package/src/operations/create-chat.ts

@@ -6,14 +6,13 @@ import * as Effect from 'effect/Effect';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
 import { AiContext } from '@dxos/assistant';
-import { Chat, DatabaseBlueprint, AgentWizardBlueprint } from '@dxos/assistant-toolkit';
-import { Blueprint, Operation } from '@dxos/compute';
-import { Feed, Obj, Ref } from '@dxos/echo';
-import { createFeedServiceLayer } from '@dxos/echo-client';
+import { AgentWizardSkill, AlarmSkill, Chat, DatabaseSkill } from '@dxos/assistant-toolkit';
+import { Operation, Skill } from '@dxos/compute';
+import { Database, Feed, Obj, Ref } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
 import { ClientCapabilities } from '@dxos/plugin-client';
 
-import { AssistantBlueprint } from '#blueprints';
+import { AssistantSkill } from '#skills';
 import { AssistantOperation } from '#types';
 
 const handler: Operation.WithHandler<typeof AssistantOperation.CreateChat> = AssistantOperation.CreateChat.pipe(
@@ -30,21 +29,21 @@ const handler: Operation.WithHandler<typeof AssistantOperation.CreateChat> = Ass
         space.db.add(chat);
       }
 
-      // Dynamic import to avoid circular dependency with the barrel that also exports BlueprintManagerHandlers.
-      const { BlueprintManagerBlueprint } = yield* Effect.promise(() => import('@dxos/assistant-toolkit'));
+      // Dynamic import to avoid circular dependency with the barrel that also exports SkillManagerHandlers.
+      const { SkillManagerSkill } = yield* Effect.promise(() => import('@dxos/assistant-toolkit'));
 
-      const feedServiceLayer = createFeedServiceLayer(space.queues);
-      const runtime = yield* Effect.runtime<Feed.FeedService>().pipe(Effect.provide(feedServiceLayer));
+      const runtime = yield* Effect.runtime<Database.Service>().pipe(Effect.provide(Database.layer(space.db)));
       const binder = new AiContext.Binder({ feed, runtime, registry });
 
-      // Bind default blueprints via registry refs — no DB clone needed since the ECHO ref
+      // Bind default skills via registry refs — no DB clone needed since the ECHO ref
       // resolver already spans the hypergraph registry.
       yield* Effect.promise(() =>
         binder.use((b: AiContext.Binder) =>
           b.bind({
-            blueprints: [AssistantBlueprint, DatabaseBlueprint, AgentWizardBlueprint, BlueprintManagerBlueprint].map(
-              ({ key }) => Ref.fromURI(Blueprint.registryURI(key)),
+            skills: [AssistantSkill, DatabaseSkill, AgentWizardSkill, SkillManagerSkill, AlarmSkill].map(({ key }) =>
+              Ref.fromURI(Skill.registryURI(key)),
             ),
+            objects: [Ref.make(chat)],
           }),
         ),
       );

package/src/operations/fork-chat.ts

@@ -5,12 +5,11 @@
 import * as Effect from 'effect/Effect';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
-import { getObjectPathFromObject, LayoutOperation } from '@dxos/app-toolkit';
+import { LayoutOperation, Paths } from '@dxos/app-toolkit';
 import { AiContext, SessionLink } from '@dxos/assistant';
 import { Chat } from '@dxos/assistant-toolkit';
 import { Operation } from '@dxos/compute';
 import { Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
-import { createFeedServiceLayer } from '@dxos/echo-client';
 import { invariant } from '@dxos/invariant';
 import { ClientCapabilities } from '@dxos/plugin-client';
 import { SpaceOperation } from '@dxos/plugin-space';
@@ -22,18 +21,15 @@ const handler: Operation.WithHandler<typeof AssistantOperation.ForkChat> = Assis
   Operation.withHandler(
     Effect.fnUntraced(function* ({ chat, companionTo }) {
       const { db } = yield* Database.Service;
-      const sourceFeed = chat.feed.target;
-      invariant(sourceFeed, 'Chat feed not found.');
+      const sourceFeed = yield* Database.load(chat.feed);
 
       const client = yield* Capability.get(ClientCapabilities.Client);
       const space = client.spaces.get(db.spaceId);
       invariant(space, 'Space not found.');
 
-      const feedServiceLayer = createFeedServiceLayer(space.queues);
+      const dbLayer = Database.layer(space.db);
 
-      const messages = yield* Feed.runQuery(sourceFeed, Filter.type(Message.Message)).pipe(
-        Effect.provide(feedServiceLayer),
-      );
+      const messages = yield* Feed.query(sourceFeed, Filter.type(Message.Message)).run.pipe(Effect.provide(dbLayer));
 
       // Sort chronologically to find the last message.
       const sorted = messages
@@ -46,8 +42,7 @@ const handler: Operation.WithHandler<typeof AssistantOperation.ForkChat> = Assis
         db,
         name: sourceName ? `${sourceName} (fork)` : undefined,
       });
-      const newFeed = newChat.feed.target;
-      invariant(newFeed, 'New chat feed not found.');
+      const newFeed = yield* Database.load(newChat.feed);
 
       if (sorted.length > 0) {
         const lastMessage = sorted[sorted.length - 1];
@@ -58,32 +53,32 @@ const handler: Operation.WithHandler<typeof AssistantOperation.ForkChat> = Assis
             feedRef: Ref.make(sourceFeed),
             messageId: lastMessage.id,
           }),
-        ]).pipe(Effect.provide(feedServiceLayer));
+        ]).pipe(Effect.provide(dbLayer));
       }
 
-      // Copy source chat's blueprint and object bindings to the new feed.
+      // Copy source chat's skill and object bindings to the new feed.
       // Sort chronologically so add/remove events are applied in the correct order.
-      const sourceBindings = (yield* Feed.runQuery(sourceFeed, Filter.type(AiContext.Binding)).pipe(
-        Effect.provide(feedServiceLayer),
+      const sourceBindings = (yield* Feed.query(sourceFeed, Filter.type(AiContext.Binding)).run.pipe(
+        Effect.provide(dbLayer),
       )).filter(Obj.instanceOf(AiContext.Binding));
 
       if (sourceBindings.length > 0) {
         // Reduce binding events to the final active set.
-        const blueprintRefMap = new Map<string, Ref.Ref<any>>();
+        const skillRefMap = new Map<string, Ref.Ref<any>>();
         const objectRefMap = new Map<string, Ref.Ref<any>>();
         for (const binding of sourceBindings) {
-          binding.blueprints.added.forEach((ref: Ref.Ref<any>) => blueprintRefMap.set(ref.uri, ref));
-          binding.blueprints.removed.forEach((ref: Ref.Ref<any>) => blueprintRefMap.delete(ref.uri));
+          binding.skills.added.forEach((ref: Ref.Ref<any>) => skillRefMap.set(ref.uri, ref));
+          binding.skills.removed.forEach((ref: Ref.Ref<any>) => skillRefMap.delete(ref.uri));
           binding.objects.added.forEach((ref: Ref.Ref<any>) => objectRefMap.set(ref.uri, ref));
           binding.objects.removed.forEach((ref: Ref.Ref<any>) => objectRefMap.delete(ref.uri));
         }
 
         yield* Feed.append(newFeed, [
           Obj.make(AiContext.Binding, {
-            blueprints: { added: Array.from(blueprintRefMap.values()), removed: [] },
+            skills: { added: Array.from(skillRefMap.values()), removed: [] },
             objects: { added: Array.from(objectRefMap.values()), removed: [] },
           }),
-        ]).pipe(Effect.provide(feedServiceLayer));
+        ]).pipe(Effect.provide(dbLayer));
       }
 
       if (companionTo) {
@@ -100,7 +95,7 @@ const handler: Operation.WithHandler<typeof AssistantOperation.ForkChat> = Assis
         );
       } else {
         // Navigate to the forked chat as a standalone plank.
-        const chatPath = getObjectPathFromObject(newChat);
+        const chatPath = Paths.getObjectPathFromObject(newChat);
         yield* Operation.invoke(LayoutOperation.Open, { subject: [chatPath] });
       }
 

package/src/operations/generate-home-suggestions.test.ts

@@ -0,0 +1,103 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom, Registry } from '@effect-atom/atom-react';
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { Capabilities, Capability, CapabilityManager } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { Database } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
+import { EntityId } from '@dxos/keys';
+
+import { AssistantCapabilities, AssistantOperation } from '#types';
+
+import { AssistantOperationHandlerSet } from './index';
+
+EntityId.dangerouslyDisableRandomness();
+
+const CACHE_TTL_MS = 60 * 60 * 1000;
+
+// Shared registry and cache atom — each test sets its own cache state before invoking the operation.
+const testRegistry = Registry.make();
+const testCacheAtom = Atom.make<AssistantCapabilities.HomeSuggestionsCache>({}).pipe(Atom.keepAlive);
+const testManager = CapabilityManager.make({ registry: testRegistry });
+testManager.contribute({ module: 'test', interface: Capabilities.AtomRegistry, implementation: testRegistry });
+testManager.contribute({
+  module: 'test',
+  interface: AssistantCapabilities.HomeSuggestionsCache,
+  implementation: testCacheAtom,
+});
+
+const TestLayer = AssistantTestLayer({
+  operationHandlers: AssistantOperationHandlerSet,
+  // Provide Capability.Service so the handler can read/write the suggestions cache.
+  extraServices: Layer.succeed(Capability.Service, testManager),
+});
+
+describe('GenerateHomeSuggestions', () => {
+  it.effect(
+    'empty space returns empty prompts (fallback path)',
+    Effect.fnUntraced(
+      function* (_) {
+        const { db } = yield* Database.Service;
+        testRegistry.set(testCacheAtom, {});
+
+        const result = yield* Operation.invoke(AssistantOperation.GenerateHomeSuggestions, { db });
+
+        expect(result.prompts).toHaveLength(0);
+        // No cache entry written when prompts is empty.
+        const cached = testRegistry.get(testCacheAtom);
+        expect(cached[db.spaceId]).toBeUndefined();
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'cache hit returns stored prompts without re-generating',
+    Effect.fnUntraced(
+      function* (_) {
+        const { db } = yield* Database.Service;
+        const stored = ['Refine the proposal', 'Review the schedule', 'Draft a summary'];
+        testRegistry.set(testCacheAtom, {
+          [db.spaceId]: { generatedAt: Date.now(), prompts: stored },
+        });
+
+        const result = yield* Operation.invoke(AssistantOperation.GenerateHomeSuggestions, { db });
+
+        expect(result.prompts).toEqual(stored);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'expired cache entry is not used — re-runs and returns empty for empty space',
+    Effect.fnUntraced(
+      function* (_) {
+        const { db } = yield* Database.Service;
+        const stale = ['Stale prompt A', 'Stale prompt B', 'Stale prompt C'];
+        testRegistry.set(testCacheAtom, {
+          [db.spaceId]: { generatedAt: Date.now() - 2 * CACHE_TTL_MS, prompts: stale },
+        });
+
+        // Empty space — expired entry is ignored, no LLM call, no new cache entry written.
+        const result = yield* Operation.invoke(AssistantOperation.GenerateHomeSuggestions, { db });
+
+        expect(result.prompts).toHaveLength(0);
+        // Cache not updated since prompts is empty.
+        const cached = testRegistry.get(testCacheAtom);
+        expect(cached[db.spaceId]?.prompts).toEqual(stale);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});