@dxos/assistant 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/session/AiSession.ts

@@ -6,7 +6,6 @@
 
 import { type Registry as AtomRegistry } from '@effect-atom/atom-react';
 import * as Array from 'effect/Array';
-import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Either from 'effect/Either';
 import { pipe } from 'effect/Function';
@@ -15,20 +14,21 @@ import * as Record from 'effect/Record';
 import * as Runtime from 'effect/Runtime';
 
 import { type OpaqueToolkit, type ToolExecutionService, type ToolResolverService } from '@dxos/ai';
-import { type Blueprint, McpServer, Operation, Trace } from '@dxos/compute';
+import { McpServer, Operation, type Skill, Trace } from '@dxos/compute';
 import { Resource } from '@dxos/context';
 import { Database, Feed, Filter, Obj, Registry } from '@dxos/echo';
-import { EffectEx } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
 import { McpToolkit } from '@dxos/mcp-client';
-import { Message, type ContentBlock } from '@dxos/types';
+import { type ContentBlock, Message } from '@dxos/types';
 
-import { ToolExecutionServices } from '../functions';
 import { AiRequest, type GenerationObserver, formatSystemPrompt } from '../request';
+import { ToolExecutionServices } from '../tool-runtime';
 import { McpServerError } from '../util';
 import * as AiContext from './AiContext';
+import * as Harness from './Harness';
 import { SessionLoader } from './SessionLoader';
