feat(web): compose a web session's agent from a named preset

`session.create` takes an optional `agentPreset`, and the host resolves it, mounts it during pre-publication setup, and records the resolved id on the session header so a later resume rebuilds the same agent. Resolution happens BEFORE the session exists, not inside setup: the session boundary snapshots `meta` before asynchronous setup begins, so an id discovered during setup could never reach the header. Mounting still happens in setup, where a failure rolls the whole creation back rather than publishing a session whose capabilities are half-installed. Resume ignores whatever the request names and rebuilds from the stored id. A resumed session's history was produced under that composition; restoring a different one would replay tool calls the model can no longer make. `dsh-agent-presets` now throws `UnknownPresetError` / `PresetMountError` so the host can tell a bad request from a broken preset — they become `agent-preset-not-found` and `agent-preset-invalid`. Ships the two built-in compositions (`standard`, `core-web`) and the persona row that lets them differ in identity. Nothing mounts them yet: no roster is configured, so `composeAgent` finds no service and every session keeps the host composition. Wiring the roster and moving base's agent-plane rows behind it is the next commit, so the switch happens atomically with a real-composition test.
2026-08-03 22:38:11 +08:00
parent 739042a804
commit 91b55b9245
22 changed files with 458 additions and 39 deletions
@@ -1865,7 +1865,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'CreateAgentOptions',
-    declaration: 'export interface CreateAgentOptions {\n    readonly sessionId: SessionId;\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly origin?: \'subagent\';\n        readonly delegationDepth?: number;\n    };\n    readonly seed?: readonly SessionEvent[];\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: AgentSetup;\n}',
+    declaration: 'export interface CreateAgentOptions {\n    readonly sessionId: SessionId;\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly origin?: \'subagent\';\n        readonly delegationDepth?: number;\n        readonly agentPreset?: string;\n    };\n    readonly seed?: readonly SessionEvent[];\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: AgentSetup;\n}',
  },
  {
    name: 'CreateGoalRequest',
@@ -1873,7 +1873,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'CreateSessionOptions',
-    declaration: 'export interface CreateSessionOptions {\n    readonly seed?: readonly SessionEvent[];\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly createdAt?: number;\n        readonly seedLength?: number;\n        readonly origin?: \'subagent\';\n        readonly delegationDepth?: number;\n    };\n}',
+    declaration: 'export interface CreateSessionOptions {\n    readonly seed?: readonly SessionEvent[];\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly createdAt?: number;\n        readonly seedLength?: number;\n        readonly origin?: \'subagent\';\n        readonly delegationDepth?: number;\n        readonly agentPreset?: string;\n    };\n}',
  },
  {
    name: 'CredentialInfo',
@@ -2525,7 +2525,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'SessionHeader',
-    declaration: 'export interface SessionHeader {\n    readonly version: number;\n    readonly id: SessionId;\n    readonly createdAt: number;\n    readonly cwd?: string;\n    readonly parentSession?: SessionId;\n    readonly seedLength?: number;\n    readonly origin?: \'subagent\';\n    readonly delegationDepth?: number;\n}',
+    declaration: 'export interface SessionHeader {\n    readonly version: number;\n    readonly id: SessionId;\n    readonly createdAt: number;\n    readonly cwd?: string;\n    readonly parentSession?: SessionId;\n    readonly seedLength?: number;\n    readonly origin?: \'subagent\';\n    readonly delegationDepth?: number;\n    readonly agentPreset?: string;\n}',
  },
  {
    name: 'SessionId',
@@ -84,6 +84,7 @@ export interface CreateAgentOptions {
    readonly seedLength?: number
    readonly origin?: 'subagent'
    readonly delegationDepth?: number
+    readonly agentPreset?: string
  }
  /**
   * Initial replay/fork history. A fork supplies a balanced completed-turn
@@ -142,6 +142,9 @@ function validateSessionHeader(id: SessionId, input: unknown): SessionHeader {
    && (typeof record.delegationDepth !== 'number' || !Number.isSafeInteger(record.delegationDepth) || record.delegationDepth < 0)) {
    throw new Error('session header delegationDepth must be a non-negative safe integer')
  }
+  if (record.agentPreset !== undefined && typeof record.agentPreset !== 'string') {
+    throw new Error('session header agentPreset must be a string')
+  }
  return deepFreeze(record as unknown as SessionHeader)
 }

@@ -882,6 +885,7 @@ export class SessionStore extends Service {
      ...meta?.seedLength === undefined ? {} : { seedLength: meta.seedLength },
      ...meta?.origin === undefined ? {} : { origin: meta.origin },
      ...meta?.delegationDepth === undefined ? {} : { delegationDepth: meta.delegationDepth },
+      ...meta?.agentPreset === undefined ? {} : { agentPreset: meta.agentPreset },
    }
    return Session.create(sessionId, seed, header)
  }
@@ -69,6 +69,13 @@ export interface SessionHeader {
   * resume — a runtime-only depth would reset a resumed child to top-level.
   */
  readonly delegationDepth?: number
+  /**
+   * Id of the agent preset this session's agent was composed from, when the
+   * deployment composes per session. Durable because the preset decides the
+   * session's tools and prompt: a resume that restored a different composition
+   * would replay history the model can no longer act on.
+   */
+  readonly agentPreset?: string
 }

 /**
@@ -90,6 +97,7 @@ export interface CreateSessionOptions {
    readonly seedLength?: number
    readonly origin?: 'subagent'
    readonly delegationDepth?: number
+    readonly agentPreset?: string
  }
 }

@@ -63,13 +63,15 @@
    "zod": "^4.4.3"
  },
  "peerDependencies": {
-    "cordis": "^4.0.0-rc.7",
-    "@deepseek-ai/dsh-invariants": "^0.0.1"
+    "@deepseek-ai/dsh-agent-presets": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
+    "@deepseek-ai/dsh-agent-presets": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-storage": "workspace:^",
    "@deepseek-ai/dsh-storage-domain": "workspace:^",
-    "cordis": "^4.0.0-rc.7",
-    "@deepseek-ai/dsh-invariants": "workspace:^"
+    "cordis": "^4.0.0-rc.7"
  }
 }
@@ -24,6 +24,7 @@ import {
  WorkspaceMoveInvalidError, WorkspaceUnknownSessionError,
 } from '@deepseek-ai/dsh-workspace'
 // Type-only: brings the `ctx.tools` Context merge into this program (viewFor reads presenters).
+import { PresetMountError, UnknownPresetError } from '@deepseek-ai/dsh-agent-presets'
 import type {} from '@deepseek-ai/dsh-tools'
 import type {
  ApiProxy, CredentialView, GoalRef, HistoryEntry, HostFrame, ModelCatalogFailure, ModelProviderGroup,
@@ -744,6 +745,45 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
    targetFor(agent)
  }

+  /**
+   * Resolve the preset an agent will be composed from, and the setup that
+   * installs it.
+   *
+   * The id is resolved BEFORE the session exists because the session boundary
+   * snapshots `meta` before asynchronous setup begins — a preset discovered
+   * during setup could never reach the header. Mounting still happens in
+   * setup, where a failure rolls the whole creation back rather than leaving a
+   * published session whose capabilities are half-installed.
+   *
+   * A deployment with no preset roster composes nothing and every session
+   * shares the host composition, which is the behavior before presets existed.
+   * @param presetId - the requested preset, or `undefined` for the default.
+   * @returns the id to record on the header (absent without a roster) and the setup callback.
+   * @throws when the roster supplies no such preset.
+   */
+  async function composeAgent(presetId: string | undefined): Promise<{
+    agentPreset?: string
+    setup: (agentCtx: Context) => Promise<void>
+  }> {
+    const presets = ctx.get('agentPresets')
+    if (presets === undefined) {
+      return {
+        setup: (agentCtx: Context) => {
+          installTarget(agentCtx)
+          return Promise.resolve()
+        },
+      }
+    }
+    const resolvedId = (await presets.resolve(presetId)).id
+    return {
+      agentPreset: resolvedId,
+      setup: async (agentCtx: Context) => {
+        installTarget(agentCtx)
+        await presets.mount(agentCtx, resolvedId)
+      },
+    }
+  }
+
  /** Send one transient frame to every connected mux consumer. */
  function broadcast(payload: MuxFrame): void {
    const envelope = frame(payload)
@@ -1101,7 +1141,12 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
  }

  /** Resolve one requested identity to a live agent, creating or resuming it once. */
