@electric-ax/agents-server 0.4.13 → 0.4.15

package/src/entity-registry.ts

@@ -26,6 +26,7 @@ import type {
   EntityStatus,
   RunnerAdminStatus,
   RunnerKind,
+  SandboxProfileAdvertisement,
   SourceStreamOffset,
   ConsumerClaim,
   DispatchPolicy,
@@ -80,6 +81,13 @@ export interface RegisterRunnerInput {
   kind?: RunnerKind
   adminStatus?: RunnerAdminStatus
   wakeStream?: string
+  /**
+   * Full-set replacement: provide the complete list of profiles the
+   * runner currently exposes. Existing rows for the runner are
+   * removed and the supplied set is inserted in one transaction.
+   * Omit (or pass undefined) to leave the existing set untouched.
+   */
+  sandboxProfiles?: ReadonlyArray<SandboxProfileAdvertisement>
 }
 
 export interface HeartbeatRunnerInput {
@@ -148,6 +156,17 @@ export class PostgresRegistry {
   ): Promise<ElectricAgentsRunner> {
     const now = new Date()
     const wakeStream = input.wakeStream ?? runnerWakeStream(input.id)
+    // Full-set replace: when the caller provides a profile list it
+    // overwrites whatever the runner previously advertised. Omitting
+    // the field on a re-registration preserves the existing value.
+    const sandboxProfilesValue = input.sandboxProfiles
+      ? input.sandboxProfiles.map((p) => ({
+          name: p.name,
+          label: p.label,
+          ...(p.description !== undefined && { description: p.description }),
+          ...(p.remote !== undefined && { remote: p.remote }),
+        }))
+      : undefined
 
     await this.db
       .insert(runners)
@@ -159,6 +178,9 @@ export class PostgresRegistry {
         kind: input.kind ?? `local`,
         adminStatus: input.adminStatus ?? `enabled`,
         wakeStream,
+        ...(sandboxProfilesValue !== undefined && {
+          sandboxProfiles: sandboxProfilesValue,
+        }),
         updatedAt: now,
       })
       .onConflictDoUpdate({
@@ -169,6 +191,9 @@ export class PostgresRegistry {
           kind: input.kind ?? `local`,
           adminStatus: input.adminStatus ?? `enabled`,
           wakeStream,
+          ...(sandboxProfilesValue !== undefined && {
+            sandboxProfiles: sandboxProfilesValue,
+          }),
           updatedAt: now,
         },
       })
@@ -180,6 +205,44 @@ export class PostgresRegistry {
     return runner
   }
 
+  /**
+   * Every sandbox profile advertised by a runner in this tenant (one entry
+   * per runner that advertises it — names may repeat across runners). Used by
+   * spawn validation for unpinned dispatch to learn whether a chosen profile
+   * is remote (so a shared sandbox can skip the single-runner guard).
+   */
+  async listSandboxProfiles(): Promise<Array<SandboxProfileAdvertisement>> {
+    const rows = await this.db
+      .select({ sandboxProfiles: runners.sandboxProfiles })
+      .from(runners)
+      .where(eq(runners.tenantId, this.tenantId))
+    const profiles: Array<SandboxProfileAdvertisement> = []
+    for (const row of rows) {
+      const list = row.sandboxProfiles as
+        | Array<{
+            name?: unknown
+            label?: unknown
+            description?: unknown
+            remote?: unknown
+          }>
+        | null
+        | undefined
+      if (!Array.isArray(list)) continue
+      for (const entry of list) {
+        if (!entry || typeof entry.name !== `string`) continue
+        profiles.push({
+          name: entry.name,
+          label: typeof entry.label === `string` ? entry.label : entry.name,
+          ...(typeof entry.description === `string` && {
+            description: entry.description,
+          }),
+          ...(typeof entry.remote === `boolean` && { remote: entry.remote }),
+        })
+      }
+    }
+    return profiles
+  }
+
   async getRunner(id: string): Promise<ElectricAgentsRunner | null> {
     const rows = await this.db
       .select()
@@ -613,6 +676,7 @@ export class PostgresRegistry {
             tags: normalizeTags(entity.tags),
             tagsIndex: buildTagsIndex(entity.tags),
             spawnArgs: entity.spawn_args ?? {},
+            sandbox: entity.sandbox ?? null,
             parent: entity.parent ?? null,
             createdBy: entity.created_by ?? null,
             typeRevision: entity.type_revision ?? null,
@@ -1223,6 +1287,8 @@ export class PostgresRegistry {
       write_token: row.writeToken,
       tags: (row.tags as EntityTags | null | undefined) ?? {},
       spawn_args: row.spawnArgs as Record<string, unknown> | undefined,
+      sandbox:
+        (row.sandbox as ElectricAgentsEntity[`sandbox`] | null) ?? undefined,
       parent: row.parent ?? undefined,
       created_by: row.createdBy ?? undefined,
       type_revision: row.typeRevision ?? undefined,
@@ -1295,6 +1361,13 @@ export class PostgresRegistry {
       kind: assertRunnerKind(row.kind),
       admin_status: assertRunnerAdminStatus(row.adminStatus),
       wake_stream: row.wakeStream,
+      sandbox_profiles:
+        (row.sandboxProfiles as Array<{
+          name: string
+          label: string
+          description?: string
+          remote?: boolean
+        }> | null) ?? [],
       created_at: row.createdAt.toISOString(),
       updated_at: row.updatedAt.toISOString(),
     }

package/src/routing/entities-router.ts

@@ -11,6 +11,7 @@ import { Router, json, status } from 'itty-router'
 import { apiError } from '../electric-agents-http.js'
 import { parsePrincipalKey, principalUrl } from '../principal.js'
 import { dispatchPolicySchema } from '../dispatch-policy-schema.js'
+import { sandboxChoiceSchema } from '../sandbox-choice-schema.js'
 import {
   ErrCodeNotFound,
   ErrCodeUnknownEntityType,
@@ -82,6 +83,7 @@ const spawnBodySchema = Type.Object({
   tags: Type.Optional(stringRecordSchema),
   parent: Type.Optional(Type.String()),
   dispatch_policy: Type.Optional(dispatchPolicySchema),
+  sandbox: Type.Optional(sandboxChoiceSchema),
   initialMessage: Type.Optional(Type.Unknown()),
   wake: Type.Optional(
     Type.Object({
@@ -135,6 +137,15 @@ const inboxMessageBodySchema = Type.Object({
 const forkBodySchema = Type.Object({
   instance_id: Type.Optional(Type.String()),
   waitTimeoutMs: Type.Optional(Type.Number()),
+  // Optional anchor pointing at an event on the source root's `main`
+  // stream. Wire shape is snake_case; the route handler translates to
+  // camelCase before forwarding to entity-manager.
+  fork_pointer: Type.Optional(
+    Type.Object({
+      offset: Type.Union([Type.String(), Type.Null()]),
+      sub_offset: Type.Number(),
+    })
+  ),
 })
 
 const setTagBodySchema = Type.Object({
@@ -794,6 +805,12 @@ async function forkEntity(
   const result = await ctx.entityManager.forkSubtree(entityUrl, {
     rootInstanceId: parsed.instance_id,
     waitTimeoutMs: parsed.waitTimeoutMs,
+    ...(parsed.fork_pointer && {
+      forkPointer: {
+        offset: parsed.fork_pointer.offset,
+        subOffset: parsed.fork_pointer.sub_offset,
+      },
+    }),
   })
   for (const forkedEntity of result.entities) {
     await linkEntityDispatchSubscription(ctx, forkedEntity)
@@ -969,6 +986,7 @@ async function spawnEntity(
     tags: parsed.tags,
     parent: parsed.parent,
     dispatch_policy: dispatchPolicy,
+    sandbox: parsed.sandbox,
     initialMessage: undefined,
     wake: parsed.wake,
     created_by: principal.url,

package/src/routing/runners-router.ts

@@ -34,6 +34,13 @@ export type RunnersRoutes = RouterType<
   RunnersRouteResult
 >
 
+const sandboxProfileBodySchema = Type.Object({
+  name: Type.String(),
+  label: Type.String(),
+  description: Type.Optional(Type.String()),
+  remote: Type.Optional(Type.Boolean()),
+})
+
 const registerRunnerBodySchema = Type.Object({
   id: Type.String(),
   owner_principal: Type.Optional(Type.String()),
@@ -51,6 +58,7 @@ const registerRunnerBodySchema = Type.Object({
     Type.Union([Type.Literal(`enabled`), Type.Literal(`disabled`)])
   ),
   wake_stream: Type.Optional(Type.String()),
+  sandbox_profiles: Type.Optional(Type.Array(sandboxProfileBodySchema)),
 })
 
 const heartbeatBodySchema = Type.Object({
@@ -234,6 +242,7 @@ async function registerRunner(
     kind: parsed.kind,
     adminStatus: parsed.admin_status,
     wakeStream: parsed.wake_stream,
+    sandboxProfiles: parsed.sandbox_profiles,
   })
   await ctx.streamClient.ensure(runner.wake_stream, {
     contentType: `application/json`,
@@ -639,6 +648,7 @@ async function notificationFromClaim(
       streams: entity.streams,
       tags: entity.tags,
       spawnArgs: entity.spawn_args,
+      sandbox: entity.sandbox,
       createdBy: entity.created_by,
     },
     principal: principalFromCreatedBy(entity.created_by),

package/src/routing/sandbox.ts

@@ -0,0 +1,173 @@
+import { ElectricAgentsError } from '../entity-manager.js'
+import { ErrCodeInvalidRequest } from '../electric-agents-types.js'
+import type {
+  DispatchPolicy,
+  ElectricAgentsEntity,
+  EntitySandboxSelection,
+  SandboxChoice,
+} from '../electric-agents-types.js'
+import type { PostgresRegistry } from '../entity-registry.js'
+
+/**
+ * Resolve and validate a spawn's sandbox CHOICE into the {@link
+ * EntitySandboxSelection} persisted on the entity. Sibling of
+ * `dispatch-policy.ts`'s `resolveEffectiveDispatchPolicyForSpawn`: kept off the
+ * EntityManager so the spawn path reads as composed resolution steps.
+ *
+ * Profiles are a per-runner concern: each runner advertises what it supports.
+ * When the spawn pins a runner via dispatch_policy, the chosen profile must be
+ * in that runner's advertised set; otherwise we'd persist an unserviceable
+ * choice that fails late at first wake. For unpinned dispatch (webhook /
+ * parent-inherited) we can't pick a target ahead of time, so we fall back to a
+ * tenant-wide "some runner offers this" check — better than nothing.
+ */
+export async function resolveSandboxForSpawn(
+  registry: PostgresRegistry,
+  dispatchPolicy: DispatchPolicy | undefined,
+  requested: SandboxChoice | undefined,
+  parentEntity: ElectricAgentsEntity | null
+): Promise<EntitySandboxSelection | undefined> {
+  if (!requested) return undefined
+
+  const choice = applyInheritedSandbox(requested, parentEntity)
+  // `inherit` against a parent with no shareable (keyed) sandbox yields none.
+  if (!choice) return undefined
+
+  const chosenName = choice.profile
+  if (!chosenName) {
+    throw new ElectricAgentsError(
+      ErrCodeInvalidRequest,
+      `sandbox requires a "profile" (or "inherit": true with a parent that has a shared sandbox).`,
+      400
+    )
+  }
+
+  const chosenIsRemote = await resolveChosenProfileRemote(
+    registry,
+    chosenName,
+    dispatchPolicy
+  )
+
+  assertSharedSandboxColocated(choice.key, chosenIsRemote, dispatchPolicy)
+
+  // Persist the selection. Only an explicit/inherited `key` is stored (it's
+  // cross-entity, so the guard above applies); a `scope` is kept so the wake
+  // can derive the key, but no `key` is stored for it — leaving the
+  // co-location guard correctly keyed on genuine cross-entity sharing.
+  const selection: EntitySandboxSelection = { profile: chosenName }
+  if (choice.key !== undefined) selection.key = choice.key
+  else if (choice.scope !== undefined) selection.scope = choice.scope
+  if (choice.persistent !== undefined) selection.persistent = choice.persistent
+  // Store ownership only when this entity is an attacher; owner is the
+  // default, so it's left implicit (the wake resolver defaults to owner).
+  if (choice.owner === false) selection.owner = false
+  return selection
+}
+
+/**
+ * Resolve `inherit` against the parent's *stored* sandbox. `inherit` reuses the
+ * parent's keyed sandbox as a non-owner (attach-only). It's graceful: if the
+ * parent has no shareable (keyed) sandbox the child simply gets none (returns
+ * `undefined`), so `spawn_worker` can always request inheritance without
+ * breaking unkeyed parents. (A running parent wake resolves inherit to its live
+ * explicit key in the runtime instead — this server-side path covers direct API
+ * callers, where only the parent's *stored* explicit key is available.)
+ *
+ * For a non-inherit choice the request passes through unchanged.
+ *
+ * NOTE: `inherit: true` takes the parent's identity AND durability wholesale —
+ * any sibling field on the request (e.g. a caller-supplied `persistent: false`)
+ * is intentionally ignored, because a child attaches to the parent's existing
+ * sandbox and cannot change how that sandbox is torn down. `sandboxChoiceSchema`
+ * permits the `{ inherit: true, persistent: ... }` combination, so the
+ * precedence is resolved here rather than rejected at the schema level.
+ */
+function applyInheritedSandbox(
+  requested: SandboxChoice,
+  parentEntity: ElectricAgentsEntity | null
+): SandboxChoice | undefined {
+  if (!requested.inherit) return requested
+  const parentKey = parentEntity?.sandbox?.key
+  if (!parentKey) return undefined
+  return {
+    profile: parentEntity!.sandbox!.profile,
+    key: parentKey,
+    // Adopt the parent's durability; an explicit key has no scope. The child
+    // attaches to (never owns) the parent's sandbox.
+    persistent: parentEntity!.sandbox!.persistent,
+    owner: false,
+  }
+}
+
+/**
+ * Validate the chosen profile is advertised by the relevant runner(s) and
+ * determine whether it is a remote (off-host) sandbox, reachable from any
+ * runner. Defaults to host-local (co-location required) unless every relevant
+ * advertisement marks it remote. Throws if the profile is unserviceable.
+ */
+async function resolveChosenProfileRemote(
+  registry: PostgresRegistry,
+  chosenName: string,
+  dispatchPolicy: DispatchPolicy | undefined
+): Promise<boolean> {
+  const runnerIds: Array<string> = []
+  for (const target of dispatchPolicy?.targets ?? []) {
+    if (target.type === `runner`) runnerIds.push(target.runnerId)
+  }
+
+  if (runnerIds.length > 0) {
+    let allRemote = true
+    for (const runnerId of runnerIds) {
+      const runner = await registry.getRunner(runnerId)
+      const advertised = runner?.sandbox_profiles ?? []
+      const match = advertised.find((p) => p.name === chosenName)
+      if (!match) {
+        throw new ElectricAgentsError(
+          ErrCodeInvalidRequest,
+          `sandbox profile "${chosenName}" is not advertised by runner "${runnerId}" (advertised: ${advertised.map((p) => p.name).join(`, `) || `(none)`}).`,
+          400
+        )
+      }
+      if (match.remote !== true) allRemote = false
+    }
+    return allRemote
+  }
+
+  const available = await registry.listSandboxProfiles()
+  const matches = available.filter((p) => p.name === chosenName)
+  if (matches.length === 0) {
+    throw new ElectricAgentsError(
+      ErrCodeInvalidRequest,
+      `sandbox profile "${chosenName}" is not offered by any registered runner (available: ${[...new Set(available.map((p) => p.name))].join(`, `) || `(none)`}).`,
+      400
+    )
+  }
+  // Only skip the co-location guard when every advertiser of this name is
+  // remote — a same-named host-local profile on another runner could
+  // otherwise land a collaborator on the wrong host.
+  return matches.every((p) => p.remote === true)
+}
+
+/**
+ * Co-location: a shared *local* sandbox lives on one host, so every
+ * collaborator must be pinned to the same single runner. Subagents inherit the
+ * parent's dispatch policy, so this holds once the root is pinned. A shared
+ * *remote* sandbox is reachable from any runner, so the guard does not apply.
+ */
+function assertSharedSandboxColocated(
+  key: string | undefined,
+  chosenIsRemote: boolean,
+  dispatchPolicy: DispatchPolicy | undefined
+): void {
+  if (key === undefined || chosenIsRemote) return
+  const targets = dispatchPolicy?.targets ?? []
+  const pinnedToSingleRunner =
+    targets.length === 1 && targets[0]?.type === `runner`
+  if (!pinnedToSingleRunner) {
+    throw new ElectricAgentsError(
+      ErrCodeInvalidRequest,
+      `a shared sandbox (sandbox.key / sandbox.inherit) requires the entity to be pinned to a single runner via dispatch_policy, so all collaborators share one host.`,
+      400
+    )
+  }
+}

package/src/sandbox-choice-schema.ts

@@ -0,0 +1,28 @@
+import { Type } from '@sinclair/typebox'
+
+/**
+ * Wire schema for a spawn-time sandbox CHOICE (the request input), as opposed to
+ * the resolved {@link import('./electric-agents-types.js').EntitySandboxSelection}
+ * persisted on the entity. The matching `SandboxChoice` type is hand-maintained
+ * in `electric-agents-types.ts` — mirrors how `dispatchPolicySchema` pairs with
+ * the `DispatchPolicy` type in `dispatch-policy-schema.ts`.
+ *
+ * Validation happens once, at the router boundary (this schema is embedded in
+ * the spawn body schema); the spawn resolver consumes already-validated input,
+ * so there is intentionally no separate `parse` helper here.
+ */
+export const sandboxChoiceSchema = Type.Object({
+  profile: Type.Optional(Type.String()),
+  // Explicit cross-entity identity — entities with the same key collaborate on
+  // one workspace. `inherit` reuses the parent entity's resolved sandbox.
+  key: Type.Optional(Type.String()),
+  // Identity scope when no explicit `key`: per-entity (default) or per-wake.
+  scope: Type.Optional(
+    Type.Union([Type.Literal(`entity`), Type.Literal(`wake`)])
+  ),
+  // Idle-teardown durability; defaults by scope when unset.
+  persistent: Type.Optional(Type.Boolean()),
+  // Whether this entity owns the sandbox (default) or only attaches to one.
+  owner: Type.Optional(Type.Boolean()),
+  inherit: Type.Optional(Type.Boolean()),
+})

package/src/stream-client.ts

@@ -4,6 +4,7 @@ import {
   FetchError,
   IdempotentProducer,
 } from '@durable-streams/client'
+import type { EventPointer } from '@electric-ax/agents-runtime'
 import { ErrCodeNotFound } from './electric-agents-types.js'
 import { ATTR, injectTraceHeaders, withSpan } from './tracing.js'
 import type { HeadersRecord, MaybePromise } from '@durable-streams/client'
@@ -242,7 +243,11 @@ export class StreamClient {
     })
   }
 
-  async fork(path: string, sourcePath: string): Promise<void> {
+  async fork(
+    path: string,
+    sourcePath: string,
+    opts?: { forkPointer?: EventPointer }
+  ): Promise<void> {
     return await withSpan(`stream.fork`, async (span) => {
       span.setAttributes({
         [ATTR.STREAM_PATH]: path,
@@ -252,6 +257,17 @@ export class StreamClient {
         'content-type': `application/json`,
         'Stream-Forked-From': new URL(this.streamUrl(sourcePath)).pathname,
       }
+      if (opts?.forkPointer) {
+        // The durable-streams server returns 400 if Stream-Fork-Sub-Offset
+        // > 0 without an accompanying Stream-Fork-Offset. When our
+        // pointer's offset is `null` (anchor at stream start), send the
+        // explicit zero-offset string to satisfy that constraint.
+        const ZERO_OFFSET = `0000000000000000_0000000000000000`
+        headers[`Stream-Fork-Offset`] = opts.forkPointer.offset ?? ZERO_OFFSET
+        if (opts.forkPointer.subOffset > 0) {
+          headers[`Stream-Fork-Sub-Offset`] = String(opts.forkPointer.subOffset)
+        }
+      }
       injectTraceHeaders(headers)
 
       const response = await fetch(this.streamUrl(path), {

package/src/utils/log.ts

@@ -8,62 +8,73 @@ const USE_FILE_LOGS = process.env.ELECTRIC_AGENTS_LOG_FILE !== `false`
 const USE_PRETTY_LOGS =
   LOG_LEVEL !== `silent` && !process.env.VITEST && !IS_ELECTRON_MAIN
 
-const LOG_DIR = USE_FILE_LOGS
-  ? (process.env.ELECTRIC_AGENTS_LOG_DIR ?? path.resolve(process.cwd(), `logs`))
-  : undefined
-const LOG_FILE = LOG_DIR
-  ? path.join(LOG_DIR, `agent-server-${Date.now()}.jsonl`)
-  : undefined
+let _logger: pino.Logger | undefined
 
-if (LOG_DIR) {
-  fs.mkdirSync(LOG_DIR, { recursive: true })
-}
+function getLogger(): pino.Logger {
+  if (_logger) return _logger
 
-export const LOG_FILE_PATH = LOG_FILE
+  const streams: Array<pino.StreamEntry> = []
 
-const streams: Array<pino.StreamEntry> = []
-if (LOG_FILE) {
-  streams.push({
-    stream: pino.destination({
-      dest: LOG_FILE,
-      sync: IS_ELECTRON_MAIN,
-    }),
-  })
-}
-if (USE_PRETTY_LOGS) {
-  streams.push({
-    stream: pino.transport({
-      target: `pino-pretty`,
-      options: {
-        colorize: true,
-        ignore: `pid,hostname,name`,
-        translateTime: `SYS:HH:MM:ss`,
-      },
-    }),
-  })
-}
+  try {
+    if (USE_FILE_LOGS) {
+      const logDir =
+        process.env.ELECTRIC_AGENTS_LOG_DIR ??
+        path.resolve(process.cwd(), `logs`)
+      fs.mkdirSync(logDir, { recursive: true })
+      const logFile = path.join(logDir, `agent-server-${Date.now()}.jsonl`)
+      streams.push({
+        stream: pino.destination({
+          dest: logFile,
+          sync: IS_ELECTRON_MAIN,
+        }),
+      })
+    }
+  } catch (err) {
+    process.stderr.write(
+      `[agents-server] Failed to initialize file logging: ${err instanceof Error ? err.message : err}\n`
+    )
+  }
 
-const logger =
-  streams.length > 0
-    ? pino(
-        {
+  try {
+    if (USE_PRETTY_LOGS) {
+      streams.push({
+        stream: pino.transport({
+          target: `pino-pretty`,
+          options: {
+            colorize: true,
+            ignore: `pid,hostname,name`,
+            translateTime: `SYS:HH:MM:ss`,
+          },
+        }),
+      })
+    }
+  } catch {
+    // pino-pretty unavailable — continue without pretty logging
+  }
+
+  _logger =
+    streams.length > 0
+      ? pino(
+          {
+            base: undefined,
+            level: LOG_LEVEL,
+          },
+          pino.multistream(streams)
+        )
+      : pino({
           base: undefined,
+          enabled: false,
           level: LOG_LEVEL,
-        },
-        pino.multistream(streams)
-      )
-    : pino({
-        base: undefined,
-        enabled: false,
-        level: LOG_LEVEL,
-      })
+        })
+  return _logger
+}
 
 function formatArgs(args: Array<unknown>): { err?: Error; msg: string } {
   const errors: Array<Error> = []
   const parts: Array<string> = []
-  for (const a of args) {
-    if (a instanceof Error) errors.push(a)
-    else parts.push(typeof a === `string` ? a : JSON.stringify(a))
+  for (const value of args) {
+    if (value instanceof Error) errors.push(value)
+    else parts.push(typeof value === `string` ? value : JSON.stringify(value))
   }
   return {
     err: errors[0],
@@ -74,22 +85,22 @@ function formatArgs(args: Array<unknown>): { err?: Error; msg: string } {
 export const serverLog = {
   info(...args: Array<unknown>): void {
     const { msg } = formatArgs(args)
-    logger.info(msg)
+    getLogger().info(msg)
   },
 
   warn(...args: Array<unknown>): void {
     const { err, msg } = formatArgs(args)
-    if (err) logger.warn({ err }, msg)
-    else logger.warn(msg)
+    if (err) getLogger().warn({ err }, msg)
+    else getLogger().warn(msg)
   },
 
   error(...args: Array<unknown>): void {
     const { err, msg } = formatArgs(args)
-    if (err) logger.error({ err }, msg)
-    else logger.error(msg)
+    if (err) getLogger().error({ err }, msg)
+    else getLogger().error(msg)
   },
 
   event(obj: Record<string, unknown>, msg: string): void {
-    logger.info(obj, msg)
+    getLogger().info(obj, msg)
   },
 }

package/src/utils/server-utils.ts

@@ -119,7 +119,7 @@ export function buildElectricProxyTarget(options: {
   if (table === `entities`) {
     target.searchParams.set(
       `columns`,
-      `"tenant_id","url","type","status","dispatch_policy","tags","spawn_args","parent","type_revision","inbox_schemas","state_schemas","created_at","updated_at"`
+      `"tenant_id","url","type","status","dispatch_policy","tags","spawn_args","sandbox","parent","type_revision","inbox_schemas","state_schemas","created_at","updated_at"`
     )
     applyTenantShapeWhere(target, options.tenantId)
   } else if (table === `entity_types`) {
@@ -131,7 +131,7 @@ export function buildElectricProxyTarget(options: {
   } else if (table === `runners`) {
     target.searchParams.set(
       `columns`,
-      `"tenant_id","id","owner_principal","label","kind","admin_status","wake_stream","created_at","updated_at"`
+      `"tenant_id","id","owner_principal","label","kind","admin_status","wake_stream","sandbox_profiles","created_at","updated_at"`
     )
     applyTenantShapeWhere(target, options.tenantId, [
       `owner_principal = ${sqlStringLiteral(options.principalUrl ?? ``)}`,

package/src/wake-registry.ts

@@ -41,6 +41,10 @@ export interface WakeEvalResult {
       collection: string
       kind: `insert` | `update` | `delete`
       key: string
+      from?: string
+      payload?: unknown
+      timestamp?: string
+      message_type?: string
     }>
   }
   runFinishedStatus?: `completed` | `failed`
@@ -885,11 +889,7 @@ export class WakeRegistry {
     reg: WakeRegistration,
     event: Record<string, unknown>
   ): {
-    change: {
-      collection: string
-      kind: `insert` | `update` | `delete`
-      key: string
-    }
+    change: WakeEvalResult[`wakeMessage`][`changes`][number]
     runFinishedStatus?: `completed` | `failed`
   } | null {
     if (reg.condition === `runFinished`) {
@@ -935,12 +935,23 @@ export class WakeRegistry {
       return null
     }
 
-    return {
-      change: {
-        collection: eventType,
-        kind,
-        key: (event.key as string) || ``,
-      },
+    const change: WakeEvalResult[`wakeMessage`][`changes`][number] = {
+      collection: eventType,
+      kind,
+      key: (event.key as string) || ``,
     }
+
+    if (eventType === `inbox`) {
+      const value = event.value as Record<string, unknown> | undefined
+      if (typeof value?.from === `string`) change.from = value.from
+      if (`payload` in (value ?? {})) change.payload = value?.payload
+      if (typeof value?.timestamp === `string`)
+        change.timestamp = value.timestamp
+      if (typeof value?.message_type === `string`) {
+        change.message_type = value.message_type
+      }
+    }
+
+    return { change }
   }
 }