+import * as SkillHooks from './SkillHooks';
 import { createToolkit } from './toolkit';
 
 export type RunProps<R = never> = {
@@ -38,14 +38,21 @@ export type RunProps<R = never> = {
   toolkit?: OpaqueToolkit.OpaqueToolkit<R>;
 
   /**
-   * Space-level MCP servers to connect alongside blueprint-defined ones.
+   * Space-level MCP servers to connect alongside skill-defined ones.
    */
   mcpServers?: readonly McpServer.McpServer[];
+
+  /**
+   * When false, messages from this request are not appended to the feed or persisted to trace.
+   *
+   * @default true
+   */
+  persist?: boolean;
 };
 
 export type Options = {
   feed: Feed.Feed;
-  runtime: Runtime.Runtime<Feed.FeedService>;
+  runtime: Runtime.Runtime<Database.Service>;
   /** @effect-atom/atom-react Registry for reactive state. */
   registry?: AtomRegistry.Registry;
 };
@@ -62,11 +69,11 @@ const SUMMARY_THRESHOLD = 80_000;
  */
 export class Session extends Resource {
   /**
-   * Blueprints and objects bound to the session.
+   * Skills and objects bound to the session.
    */
   private readonly _binder: AiContext.Binder;
   private readonly _feed: Feed.Feed;
-  private readonly _runtime: Runtime.Runtime<Feed.FeedService>;
+  private readonly _runtime: Runtime.Runtime<Database.Service>;
   private readonly _sessionLoader = new SessionLoader();
 
   public constructor(options: Options) {
@@ -107,7 +114,7 @@ export class Session extends Resource {
     ToolExecutionService | ToolResolverService
   > {
     return Effect.gen(this, function* () {
-      const toolkit = yield* createToolkit({ blueprints: this.context.getBlueprints() });
+      const toolkit = yield* createToolkit({ skills: this.context.getSkills() });
       return toolkit.toolkit.tools;
     }).pipe(Effect.orDie);
   }
@@ -133,52 +140,66 @@ export class Session extends Resource {
   ): Effect.Effect<Message.Message[], AiRequest.RunError, AiRequest.RunRequirements | R> {
     return Effect.gen(this, function* () {
       const history = yield* Effect.promise(() => this.getHistory());
-      const blueprints = this.context.getBlueprints();
+      const skills = this.context.getSkills();
       const objects = this.context.getObjects();
 
       log('run', {
         history: history.length,
-        blueprints: blueprints.length,
+        skills: skills.length,
         objects: objects.length,
       });
 
       const request = new AiRequest.Request({
         summarizationThreshold: SUMMARY_THRESHOLD,
         observer: params.observer,
+        persist: params.persist,
         onOutput: (message) =>
           Effect.promise(() => Runtime.runPromise(this._runtime)(Feed.append(this._feed, [message]))),
       });
 
       yield* request.begin({
         history,
-        blueprints,
+        skills,
         objects,
         prompt: params.prompt,
         system: params.system,
       });
 
-      // Turn loop: recompute toolkit and system prompt between turns to pick up dynamically enabled blueprints.
+      // Fire begin-request hooks declared by the bound skills. These run in the agent's turn
+      // fiber (Tier A only), so they cannot reach the live host (Tier B) — that is the end hook's job.
+      yield* SkillHooks.runHooks({
+        skills,
+        phase: 'begin-request',
+        invoke: (operation, input) => Operation.invoke(operation, input).pipe(Effect.asVoid, Effect.orDie),
+      });
+
+      // Turn loop: recompute toolkit and system prompt between turns to pick up dynamically enabled skills.
       do {
         yield* Effect.promise(() => this.context.sync());
-        const currentBlueprints = this.context.getBlueprints();
-        const mcps = yield* connectMcpServers(currentBlueprints, params.mcpServers);
+        const currentSkills = this.context.getSkills();
+        const mcps = yield* connectMcpServers(currentSkills, params.mcpServers);
         const toolkit = yield* createToolkit({
           toolkit: params.toolkit,
-          blueprints: currentBlueprints,
+          skills: currentSkills,
           opaqueToolkits: mcps,
         });
 
         log('toolkit', { tools: Record.keys(toolkit.toolkit.tools) });
         const system = yield* formatSystemPrompt({
           system: params.system,
-          blueprints: currentBlueprints,
+          skills: currentSkills,
           objects: this.context.getObjects(),
         }).pipe(Effect.orDie);
 
-        const { done } = yield* request.runAgentTurn({ system, toolkit });
+        const { done, finishReason } = yield* request.runAgentTurn({ system, toolkit });
         if (done) {
           break;
         }
+        // A paused server-tool turn (e.g. Anthropic `pause_turn`) resumes with another request and
+        // no local tool execution; the trailing server tool call must be left intact for the provider.
+        if (finishReason === 'pause') {
+          continue;
+        }
 
         yield* request.runTools({ toolkit });
       } while (true);
@@ -193,10 +214,13 @@ export class Session extends Resource {
     }).pipe(
       Effect.provide(
         Layer.mergeAll(
-          Layer.succeed(AiContext.Service, {
-            binder: this.context,
-          }),
-          Layer.succeed(Service, this),
+          // Tier A only: the agent's own turn fiber has no `ProcessManager.Service` in scope, so
+          // Tier B (setAlarm/enqueueMessage) is reachable only by child operations through the
+          // process-affinity HarnessService LayerSpec — not from here.
+          Layer.succeed(
+            Harness.HarnessService,
+            Harness.fromBinder({ feed: this._feed, runtime: this._runtime, binder: this.context }),
+          ),
           Operation.withInvocationOptions({ conversation: Obj.getURI(this._feed) }),
         ),
       ),
@@ -205,68 +229,12 @@ export class Session extends Resource {
   }
 }
 
-/**
- * Gives access to the ai session.
- */
-export class Service extends Context.Tag('@dxos/assistant/AiSessionService')<Service, Session>() {
-  /**
-   * Create a new session layer from options.
-   */
-  static layer = (options: Options): Layer.Layer<Service | AiContext.Service> =>
-    aiContextFromSession.pipe(
-      Layer.provideMerge(
-        Layer.scoped(
-          Service,
-          Effect.gen(function* () {
-            const session = yield* EffectEx.acquireReleaseResource(() => new Session(options));
-            return session;
-          }),
-        ),
-      ),
-    );
-
-  /**
-   * Create a new session with a new feed.
-   */
-  static layerNewFeed = (
-    options?: Omit<Options, 'feed' | 'runtime'>,
-  ): Layer.Layer<Service | AiContext.Service, never, Database.Service | Feed.FeedService> =>
-    Layer.unwrapScoped(
-      Effect.gen(function* () {
-        const feed = yield* Database.add(Feed.make());
-        const runtime = yield* Effect.runtime<Feed.FeedService>();
-        return Service.layer({ ...options, feed, runtime });
-      }),
-    );
-
-  /**
-   * Run a prompt in the current session.
-   */
-  static run = <R = never>(
-    params: RunProps<R>,
-  ): Effect.Effect<Message.Message[], AiRequest.RunError, AiRequest.RunRequirements | Service | R> =>
-    Effect.gen(function* () {
-      const session = yield* Service;
-      return yield* session.createRequest(params);
-    });
-}
-
-const aiContextFromSession = Layer.effect(
-  AiContext.Service,
-  Effect.gen(function* () {
-    const session = yield* Service;
-    return {
-      binder: session.context,
-    };
-  }),
-);
-
 const connectMcpServers = (
-  blueprints: readonly Blueprint.Blueprint[],
+  skills: readonly Skill.Skill[],
   spaceMcpServers: readonly McpServer.McpServer[] = [],
 ): Effect.Effect<OpaqueToolkit.OpaqueToolkit[], never, Trace.TraceService> => {
-  const blueprintServers: McpToolkit.McpToolkitOptions[] = pipe(
-    blueprints,
+  const skillServers: McpToolkit.McpToolkitOptions[] = pipe(
+    skills,
     Array.flatMap((_) => _.mcpServers ?? []),
     Array.map(({ url, protocol, apiKey }) => ({ url, protocol, apiKey })),
   );
@@ -275,7 +243,7 @@ const connectMcpServers = (
     protocol,
     apiKey,
   }));
-  const allServers = [...blueprintServers, ...spaceServers];
+  const allServers = [...skillServers, ...spaceServers];
 
   return pipe(
     allServers,

package/src/session/Harness.ts

@@ -0,0 +1,241 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import type * as RpcClient from '@effect/rpc/RpcClient';
+import * as Context from 'effect/Context';
+import * as DateTime from 'effect/DateTime';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import type * as Runtime from 'effect/Runtime';
+import type * as Scope from 'effect/Scope';
+
+import { LayerSpec, Process, ServiceNotAvailableError } from '@dxos/compute';
+import { ProcessManager } from '@dxos/compute-runtime';
+import { Annotation, Database, EID, Feed, Filter, Obj, type URI } from '@dxos/echo';
+import { EffectEx } from '@dxos/effect';
+import { BaseError } from '@dxos/errors';
+import { type ContentBlock, Message } from '@dxos/types';
+
+import * as AiContext from './AiContext';
+import { type HarnessControlRpcs } from './harness-control';
+import { SessionLoader } from './SessionLoader';
+
+export interface Service {
+  /** The conversation {@link AiContext.Binder} (Tier A). */
+  binder: Effect.Effect<AiContext.Binder, NotSupportedError>;
+  /** The conversation message history (Tier A). */
+  history: Effect.Effect<Message.Message[], NotSupportedError>;
+  /** Objects bound to the conversation that match the filter (Tier A). */
+  queryContext<T extends Obj.Unknown>(filter: Filter.Filter<T>): Effect.Effect<T[], NotSupportedError>;
+  /** Enqueue a message into the owning host's input queue (Tier B). */
+  enqueueMessage(options: EnqueueMessageOptions): Effect.Effect<void, NotSupportedError>;
+  /** Schedule a self-wake on the owning host (Tier B). */
+  setAlarm(options: SetAlarmOptions): Effect.Effect<void, NotSupportedError>;
+}
+
+/**
+ * Provides access to the controlling harness for tools and operations that are executed by the agent.
+ *
+ * Replaces AiContextService and AiSessionService.
+ */
+export class HarnessService extends Context.Tag('@dxos/assistant/HarnessService')<HarnessService, Service>() {}
+
+/**
+ * Acess current context binder.
+ */
+export const binder: Effect.Effect<AiContext.Binder, NotSupportedError, HarnessService> = Effect.flatMap(
+  HarnessService,
+  (service) => service.binder,
+);
+
+/**
+ * Query the context using a filter.
+ */
+export const queryContext = <T extends Obj.Unknown>(
+  filter: Filter.Filter<T>,
+): Effect.Effect<T[], NotSupportedError, HarnessService> =>
+  Effect.flatMap(HarnessService, (service) => service.queryContext(filter));
+
+interface EnqueueMessageOptions {
+  content: ContentBlock.Any[];
+
+  // TODO(dmaretskyi): Order: 'first' | 'last'
+}
+
+/**
+ * Query the session history.
+ */
+export const history: Effect.Effect<Message.Message[], NotSupportedError, HarnessService> = Effect.flatMap(
+  HarnessService,
+  (service) => service.history,
+);
+
+/**
+ * Enqueue a message to the harness.
+ */
+export const enqueueMessage = (
+  options: EnqueueMessageOptions,
+): Effect.Effect<void, NotSupportedError, HarnessService> =>
+  Effect.flatMap(HarnessService, (service) => service.enqueueMessage(options));
+
+interface SetAlarmOptions {
+  at: DateTime.DateTime;
+  /**
+   * Message to send when the alarm fires.
+   */
+  message: string | null;
+}
+
+export const setAlarm = (options: SetAlarmOptions): Effect.Effect<void, NotSupportedError, HarnessService> =>
+  Effect.flatMap(HarnessService, (service) => service.setAlarm(options));
+
+/**
+ * Binds skills and/or objects to the conversation context.
+ */
+export const bindContext = ({
+  skills,
+  objects,
+}: AiContext.BindingProps): Effect.Effect<void, NotSupportedError, HarnessService> =>
+  Effect.gen(function* () {
+    const sessionBinder = yield* binder;
+    yield* Effect.promise(() => sessionBinder.bind({ skills, objects }));
+  });
+
+export class NotSupportedError extends BaseError.extend('NotSupportedError', 'Operation not supported') {}
+
+/**
+ * Process-affinity {@link LayerSpec} that materialises {@link HarnessService} from the resolution
+ * context's `conversation` DXN. Merges the former `AiContext.Service` (Tier A) with live host
+ * dispatch (Tier B).
+ */
+export const layerSpec: LayerSpec.LayerSpec = LayerSpec.make(
+  {
+    affinity: 'process',
+    requires: [Database.Service, ProcessManager.Service],
+    provides: [HarnessService],
+  },
+  (context) =>
+    Layer.scoped(
+      HarnessService,
+      Effect.gen(function* () {
+        if (!context.conversation) {
+          // LayerSpec.make requires a never-failing layer (error channel = never), so typed failure
+          // is not possible here. Die with ServiceNotAvailableError to signal a programming error
+          // (missing 'conversation' in spawn environment) that callers cannot recover from.
+          return yield* Effect.die(
+            new ServiceNotAvailableError(HarnessService.key, {
+              message: `Service not available: ${HarnessService.key} — process spawn is missing 'conversation' in environment (set via Operation.withInvocationOptions or ProcessManager.spawn environment)`,
+            }),
+          );
+        }
+        const conversation = context.conversation;
+        const processManager = yield* ProcessManager.Service;
+        const runtime = yield* Effect.runtime<Database.Service>();
+        return yield* make({ conversation, processManager, runtime });
+      }),
+    ),
+);
+
+interface MakeOptions {
+  conversation: URI.URI;
+  processManager: Context.Tag.Service<ProcessManager.Service>;
+  runtime: Runtime.Runtime<Database.Service>;
+}
+
+/**
+ * Builds the {@link Service} for a conversation-scoped resolution context. Tier A resolves the
+ * conversation feed / {@link AiContext.Binder} once; Tier B looks up the owning host process lazily per call
+ * and dispatches over its `Handle.rpc` control surface (raising {@link NotSupportedError} when no
+ * live host owns the conversation).
+ */
+export const make = ({
+  conversation,
+  processManager,
+  runtime,
+}: MakeOptions): Effect.Effect<Service, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const feed = yield* Database.resolve(EID.parse(conversation), Feed.Feed).pipe(
+      Effect.provide(runtime),
+      Effect.orDie,
+    );
+    const boundBinder = yield* EffectEx.acquireReleaseResource(() => new AiContext.Binder({ feed, runtime }));
+    return makeService({
+      feed,
+      runtime,
+      binder: boundBinder,
+      owningHost: lookupOwningHost(processManager, conversation),
+    });
+  });
+
+interface FromBinderOptions {
+  feed: Feed.Feed;
+  runtime: Runtime.Runtime<Database.Service>;
+  binder: AiContext.Binder;
+}
+
+/**
+ * Builds the {@link Service} from a {@link AiContext.Binder} already opened for the conversation (e.g. the
+ * agent's own turn fiber, which has no `ProcessManager.Service` in scope). Tier A is fully served;
+ * Tier B raises {@link NotSupportedError} since the live-host control surface is not reachable here.
+ */
+export const fromBinder = ({ feed, runtime, binder }: FromBinderOptions): Service =>
+  makeService({ feed, runtime, binder, owningHost: Effect.fail(new NotSupportedError()) });
+
+interface MakeServiceOptions {
+  feed: Feed.Feed;
+  runtime: Runtime.Runtime<Database.Service>;
+  binder: AiContext.Binder;
+  owningHost: Effect.Effect<RpcClient.RpcClient<HarnessControlRpcs>, NotSupportedError>;
+}
+
+const makeService = ({ feed, runtime, binder, owningHost }: MakeServiceOptions): Service => ({
+  binder: Effect.succeed(binder),
+  history: Effect.gen(function* () {
+    const messages = yield* Feed.query(feed, Filter.type(Message.Message)).run;
+    return yield* new SessionLoader().reifyHistory(feed, messages);
+  }).pipe(Effect.provide(runtime)),
+  queryContext: <T extends Obj.Unknown>(filter: Filter.Filter<T>) =>
+    Effect.sync(() => {
+      const match = Filter.toPredicate(filter);
+      return binder.getObjects().filter(match);
+    }),
+  enqueueMessage: ({ content }) => owningHost.pipe(Effect.flatMap((rpc) => rpc.enqueueMessage({ content }))),
+  setAlarm: ({ at, message }) =>
+    owningHost.pipe(Effect.flatMap((rpc) => rpc.setAlarm({ at: DateTime.toUtc(at), message }))),
+});
+
+/**
+ * Resolves the live host owning `conversation` per call (so a process replacement — e.g. a model
+ * switch — is never captured stale) and exposes its `HarnessControl` RPC client.
+ */
+const lookupOwningHost = (
+  processManager: Context.Tag.Service<ProcessManager.Service>,
+  conversation: URI.URI,
+): Effect.Effect<RpcClient.RpcClient<HarnessControlRpcs>, NotSupportedError> =>
+  Effect.gen(function* () {
+    const processes = yield* processManager.list({ target: conversation });
+    const host = processes.find(
+      (process) =>
+        !isTerminalProcess(process.status.state) &&
+        Option.getOrElse(
+          Annotation.getDictionary(process.params.annotations, Process.HarnessHostAnnotation),
+          () => false,
+        ),
+    );
+    if (!host) {
+      return yield* Effect.fail(new NotSupportedError());
+    }
+    // The host is discovered by annotation, but the HarnessControl RPC contract is fixed at the
+    // spawn site (agent-process declares it as its `rpcs`); narrow the variance-erased
+    // `RpcClient<any>` to that contract so the dispatch below is typed. No typed path exists here:
+    // the host handle carries `RpcClient<any>` (design spec §4.4) and the concrete definition lives
+    // in `@dxos/functions-runtime`, which depends on this package — importing it would cycle.
+    return host.rpc as unknown as RpcClient.RpcClient<HarnessControlRpcs>;
+  });
+
+const isTerminalProcess = (state: Process.State): boolean =>
+  state === Process.State.SUCCEEDED || state === Process.State.FAILED || state === Process.State.TERMINATED;

package/src/session/SessionLink.ts

@@ -13,11 +13,11 @@ import { DXN, Feed, Obj, Ref, Type } from '@dxos/echo';
  * When present in a feed, the messages from the referenced feed up to and including
  * `messageId` are prepended to the conversation history before each turn.
  */
-export const SessionLink = Schema.Struct({
-  /** Reference to the feed of the source session. */
-  feedRef: Ref.Ref(Feed.Feed),
-  /** Messages from the source feed up to and including this message ID are injected. */
-  messageId: Obj.ID,
-}).pipe(Type.makeObject(DXN.make('org.dxos.type.sessionLink', '0.1.0')));
-
-export type SessionLink = Type.InstanceType<typeof SessionLink>;
+export class SessionLink extends Type.makeObject<SessionLink>(DXN.make('org.dxos.type.sessionLink', '0.1.0'))(
+  Schema.Struct({
+    /** Reference to the feed of the source session. */
+    feedRef: Ref.Ref(Feed.Feed),
+    /** Messages from the source feed up to and including this message ID are injected. */
+    messageId: Obj.ID,
+  }),
+) {}

package/src/session/SessionLoader.ts

@@ -4,7 +4,7 @@
 
 import * as Effect from 'effect/Effect';
 
-import { Feed, Filter, Obj } from '@dxos/echo';
+import { Database, Feed, Filter, Obj } from '@dxos/echo';
 import { Message } from '@dxos/types';
 
 import * as SessionLink from './SessionLink';
@@ -21,9 +21,9 @@ export class SessionLoader {
   reifyHistory(
     feed: Feed.Feed,
     messages: Message.Message[],
-  ): Effect.Effect<Message.Message[], never, Feed.FeedService> {
+  ): Effect.Effect<Message.Message[], never, Database.Service> {
     return Effect.gen(function* () {
-      const links = yield* Feed.runQuery(feed, Filter.type(SessionLink.SessionLink));
+      const links = yield* Feed.query(feed, Filter.type(SessionLink.SessionLink)).run;
       const sessionLinks = links.filter(Obj.instanceOf(SessionLink.SessionLink));
 
       const link = sessionLinks[0];
@@ -36,7 +36,7 @@ export class SessionLoader {
         return messages;
       }
 
-      const sourceMessages = yield* Feed.runQuery(sourceFeed, Filter.type(Message.Message));
+      const sourceMessages = yield* Feed.query(sourceFeed, Filter.type(Message.Message)).run;
       const filtered = sourceMessages.filter(Obj.instanceOf(Message.Message));
 
       // Sort by creation timestamp so history is in chronological order.

package/src/session/SkillHooks.ts

@@ -0,0 +1,71 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Effect from 'effect/Effect';
+
+import { Operation, Skill } from '@dxos/compute';
+import { Database, Obj } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+
+/**
+ * Tag of the lifecycle point a hook fires at, matching {@link Skill.HookSpec}.
+ */
+export type HookPhase = 'begin-request' | 'end-request';
+
+/**
+ * Invokes a resolved operation with the hook's templated input. Begin and end hooks fire in
+ * different contexts (the agent's turn fiber vs. a child process with Tier B reachable), so the
+ * invocation strategy is supplied by the caller rather than fixed here. `R` carries the invoker's
+ * own requirements (e.g. `Operation.Service`) up into {@link runHooks}.
+ */
+export type HookInvoker<R> = (
+  operation: Operation.Definition.Any,
+  input: Record<string, unknown>,
+) => Effect.Effect<void, never, R>;
+
+/**
+ * Runs every {@link Skill.Hook} on `skills` whose spec matches `phase`. Each hook resolves its
+ * `function` ref to a {@link Operation.PersistentOperation}, deserializes it to a definition, and
+ * invokes it with the templated `input` via `invoke`. Hooks without a function ref are skipped.
+ *
+ * Hook failures are isolated: a throwing hook logs and is swallowed so one skill's hook cannot
+ * abort the request lifecycle (or the sibling hooks).
+ */
+export const runHooks = <R>({
+  skills,
+  phase,
+  invoke,
+}: {
+  skills: readonly Skill.Skill[];
+  phase: HookPhase;
+  invoke: HookInvoker<R>;
+}): Effect.Effect<void, never, Database.Service | R> =>
+  Effect.gen(function* () {
+    for (const skill of skills) {
+      for (const hook of skill.hooks ?? []) {
+        if (hook.spec._tag !== phase) {
+          continue;
+        }
+        if (!hook.function) {
+          continue;
+        }
+
+        yield* Effect.gen(function* () {
+          const record = yield* Database.load(hook.function!);
+          invariant(Obj.instanceOf(Operation.PersistentOperation, record), 'Hook function must be an operation.');
+          const operation = Operation.deserialize(record);
+          // Hooks carry no event payload (the spec is a bare tag), so the input template is passed
+          // through verbatim — the hook's operation reads any conversation state it needs itself.
+          yield* invoke(operation, { ...hook.input });
+        }).pipe(
+          Effect.catchAllCause((cause) =>
+            Effect.sync(() => log.warn('skill hook failed', { phase, skill: Skill.getKey(skill), cause })),
+          ),
+        );
+      }
+    }
+  });

package/src/session/harness-control.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Rpc from '@effect/rpc/Rpc';
+import * as RpcGroup from '@effect/rpc/RpcGroup';
+import * as Schema from 'effect/Schema';
+
+import { ContentBlock } from '@dxos/types';
+
+/**
+ * Typed control surface on the live host process that owns a conversation's harness.
+ *
+ * The same group is declared as the agent process's `rpcs` (so its handlers run on the host's
+ * server fiber with the live `AlarmManager`/`inputQueue` in scope) and used by {@link HarnessService}
+ * Tier B to dispatch over the discovered host's `Handle.rpc` — keeping both ends on one contract.
+ */
+export const HarnessControl = RpcGroup.make(
+  Rpc.make('setAlarm', {
+    payload: Schema.Struct({ at: Schema.DateTimeUtc, message: Schema.NullOr(Schema.String) }),
+    success: Schema.Void,
+  }),
+  Rpc.make('enqueueMessage', {
+    payload: Schema.Struct({ content: Schema.Array(ContentBlock.Any) }),
+    success: Schema.Void,
+  }),
+);
+
+/** Union of the RPCs declared in {@link HarnessControl}. */
+export type HarnessControlRpcs = RpcGroup.Rpcs<typeof HarnessControl>;

package/src/session/index.ts

@@ -6,5 +6,8 @@ export * from './toolkit';
 
 export * as AiContext from './AiContext';
 export * as AiSession from './AiSession';
+export * as Harness from './Harness';
+export * as SkillHooks from './SkillHooks';
+export { HarnessControl, type HarnessControlRpcs } from './harness-control';
 export { SessionLoader } from './SessionLoader';
 export * as SessionLink from './SessionLink';