-  async function ensureSession(sessionId: SessionId, cwd: string, checkPersistedIdentity: boolean): Promise<Agent> {
+  async function ensureSession(
+    sessionId: SessionId,
+    cwd: string,
+    checkPersistedIdentity: boolean,
+    presetId?: string,
+  ): Promise<Agent> {
    let creation = sessionCreations.get(sessionId)
    if (creation === undefined) {
      creation = (async () => {
@@ -1127,10 +1172,14 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
          if (inspected.meta.cwd !== cwd) {
            throw new SessionCwdConflict(sessionId, cwd, inspected.meta.cwd)
          }
+          // The stored preset wins over anything the request names: a resumed
+          // session's history was produced under that composition, and
+          // rebuilding it differently would replay tool calls the model can no
+          // longer make.
          return (await ctx.agents.resume({
            resumeSessionId: sessionId,
            agentOptions,
-            setup: installTarget,
+            setup: (await composeAgent(inspected.meta.agentPreset)).setup,
          })).agent
        }

@@ -1139,11 +1188,15 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
        } catch (error: unknown) {
          throw new Error(`failed to ensure project directory "${cwd}": ${String(error)}`, { cause: error })
        }
+        const composition = await composeAgent(presetId)
        return (await ctx.agents.create({
          sessionId,
          agentOptions,
-          meta: { cwd },
-          setup: installTarget,
+          meta: {
+            cwd,
+            ...composition.agentPreset === undefined ? {} : { agentPreset: composition.agentPreset },
+          },
+          setup: composition.setup,
        })).agent
      })().catch((error: unknown) => {
        // Another Host entry path may have published the same identity while
@@ -1592,9 +1645,24 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
          }
        }
        const cwd = workspace?.path ?? request.payload.cwd ?? defaults.cwd
+        const requestedPreset = request.payload.agentPreset
        try {
-          await ensureSession(sessionId, cwd, request.payload.sessionId !== undefined)
+          await ensureSession(sessionId, cwd, request.payload.sessionId !== undefined, requestedPreset)
        } catch (error: unknown) {
+          if (error instanceof UnknownPresetError) {
+            return err(request, {
+              code: 'agent-preset-not-found',
+              message: error.message,
+              details: { agentPreset: error.presetId, available: [...error.available] },
+            })
+          }
+          if (error instanceof PresetMountError) {
+            return err(request, {
+              code: 'agent-preset-invalid',
+              message: error.message,
+              details: { agentPreset: error.presetId, reason: error.reason },
+            })
+          }
          if (error instanceof SessionCwdConflict) {
            return err(request, {
              code: 'session-conflict',
@@ -46,6 +46,8 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
  z.object({ code: z.literal('directory-exists'), message: z.string(), details: z.object({ path: z.string() }) }),
  z.object({ code: z.literal('directory-create-failed'), message: z.string(), details: z.object({ path: z.string() }) }),
  z.object({ code: z.literal('directory-picker-unavailable'), message: z.string(), details: z.object({ capability: z.string() }) }),
+  z.object({ code: z.literal('agent-preset-not-found'), message: z.string(), details: z.object({ agentPreset: z.string(), available: z.array(z.string()) }) }),
+  z.object({ code: z.literal('agent-preset-invalid'), message: z.string(), details: z.object({ agentPreset: z.string(), reason: z.string() }) }),
  z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
  z.object({ code: z.literal('queue-item-not-found'), message: z.string(), details: z.object({ itemId: z.string() }) }),
  z.object({ code: z.literal('steer-unavailable'), message: z.string(), details: z.object({ itemId: z.string() }) }),
@@ -44,6 +44,8 @@ export interface RpcErrorDetailsMap {
  'directory-exists': { path: string }
  'directory-create-failed': { path: string }
  'directory-picker-unavailable': { capability: string }
+  'agent-preset-not-found': { agentPreset: string; available: string[] }
+  'agent-preset-invalid': { agentPreset: string; reason: string }
  'agent-busy': { reason: string }
  'queue-item-not-found': { itemId: MessageId }
  'steer-unavailable': { itemId: MessageId }
@@ -100,6 +100,7 @@ export const sessionCreateRequestSchema = z.object({
  workspaceId: workspaceIdSchema.optional(),
  cwd: z.string().optional(),
  sessionId: sessionIdSchema.optional(),
+  agentPreset: z.string().optional(),
 }).refine(
  payload => payload.workspaceId === undefined || payload.cwd === undefined,
  { message: 'session.create accepts workspaceId or cwd, not both' },
@@ -199,8 +199,14 @@ export interface SessionsApi {
   * session, while a different cwd fails with `session-conflict`. Workspace
   * creation attaches the session after publication; an attach failure
   * returns `workspace-attach-failed` with the published session id.
+   *
+   * `agentPreset` names the composition the new session's agent is built
+   * from; omitted, the deployment's default preset applies. The resolved id
+   * is stored on the session header, so a later resume rebuilds the same
+   * agent. An unknown id fails with `agent-preset-not-found`, and a preset
+   * whose composition cannot be mounted fails with `agent-preset-invalid`.
   */
-  create(request: RpcRequest<{ workspaceId?: WorkspaceId; cwd?: string; sessionId?: SessionId }>):
+  create(request: RpcRequest<{ workspaceId?: WorkspaceId; cwd?: string; sessionId?: SessionId; agentPreset?: string }>):
  Promise<RpcResponse<{ sessionId: SessionId }>>

  /**
@@ -32,6 +32,9 @@
    {
      "path": "../../core/agent"
    },
+    {
+      "path": "../../preset/agent-presets"
+    },
    {
      "path": "../../core/session"
    },
@@ -14,10 +14,11 @@ import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import { discoverPresets } from './discovery.ts'
 import { mountPreset } from './mount.ts'
-import type { AgentPreset, Config } from './types.ts'
+import { UnknownPresetError, type AgentPreset, type Config } from './types.ts'

 export { COMPOSITION_FILE, discoverPresets, scanRoot } from './discovery.ts'
 export { inactiveRows, leakedServices, livePresetMounts, mountPreset, type PresetMount } from './mount.ts'
+export { PresetMountError, UnknownPresetError } from './types.ts'
 export type { AgentPreset, Config, PresetRoot, PresetTrust } from './types.ts'

 declare module 'cordis' {
@@ -73,8 +74,7 @@ export class AgentPresets extends Service {
    const presets = await this.list()
    const found = presets.find(preset => preset.id === wanted)
    if (found === undefined) {
-      const known = presets.map(preset => preset.id).join(', ')
-      throw new Error(`agent-presets: preset "${wanted}" not found (available: ${known || 'none'})`)
+      throw new UnknownPresetError(wanted, presets.map(preset => preset.id))
    }
    return found
  }
@@ -19,7 +19,7 @@ import { Context, type Fiber } from 'cordis'
 import { Include } from '@cordisjs/plugin-include'
 import type { EntryTree } from '@cordisjs/plugin-loader'
 import { scopeOf } from '@deepseek-ai/dsh-scope'
-import type { AgentPreset } from './types.ts'
+import { PresetMountError, type AgentPreset } from './types.ts'

 /** What one mounted subtree publishes about itself for the audit to read. */
 interface MountedTree {
@@ -221,6 +221,6 @@ export async function mountPreset(agentCtx: Context, preset: AgentPreset): Promi
       wraps a row's thrown value before it propagates, and this module's own
       rejections are Errors. The fallback keeps a hostile value readable. */
    const detail = error instanceof Error ? error.message : String(error)
-    throw new Error(`agent-presets: preset "${preset.id}" (${preset.path}) failed to mount: ${detail}`, { cause: error })
+    throw new PresetMountError(preset.id, `${detail} (${preset.path})`, { cause: error })
  }
 }
@@ -32,3 +32,34 @@ export interface Config {
  /** Scanned roots in precedence order; an earlier root wins a duplicate id. */
  roots: PresetRoot[]
 }
+
+/**
+ * No configured root supplies the requested preset.
+ *
+ * Separate from a mount failure because the two mean different things to a
+ * caller: an unknown id is a bad request, while an unusable composition is a
+ * broken preset the deployment must fix.
+ */
+export class UnknownPresetError extends Error {
+  constructor(
+    /** The id that was requested. */
+    readonly presetId: string,
+    /** Ids the roster does supply, for the caller to offer instead. */
+    readonly available: readonly string[],
+  ) {
+    super(`agent-presets: preset "${presetId}" not found (available: ${available.join(', ') || 'none'})`)
+  }
+}
+
+/** A preset exists but its composition cannot be installed. */
+export class PresetMountError extends Error {
+  constructor(
+    /** The preset whose composition failed. */
+    readonly presetId: string,
+    /** Why it failed, without this package's own message prefix. */
+    readonly reason: string,
+    options?: ErrorOptions,
+  ) {
+    super(`agent-presets: preset "${presetId}" failed to mount: ${reason}`, options)
+  }
+}