Fix agents quickstart runner registration

Author: KyleAMathews

.changeset/quickstart-runner-principal.md

@@ -0,0 +1,8 @@
+---
+"electric-ax": patch
+"@electric-ax/agents": patch
+"@electric-ax/agents-runtime": patch
+"@electric-ax/agents-server-ui": patch
+---
+
+Fix Electric Agents quickstart startup by authenticating the built-in pull-wake runner with the same principal it registers as, registering built-in agent types with the local runner as their default dispatch target, and aligning the CLI's default principal with the local quickstart user. Pin the CLI-launched agents-server Docker image to the matching released agents-server version, improve registration fetch errors so startup failures include the endpoint and underlying cause, avoid the CLI observe live-query Collection boundary, and clarify browser-only credentials settings copy.

package.json

@@ -8,7 +8,7 @@
   "packageManager": "pnpm@10.12.1",
   "private": true,
   "scripts": {
-    "ci:publish": "pnpm '/^ci:publish:.+/' && pnpm exec changeset tag",
+    "ci:publish": "pnpm run -r --filter './packages/**' build && pnpm '/^ci:publish:.+/' && pnpm exec changeset tag",
     "ci:publish:hex-electric": "pnpm run --dir packages/sync-service publish:hex",
     "ci:publish:hex-electric-client": "pnpm run --dir packages/elixir-client publish:hex",
     "ci:publish:npm": "pnpm publish -r --filter './packages/**' --no-git-checks --access public",

packages/agents-runtime/src/create-handler.ts

@@ -561,14 +561,23 @@ export function createRuntimeRouter(
         }
       }
 
-      const typeRes = await fetch(
-        appendPathToUrl(baseUrl, `/_electric/entity-types`),
-        {
+      const registrationUrl = appendPathToUrl(
+        baseUrl,
+        `/_electric/entity-types`
+      )
+      let typeRes: Response
+      try {
+        typeRes = await fetch(registrationUrl, {
           method: `POST`,
           headers: await registrationHeaders(),
           body: JSON.stringify(body),
-        }
-      )
+        })
+      } catch (error) {
+        const message = `Failed to register type "${name}" at ${registrationUrl}: ${formatFetchError(error)}`
+        runtimeLog.error(`[agent-runtime]`, message)
+        failed.push(`${name} (${message})`)
+        return
+      }
 
       if (!typeRes.ok) {
         const err = await typeRes.text()
@@ -750,6 +759,17 @@ function json(body: Record<string, unknown>, status: number): Response {
   })
 }
 
+function formatFetchError(error: unknown): string {
+  if (error instanceof Error) {
+    const cause =
+      error.cause instanceof Error
+        ? `: ${error.cause.message || error.cause.name}`
+        : ``
+    return `${error.message || error.name || `Unknown error`}${cause}`
+  }
+  return String(error) || `Unknown error`
+}
+
 async function toFetchRequest(req: IncomingMessage): Promise<Request> {
   const body = await readBody(req)
   const host =

packages/agents-runtime/src/entity-timeline.ts

@@ -15,7 +15,7 @@ import {
   sum,
   toArray,
 } from '@durable-streams/state/db'
-import { caseWhen } from '@tanstack/db'
+import { BasicIndex, caseWhen } from '@tanstack/db'
 import type {
   Collection,
   InitialQueryBuilder,
@@ -1316,6 +1316,42 @@ const getEntitySignalsCollection = cachedCollectionFactory(
 
 type EntityTimelineQueryBuilder = (q: InitialQueryBuilder) => QueryBuilder<any>
 
+const indexedTimelineDbs = new WeakSet<object>()
+
+function createIndexIfAvailable(
+  collection: unknown,
+  index: (row: any) => unknown
+): void {
+  if (
+    collection &&
+    typeof (collection as { createIndex?: unknown }).createIndex === `function`
+  ) {
+    const indexedCollection = collection as {
+      createIndex: (
+        index: (row: any) => unknown,
+        config: { indexType: typeof BasicIndex }
+      ) => void
+    }
+    indexedCollection.createIndex(index, { indexType: BasicIndex })
+  }
+}
+
+export function ensureEntityTimelineIndexes(db: EntityStreamDB): void {
+  if (indexedTimelineDbs.has(db as object)) return
+  indexedTimelineDbs.add(db as object)
+
+  createIndexIfAvailable(db.collections.texts, (row) => row.run_id)
+  createIndexIfAvailable(db.collections.textDeltas, (row) => row.text_id)
+  createIndexIfAvailable(db.collections.toolCalls, (row) => row.run_id)
+  createIndexIfAvailable(db.collections.reasoning, (row) => row.run_id)
+  createIndexIfAvailable(
+    db.collections.reasoningDeltas,
+    (row) => row.reasoning_id
+  )
+  createIndexIfAvailable(db.collections.steps, (row) => row.run_id)
+  createIndexIfAvailable(db.collections.errors, (row) => row.run_id)
+}
+
 /**
  * Builds a live timeline query for an entity stream.
  *
@@ -1339,6 +1375,7 @@ export function createEntityTimelineQuery(
   db: EntityStreamDB,
   opts: EntityTimelineQueryOptions = {}
 ): EntityTimelineQueryBuilder {
+  ensureEntityTimelineIndexes(db)
   return (q: InitialQueryBuilder) => buildEntityTimelineQuery(q, db, opts)
 }
 
@@ -1441,18 +1478,15 @@ function buildEntityTimelineQuery(
       text: caseWhen(text.key, {
         key: text.key,
         run_id: text.run_id,
-        order: coalesce(text._timeline_order, `~`),
+        order: coalesce(text._seq, -1),
         status: text.status,
       }),
       textContent: concat(
         toArray(
           q
             .from({ textChunk: db.collections.textDeltas })
             .where(({ textChunk }) => eq(textChunk.text_id, text.key))
-            .orderBy(({ textChunk }) =>
-              coalesce(textChunk._timeline_order, `~`)
-            )
-            .orderBy(({ textChunk }) => textChunk.key)
+            .orderBy(({ textChunk }) => coalesce(textChunk._seq, -1))
             .select(({ textChunk }) => textChunk.delta)
         )
       ),
@@ -1486,7 +1520,7 @@ function buildEntityTimelineQuery(
     .select(({ reasoning }) => ({
       key: reasoning.key,
       run_id: reasoning.run_id,
-      order: coalesce(reasoning._timeline_order, `~`),
+      order: coalesce(reasoning._seq, -1),
       status: reasoning.status,
       summary_title: reasoning.summary_title,
       encrypted: reasoning.encrypted,
@@ -1497,10 +1531,7 @@ function buildEntityTimelineQuery(
             .where(({ reasoningChunk }) =>
               eq(reasoningChunk.reasoning_id, reasoning.key)
             )
-            .orderBy(({ reasoningChunk }) =>
-              coalesce(reasoningChunk._timeline_order, `~`)
-            )
-            .orderBy(({ reasoningChunk }) => reasoningChunk.key)
+            .orderBy(({ reasoningChunk }) => coalesce(reasoningChunk._seq, -1))
             .select(({ reasoningChunk }) => reasoningChunk.delta)
         )
       ),
@@ -1667,6 +1698,7 @@ type EntityQueryBuilder = (q: InitialQueryBuilder) => QueryBuilder<any>
 export function createEntityIncludesQuery(
   db: EntityStreamDB
 ): EntityQueryBuilder {
+  ensureEntityTimelineIndexes(db)
   const seedCollection = getTimelineSeedCollection(db)
   const runsCollection = getEntityRunsCollection(db)
   const inboxCollection = getEntityInboxCollection(db)

packages/agents-runtime/test/create-handler.test.ts

@@ -648,6 +648,23 @@ describe(`createRuntimeHandler`, () => {
     )
   })
 
+  it(`registerTypes includes URL and cause when registration fetch throws`, async () => {
+    defineEntity(`network-agent`, { handler: async () => {} })
+
+    vi.spyOn(globalThis, `fetch`).mockRejectedValue(
+      new Error(`fetch failed`, { cause: new Error(`ECONNREFUSED 127.0.0.1`) })
+    )
+
+    const handler = createRuntimeHandler({
+      baseUrl: `http://localhost:3000`,
+      handlerUrl: `http://localhost:4000/electric-agents`,
+    })
+
+    await expect(handler.registerTypes()).rejects.toThrow(
+      `Failed to register type "network-agent" at http://localhost:3000/_electric/entity-types: fetch failed: ECONNREFUSED 127.0.0.1`
+    )
+  })
+
   it(`registers entity types with a webhook default dispatch policy`, async () => {
     defineEntity(`schema-agent`, {
       description: `Schema agent`,

packages/agents-runtime/test/entity-timeline.test.ts

@@ -1835,6 +1835,61 @@ describe(`entity includes query`, () => {
       })
     })
 
+    it(`interleaves top-level live timeline rows by runtime timeline order`, async () => {
+      const { collections, sync } = createEntityCollections()
+      const liveQuery = createLiveQueryCollection({
+        query: createEntityTimelineQuery({ collections } as any),
+        startSync: true,
+      })
+      await liveQuery.preload()
+
+      sync.inbox.insert({
+        key: `msg-1`,
+        _timeline_order: order(1),
+        from: `user`,
+        payload: `first`,
+        timestamp: `2026-04-15T18:00:00.000Z`,
+        status: `processed`,
+      })
+      sync.runs.insert({
+        key: `run-1`,
+        _timeline_order: order(2),
+        status: `started`,
+      })
+      sync.texts.insert({
+        key: `text-1`,
+        _timeline_order: order(3),
+        run_id: `run-1`,
+        status: `streaming`,
+      })
+      sync.textDeltas.insert({
+        key: `td-1`,
+        text_id: `text-1`,
+        run_id: `run-1`,
+        delta: `First response`,
+      })
+      sync.inbox.insert({
+        key: `msg-2`,
+        _timeline_order: order(4),
+        from: `user`,
+        payload: `second`,
+        timestamp: `2026-04-15T18:01:00.000Z`,
+        status: `processed`,
+      })
+      await new Promise((r) => setTimeout(r, 50))
+
+      const rows = getData(liveQuery)
+      expect(
+        rows.map((row) =>
+          row.inbox
+            ? `inbox:${row.inbox.key}`
+            : row.run
+              ? `run:${row.run.key}`
+              : `other:${row.$key}`
+        )
+      ).toEqual([`inbox:msg-1`, `run:run-1`, `inbox:msg-2`])
+    })
+
     it(`reacts to toolCall updates`, async () => {
       const { collections, sync } = createEntityCollections()
       const queryFn = createEntityIncludesQuery({ collections } as any)
@@ -2497,6 +2552,51 @@ describe(`entity includes query`, () => {
       expect(item.text?.content).toBe(`Hello world`)
     })
 
+    it(`live items.text.content orders deltas by stream sequence, not key`, async () => {
+      // Production regression: delta keys like `msg-0:10` sort before
+      // `msg-0:2` lexicographically. The live query must use stream
+      // sequence order so streamed text stays in model output order.
+      const { collections, sync } = createTimelineCollections()
+      const liveQuery = createLiveQueryCollection({
+        query: createEntityTimelineQuery({ collections } as any),
+        startSync: true,
+      })
+      await liveQuery.preload()
+
+      sync.runs.insert({ key: `run-0`, status: `started` })
+      sync.texts.insert({
+        key: `msg-0`,
+        run_id: `run-0`,
+        status: `streaming`,
+      })
+      for (let i = 0; i <= 10; i++) {
+        sync.textDeltas.insert({
+          key: `msg-0:${i}`,
+          text_id: `msg-0`,
+          run_id: `run-0`,
+          delta: `[${i}]`,
+        })
+      }
+      sync.texts.update({
+        key: `msg-0`,
+        run_id: `run-0`,
+        status: `completed`,
+      })
+      sync.runs.update({
+        key: `run-0`,
+        status: `completed`,
+        finish_reason: `stop`,
+      })
+      await new Promise((r) => setTimeout(r, 50))
+
+      const rows = getRows(liveQuery)
+      const runRow = rows.find((r) => r.run?.key === `run-0`)
+      expect(runRow).toBeTruthy()
+      const items = Array.from(runRow.run.items.toArray) as Array<any>
+      expect(items).toHaveLength(1)
+      expect(items[0].text?.content).toBe(`[0][1][2][3][4][5][6][7][8][9][10]`)
+    })
+
     it(`reasoning content survives multiple run-row updates in sequence`, async () => {
       // Even closer to production: the run row gets updated MULTIPLE
       // times (each delta + status flip), which may invalidate the

packages/agents-server-ui/src/components/settings/pages/CredentialsPage.tsx

@@ -81,13 +81,13 @@ export function CredentialsPage(): React.ReactElement {
         description={
           isDesktop
             ? `Configure model providers for connected local runtimes. Changes save automatically and apply on the next runtime restart.`
-            : `Model providers are configured by the agents-server you're connected to. The web build inherits whatever providers the server was started with.`
+            : `Model providers are configured by the runtime connected to this server. Restart that runtime with provider credentials to change the available models.`
         }
       >
         {!isDesktop ? (
           <SettingsPanel>
             <Text size={2} tone="muted">
-              No editable provider keys in the web build.
+              Provider keys are not editable from the browser UI.
             </Text>
           </SettingsPanel>
         ) : !status ? (

packages/agents/src/server.ts

@@ -309,6 +309,9 @@ export class BuiltinAgentsServer {
         baseSkillsDir: this.options.baseSkillsDir,
         enabledModelValues: this.options.enabledModelValues,
         serverHeaders: pullWake.headers,
+        defaultDispatchPolicyForType: () => ({
+          targets: [{ type: `runner`, runnerId: pullWake.runnerId }],
+        }),
       })
       if (!this.bootstrap) {
         throw new Error(
@@ -428,9 +431,13 @@ export class BuiltinAgentsServer {
     )
     headers.set(`content-type`, `application/json`)
     const profiles = this.bootstrap?.runtime.sandboxProfileDescriptors ?? []
-    const response = await fetch(
-      appendPathToUrl(this.options.agentServerUrl, `/_electric/runners`),
-      {
+    const registrationUrl = appendPathToUrl(
+      this.options.agentServerUrl,
+      `/_electric/runners`
+    )
+    let response: Response
+    try {
+      response = await fetch(registrationUrl, {
         method: `POST`,
         headers,
         body: JSON.stringify({
@@ -441,8 +448,12 @@ export class BuiltinAgentsServer {
           admin_status: `enabled`,
           sandbox_profiles: profiles,
         }),
-      }
-    )
+      })
+    } catch (error) {
+      throw new Error(
+        `Failed to register pull-wake runner ${pullWake.runnerId} at ${registrationUrl}: ${formatFetchError(error)}`
+      )
+    }
     if (!response.ok) {
       throw new Error(
         `Failed to register pull-wake runner ${pullWake.runnerId}: ${response.status} ${await response.text()}`
@@ -451,3 +462,14 @@ export class BuiltinAgentsServer {
     return (await response.json()) as { wake_stream_offset?: string }
   }
 }
+
+function formatFetchError(error: unknown): string {
+  if (error instanceof Error) {
+    const cause =
+      error.cause instanceof Error
+        ? `: ${error.cause.message || error.cause.name}`
+        : ``
+    return `${error.message || error.name || `Unknown error`}${cause}`
+  }
+  return String(error) || `Unknown error`
+}