canopy-client 0.1.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "canopy-client",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Framework-free TypeScript client for canopy-web: delegated-token cache, REST, and the session WebSocket.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dimagi-internal/canopy-web.git",
+    "directory": "frontend/packages/canopy-client"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./bridge": "./src/bridge.ts"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/bridge.ts

@@ -0,0 +1,114 @@
+/**
+ * The host bridge contract: how a product lends an agent its page.
+ *
+ * Defined here, at the framework-free layer, because the v2 spec (§8) requires
+ * ONE definition with two transports. A React host mounting `canopy-ui/chat`
+ * calls these functions directly; the iframe widget reaches the identical
+ * functions over `postMessage`. If the contract lived in the widget, a native
+ * host would have to reimplement it and the two would drift — which is the
+ * mistake `RunnerAssignment` and `runner_tenant_slugs` were both cleanups of.
+ *
+ * **Why a snapshot and not a live feed.** `provideContext` is pulled when a
+ * session opens, not subscribed to. A continuously-synced readable channel
+ * (CopilotKit's `useCopilotReadable` is the reference shape) is real future
+ * work; it is not needed to prove that an agent can reason about the page, and
+ * every tick of it is a message the host has to be trusted to get right.
+ *
+ * **What the ACL story is.** The host resolves context and runs actions *in the
+ * user's own session*, so an agent sees and does exactly what that user could —
+ * never more. That is why v1 takes this route rather than giving the agent its
+ * own credential for the host (v2 spec §8, option (b)): there is nothing here
+ * that can exceed the user, so there is nothing to leak.
+ *
+ * **The limit that follows.** Both halves need the page to be open. Close the
+ * tab and the agent cannot read or act; there is no server-side path. Action is
+ * scoped to the life of the visit, and a host should not describe it otherwise.
+ */
+
+/** Arbitrary JSON the host chooses to expose. Deliberately opaque: canopy never
+ *  interprets it, the same way `Session.metadata` is an opaque bag. */
+export type HostContext = Record<string, unknown>
+
+/** Pulled when a session opens. Synchronous or not — a host may need to read
+ *  something async, and the caller always awaits. */
+export type ContextProvider = () => HostContext | Promise<HostContext>
+
+/**
+ * One thing an agent may ask the page to do.
+ *
+ * Returning a value is how the agent learns whether it worked; THROWING is how
+ * a host refuses. A refusal must be an error and not a `false`, because a
+ * silently-ignored action is indistinguishable to the agent from a successful
+ * one, and it will carry on as though the change landed.
+ */
+export type HostAction = (args: Record<string, unknown>) => unknown | Promise<unknown>
+
+export interface HostBridge {
+  /** Register what the agent may read. Replaces any previous provider — a page
+   *  has one current state, not an accumulating list of them. */
+  provideContext(provider: ContextProvider): void
+  /** Register one named action. Re-registering a name replaces it, so a
+   *  re-rendering host component can call this freely without stacking
+   *  handlers. */
+  registerAction(name: string, action: HostAction): void
+  /** Stop offering an action — e.g. the user navigated away from the thing it
+   *  acted on, and running it now would mutate something off-screen. */
+  unregisterAction(name: string): void
+  /** Read the current snapshot. `{}` when the host registered no provider,
+   *  rather than throwing: a host that lends no context is a legitimate host. */
+  readContext(): Promise<HostContext>
+  /** Names currently offered, so the agent can be told what it may call. */
+  actionNames(): string[]
+  /** Run one. Rejects with `UnknownActionError` if it was never registered or
+   *  has since been withdrawn — never a silent no-op. */
+  runAction(name: string, args?: Record<string, unknown>): Promise<unknown>
+}
+
+export class UnknownActionError extends Error {
+  // See CanopyRestError in rest.ts: `erasableSyntaxOnly` forbids constructor
+  // parameter properties.
+  readonly actionName: string
+
+  constructor(name: string) {
+    super(
+      `no host action named ${JSON.stringify(name)} is registered. ` +
+        'It may have been withdrawn because the page moved on.',
+    )
+    // `actionName`, not `name`: Error already defines `name` (it is the class
+    // name used when stringifying an error), so the original field was
+    // shadowing it and would have made this print as `no host action named…`
+    // instead of `UnknownActionError`.
+    this.actionName = name
+  }
+}
+
+export function createHostBridge(): HostBridge {
+  let provider: ContextProvider | null = null
+  const actions = new Map<string, HostAction>()
+
+  return {
+    provideContext(next) {
+      provider = next
+    },
+    registerAction(name, action) {
+      actions.set(name, action)
+    },
+    unregisterAction(name) {
+      actions.delete(name)
+    },
+    async readContext() {
+      if (!provider) return {}
+      return provider()
+    },
+    actionNames() {
+      // Sorted so a host that registers in a different order across renders
+      // does not produce a different tool list for the agent each time.
+      return [...actions.keys()].sort()
+    },
+    async runAction(name, args = {}) {
+      const action = actions.get(name)
+      if (!action) throw new UnknownActionError(name)
+      return action(args)
+    },
+  }
+}

package/src/client.test.ts

@@ -0,0 +1,317 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import {
+  CanopyRestError,
+  buildSessionWsUrl,
+  createCanopyClient,
+  createHostBridge,
+  createTokenStore,
+  UnknownActionError,
+} from './index'
+
+const TOKEN_TTL = () => new Date(Date.now() + 60 * 60 * 1000).toISOString()
+
+describe('token store', () => {
+  it('caches, so N callers in a tick do not mint N tokens server-side', async () => {
+    const fetchToken = vi.fn().mockResolvedValue({ token: 't1', expiresAt: TOKEN_TTL() })
+    const store = createTokenStore(fetchToken)
+
+    const all = await Promise.all([store.get(), store.get(), store.get()])
+
+    expect(all).toEqual(['t1', 't1', 't1'])
+    expect(fetchToken).toHaveBeenCalledTimes(1)
+  })
+
+  it('force bypasses the cache — the 401 path must not trust our own bookkeeping', async () => {
+    const fetchToken = vi
+      .fn()
+      .mockResolvedValueOnce({ token: 'stale', expiresAt: TOKEN_TTL() })
+      .mockResolvedValueOnce({ token: 'fresh', expiresAt: TOKEN_TTL() })
+    const store = createTokenStore(fetchToken)
+
+    expect(await store.get()).toBe('stale')
+    expect(await store.get(true)).toBe('fresh')
+    expect(fetchToken).toHaveBeenCalledTimes(2)
+  })
+
+  it('refetches a token already inside the refresh skew', async () => {
+    // 2 minutes out, against a 5-minute skew: treated as due, not valid.
+    const soon = new Date(Date.now() + 2 * 60 * 1000).toISOString()
+    const fetchToken = vi.fn().mockResolvedValue({ token: 't', expiresAt: soon })
+    const store = createTokenStore(fetchToken)
+
+    await store.get()
+    await store.get()
+
+    expect(fetchToken).toHaveBeenCalledTimes(2)
+  })
+
+  it('treats an unparseable expiry as already expired rather than caching NaN', async () => {
+    const fetchToken = vi.fn().mockResolvedValue({ token: 't', expiresAt: 'not a date' })
+    const store = createTokenStore(fetchToken)
+
+    await store.get()
+    await store.get()
+
+    expect(fetchToken).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not poison later calls with a rejected in-flight promise', async () => {
+    const fetchToken = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('network blip'))
+      .mockResolvedValueOnce({ token: 'recovered', expiresAt: TOKEN_TTL() })
+    const store = createTokenStore(fetchToken)
+
+    await expect(store.get()).rejects.toThrow('network blip')
+    expect(await store.get()).toBe('recovered')
+  })
+
+  it('keeps two stores independent — a page may mount two widgets', async () => {
+    // ace-web held this state at module scope, which is fine for exactly one
+    // client per page and wrong for two panels or two agents.
+    const a = createTokenStore(vi.fn().mockResolvedValue({ token: 'a', expiresAt: TOKEN_TTL() }))
+    const b = createTokenStore(vi.fn().mockResolvedValue({ token: 'b', expiresAt: TOKEN_TTL() }))
+
+    expect(await a.get()).toBe('a')
+    expect(await b.get()).toBe('b')
+    expect(a.peek()).toBe('a')
+  })
+
+  it('peek is null before the first mint', () => {
+    const store = createTokenStore(vi.fn())
+    expect(store.peek()).toBeNull()
+  })
+})
+
+describe('session websocket url', () => {
+  it('borrows scheme and host when the base is a bare path', () => {
+    const url = buildSessionWsUrl('/canopy', 'sess-1', 'tok', {
+      protocol: 'https:',
+      host: 'labs.connect.dimagi.com',
+    })
+    expect(url).toBe('wss://labs.connect.dimagi.com/canopy/ws/canopy-sessions/sess-1/?token=tok')
+  })
+
+  it('keeps its own host when the base is absolute — the widget case', () => {
+    const url = buildSessionWsUrl('https://canopy.example.com/canopy', 'sess-1', 'tok')
+    expect(url).toBe('wss://canopy.example.com/canopy/ws/canopy-sessions/sess-1/?token=tok')
+  })
+
+  it('downgrades to ws:// for a plain-http base, so dev works', () => {
+    const url = buildSessionWsUrl('http://localhost:8000', 'sess-1', 'tok')
+    expect(url).toBe('ws://localhost:8000/ws/canopy-sessions/sess-1/?token=tok')
+  })
+
+  it('url-encodes the session id and the token', () => {
+    const url = buildSessionWsUrl('http://h', 'a/b', 'to ken')
+    expect(url).toContain('/ws/canopy-sessions/a%2Fb/')
+    expect(url).toContain('token=to%20ken')
+  })
+
+  it('omits the query entirely when there is no token', () => {
+    expect(buildSessionWsUrl('http://h', 's', null)).toBe('ws://h/ws/canopy-sessions/s/')
+  })
+})
+
+describe('rest', () => {
+  function harness(responses: Array<{ status: number; body?: unknown }>) {
+    const calls: Array<{ url: string; init: RequestInit }> = []
+    const queue = [...responses]
+    const fetchImpl = vi.fn(async (url: string, init: RequestInit = {}) => {
+      calls.push({ url: String(url), init })
+      const next = queue.shift() ?? { status: 200, body: [] }
+      return {
+        ok: next.status >= 200 && next.status < 300,
+        status: next.status,
+        json: async () => next.body,
+      } as Response
+    }) as unknown as typeof fetch
+
+    const client = createCanopyClient({
+      baseUrl: 'https://canopy.example.com',
+      fetchToken: vi.fn().mockResolvedValue({ token: 'tok', expiresAt: TOKEN_TTL() }),
+      originKey: 'connect-labs:opp-42',
+      source: 'connect-labs',
+      fetchImpl,
+    })
+    return { client, calls }
+  }
+
+  it('sends the bearer on every request', async () => {
+    const { client, calls } = harness([{ status: 200, body: [] }])
+    await client.rest.listAgents()
+    expect((calls[0].init.headers as Record<string, string>).Authorization).toBe('Bearer tok')
+  })
+
+  it('scopes the session list by this product, not by everything the user has', async () => {
+    const { client, calls } = harness([{ status: 200, body: [] }])
+    await client.rest.listSessions({ state: 'active' })
+    expect(calls[0].url).toContain('origin_key=connect-labs%3Aopp-42')
+    expect(calls[0].url).toContain('source=connect-labs')
+    expect(calls[0].url).toContain('state=active')
+  })
+
+  it('retries a 401 exactly once, with a forced re-mint', async () => {
+    const { client, calls } = harness([
+      { status: 401 },
+      { status: 200, body: [{ id: 's1', title: 't', last_activity_at: 'x' }] },
+    ])
+    const rows = await client.rest.listSessions()
+    expect(calls).toHaveLength(2)
+    expect(rows[0].id).toBe('s1')
+  })
+
+  it('does not retry a second 401 — it raises instead of looping', async () => {
+    const { client, calls } = harness([{ status: 401 }, { status: 401 }])
+    await expect(client.rest.listSessions()).rejects.toBeInstanceOf(CanopyRestError)
+    expect(calls).toHaveLength(2)
+  })
+
+  it('maps last_activity_at onto updatedAt — SessionOut has no updated_at', async () => {
+    const { client } = harness([
+      {
+        status: 200,
+        body: [
+          {
+            id: 's1',
+            title: 'chat',
+            agent_slug: 'labs-helper',
+            last_activity_at: '2026-09-12T00:00:00Z',
+            runner_name: 'jj-mbp',
+            runner_online: true,
+          },
+        ],
+      },
+    ])
+    const [row] = await client.rest.listSessions()
+    expect(row.updatedAt).toBe('2026-09-12T00:00:00Z')
+    expect(row.agentSlug).toBe('labs-helper')
+    expect(row.runnerOnline).toBe(true)
+  })
+
+  it('reports runnerOnline as null for an unbound session, not false', async () => {
+    // null means "nothing to be offline"; false would make the placement banner
+    // claim a runner had gone away when there never was one.
+    const { client } = harness([{ status: 200, body: [{ id: 's', title: '', last_activity_at: '' }] }])
+    const [row] = await client.rest.listSessions()
+    expect(row.runnerOnline).toBeNull()
+  })
+
+  it('threads has_more_before through the detail read', async () => {
+    const { client } = harness([
+      {
+        status: 200,
+        body: { id: 's', title: '', last_activity_at: '', has_more_before: true, oldest_loaded_turn_index: 64 },
+      },
+    ])
+    const detail = await client.rest.getSession('s')
+    expect(detail.hasMoreBefore).toBe(true)
+    expect(detail.oldestLoadedTurnIndex).toBe(64)
+  })
+
+  it('the agent picker takes no app parameter — the token decides', async () => {
+    const { client, calls } = harness([{ status: 200, body: [] }])
+    await client.rest.listAgents()
+    expect(calls[0].url).toBe('https://canopy.example.com/api/embed/agents')
+    expect(calls[0].url).not.toContain('app=')
+  })
+})
+
+describe('socket url from the client', () => {
+  it('is null until a token exists, rather than a url that will be rejected', async () => {
+    const client = createCanopyClient({
+      baseUrl: 'https://canopy.example.com',
+      fetchToken: vi.fn().mockResolvedValue({ token: 'tok', expiresAt: TOKEN_TTL() }),
+      fetchImpl: vi.fn() as unknown as typeof fetch,
+    })
+    expect(client.sessionSocketUrl('s1')).toBeNull()
+
+    await client.rest.listAgents().catch(() => undefined) // mints a token
+    expect(client.sessionSocketUrl('s1')).toContain('token=tok')
+  })
+})
+
+describe('host bridge', () => {
+  it('returns an empty snapshot when the host lends no context', async () => {
+    expect(await createHostBridge().readContext()).toEqual({})
+  })
+
+  it('reads the CURRENT page state each time, not the state at registration', async () => {
+    // The whole point: a workflow's props change as the user works, and the
+    // agent must see what is on screen when the session opens.
+    const bridge = createHostBridge()
+    let step = 1
+    bridge.provideContext(() => ({ step }))
+    expect(await bridge.readContext()).toEqual({ step: 1 })
+    step = 2
+    expect(await bridge.readContext()).toEqual({ step: 2 })
+  })
+
+  it('replaces the provider rather than accumulating providers', async () => {
+    const bridge = createHostBridge()
+    bridge.provideContext(() => ({ which: 'first' }))
+    bridge.provideContext(() => ({ which: 'second' }))
+    expect(await bridge.readContext()).toEqual({ which: 'second' })
+  })
+
+  it('awaits an async provider', async () => {
+    const bridge = createHostBridge()
+    bridge.provideContext(async () => ({ loaded: true }))
+    expect(await bridge.readContext()).toEqual({ loaded: true })
+  })
+
+  it('runs a registered action and returns its result to the agent', async () => {
+    const bridge = createHostBridge()
+    const onUpdateState = vi.fn().mockResolvedValue({ saved: true })
+    bridge.registerAction('updateState', onUpdateState)
+
+    const result = await bridge.runAction('updateState', { status: 'reviewed' })
+
+    expect(onUpdateState).toHaveBeenCalledWith({ status: 'reviewed' })
+    expect(result).toEqual({ saved: true })
+  })
+
+  it('rejects an unknown action instead of silently doing nothing', async () => {
+    // A no-op is indistinguishable to the agent from success, and it will carry
+    // on as though the page changed.
+    await expect(createHostBridge().runAction('nope')).rejects.toBeInstanceOf(UnknownActionError)
+  })
+
+  it('rejects an action that was withdrawn when the page moved on', async () => {
+    const bridge = createHostBridge()
+    bridge.registerAction('updateState', vi.fn())
+    bridge.unregisterAction('updateState')
+    await expect(bridge.runAction('updateState')).rejects.toBeInstanceOf(UnknownActionError)
+    expect(bridge.actionNames()).toEqual([])
+  })
+
+  it('re-registering a name replaces the handler, so a re-render cannot stack them', async () => {
+    const bridge = createHostBridge()
+    const stale = vi.fn()
+    const fresh = vi.fn()
+    bridge.registerAction('act', stale)
+    bridge.registerAction('act', fresh)
+
+    await bridge.runAction('act')
+
+    expect(stale).not.toHaveBeenCalled()
+    expect(fresh).toHaveBeenCalledOnce()
+    expect(bridge.actionNames()).toEqual(['act'])
+  })
+
+  it('lists action names in a stable order across registration orders', () => {
+    const a = createHostBridge()
+    a.registerAction('zed', vi.fn())
+    a.registerAction('alpha', vi.fn())
+    expect(a.actionNames()).toEqual(['alpha', 'zed'])
+  })
+
+  it('propagates a host refusal as an error, not a falsy return', async () => {
+    const bridge = createHostBridge()
+    bridge.registerAction('act', () => {
+      throw new Error('not allowed on a completed run')
+    })
+    await expect(bridge.runAction('act')).rejects.toThrow('not allowed on a completed run')
+  })
+})

package/src/dependency-free.test.ts

@@ -0,0 +1,49 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { describe, expect, it } from 'vitest'
+
+/**
+ * The package's reason for existing is that it depends on nothing.
+ *
+ * canopy-ui requires React 19; connect-labs is React 18, and mostly Django
+ * templates with alpine and htmx besides. If this package ever grows an import
+ * of a framework — or of anything at all — the hosts it was built for can no
+ * longer use it, and the failure would show up as a peer-dependency conflict
+ * in someone else's repo rather than as a test here.
+ */
+
+const SRC = dirname(fileURLToPath(import.meta.url))
+
+function shippedFiles(): string[] {
+  return readdirSync(SRC).filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts'))
+}
+
+describe('the package ships with no dependencies', () => {
+  it('declares none in package.json', () => {
+    const pkg = JSON.parse(readFileSync(join(SRC, '..', 'package.json'), 'utf8'))
+    expect(pkg.dependencies).toBeUndefined()
+    expect(pkg.peerDependencies).toBeUndefined()
+    expect(pkg.devDependencies).toBeUndefined()
+  })
+
+  it('imports nothing but its own modules', () => {
+    // Matches `from "x"` / `from 'x'` where x is not relative.
+    const bare = /from\s+['"]([^.'"][^'"]*)['"]/g
+    const offenders: string[] = []
+
+    for (const file of shippedFiles()) {
+      const source = readFileSync(join(SRC, file), 'utf8')
+      for (const [, spec] of source.matchAll(bare)) {
+        offenders.push(`${file} imports ${spec}`)
+      }
+    }
+
+    expect(offenders).toEqual([])
+  })
+
+  it('covers every shipped module, so a new file cannot slip past the check', () => {
+    expect(shippedFiles().sort()).toEqual(['bridge.ts', 'index.ts', 'rest.ts', 'token.ts', 'ws.ts'])
+  })
+})

package/src/index.ts

@@ -0,0 +1,99 @@
+/**
+ * `canopy-client` — layer 1 of the embedded-agent SDK (v2 spec §1).
+ *
+ * The transport half of talking to canopy-web, with **no framework and no
+ * dependencies at all**. That emptiness is the feature: canopy-ui requires
+ * React 19, and the hosts that most want an agent cannot always have it —
+ * connect-labs is React 18, Django templates, alpine and htmx. The iframe
+ * widget bundles its own React; a native React host brings its own; a Django
+ * page brings none. All three use this.
+ *
+ * Extracted from ace-web's `frontend/src/canopy/{token,api,ws}.ts`, which was
+ * already framework-free (zero React imports across ~390 lines) but trapped
+ * inside one host and coupled to that host's endpoints. ace-web still has its
+ * own copy; adopting this is a follow-up in that repo, and until it does the
+ * duplication is real.
+ *
+ * **Why the name is unscoped.** It was `@canopy/client`, which cannot be
+ * published: the `@canopy` npm scope belongs to somebody else (it holds one
+ * package, `atos-theme`, which is not ours). That made the whole layer-1 plan
+ * a dead end — ace-web could never `npm install` it, so the duplication above
+ * could never actually be paid down. `canopy-ui` had already hit this and
+ * settled it: it is deliberately unscoped, "no org scope — portable, not tied
+ * to any account", after starting life as `@canopy/workbench`. This follows
+ * that, rather than re-litigating it a third time.
+ *
+ * What stays OUT, and why:
+ *
+ *  - **Token minting.** The `AppCredential` is a secret, so only a host backend
+ *    can exchange it. The client takes a `fetchToken` callback.
+ *  - **Session creation.** The host stamps `origin_key` server-side from a
+ *    membership-checked path; a client that could set its own would be able to
+ *    claim another tenant's scope. So creation is the host's endpoint, and this
+ *    package only ever reads and sends.
+ */
+
+export { createTokenStore } from './token'
+export type { CanopyToken, FetchToken, TokenStore } from './token'
+
+export { buildSessionWsUrl } from './ws'
+export type { WsLocation } from './ws'
+
+export { createRest, CanopyRestError, RUNNER_STATUS_ONLINE } from './rest'
+export type { CanopyRest, CanopySessionDetail, CanopySessionSummary, RestConfig } from './rest'
+
+export { createHostBridge, UnknownActionError } from './bridge'
+export type { ContextProvider, HostAction, HostBridge, HostContext } from './bridge'
+
+import { createRest, type CanopyRest } from './rest'
+import { createTokenStore, type FetchToken } from './token'
+import { buildSessionWsUrl } from './ws'
+
+export interface CanopyClientConfig {
+  /** Browser-facing canopy base: a same-origin path prefix (`/canopy`) or an
+   *  absolute URL (the normal case for an embedded widget). */
+  baseUrl: string
+  /** How this host mints a delegated token for the signed-in user. */
+  fetchToken: FetchToken
+  /** `metadata.origin_key` to FILTER the session list by — this product's
+   *  scope, as the host stamped it server-side. */
+  originKey?: string
+  /** `metadata.source` to filter by, e.g. `connect-labs`. */
+  source?: string
+  fetchImpl?: typeof fetch
+}
+
+export interface CanopyClient {
+  rest: CanopyRest
+  /** The session socket URL, with the cached token already on it. Returns
+   *  `null` when no token has been minted yet — the caller should not open a
+   *  socket in that state, and getting `null` is easier to handle correctly
+   *  than a URL that will be rejected. */
+  sessionSocketUrl(sessionId: string): string | null
+  /** Force the next request to re-mint. For a host that knows the user's
+   *  identity changed (a sign-out, an account switch). */
+  invalidateToken(): void
+}
+
+export function createCanopyClient(config: CanopyClientConfig): CanopyClient {
+  const tokens = createTokenStore(config.fetchToken)
+  const rest = createRest({
+    baseUrl: config.baseUrl,
+    tokens,
+    originKey: config.originKey,
+    source: config.source,
+    fetchImpl: config.fetchImpl,
+  })
+
+  return {
+    rest,
+    sessionSocketUrl(sessionId) {
+      const token = tokens.peek()
+      if (!token) return null
+      return buildSessionWsUrl(config.baseUrl, sessionId, token)
+    },
+    invalidateToken() {
+      tokens.clear()
+    },
+  }
+}

package/src/rest.ts

@@ -0,0 +1,195 @@
+/**
+ * Browser → canopy-web REST, with the bearer and the 401 retry in one place.
+ *
+ * Ported from ace-web's `frontend/src/canopy/api.ts`, minus everything that was
+ * about ace-web: the `source: "ace-web"` literal, `aceOriginKey()`, and
+ * `createCanopySession`, which called ace-web's OWN endpoint rather than
+ * canopy's (session create stays host-side on purpose — the host stamps
+ * `origin_key` server-side from a membership-checked path, so a caller cannot
+ * claim another tenant's scope). Those become configuration and a host
+ * callback respectively.
+ *
+ * Field mappings against canopy's real schemas are preserved from ace-web,
+ * including the ones that were wrong once and got fixed there:
+ *
+ *  - `SessionOut` has no `updated_at`; it is `last_activity_at`.
+ *  - `Runner.live_status` values are LOWERCASE (`online`, `stale`, …). An
+ *    earlier ace-web draft compared against `"ONLINE"` — the Python constant's
+ *    NAME, not its value — which made every runner look offline and mis-fired
+ *    the placement banner on every chat.
+ *  - `runner_online` is read off the session, not cross-referenced against the
+ *    runner fleet: `GET /api/harness/runners/` is scoped to runners the caller
+ *    personally PAIRED, so a delegated user sees an empty fleet there and could
+ *    never otherwise distinguish a stalled chat from a slow one.
+ */
+
+import type { TokenStore } from './token'
+
+export interface CanopySessionSummary {
+  id: string
+  title: string
+  agentSlug: string | null
+  updatedAt: string
+  runnerName: string | null
+  /** `true`/`false` when the session has a runner binding, `null` when it has
+   *  none — there is nothing to be offline. */
+  runnerOnline: boolean | null
+}
+
+export interface CanopySessionDetail extends CanopySessionSummary {
+  hasMoreBefore: boolean
+  oldestLoadedTurnIndex: number | null
+}
+
+/** `Runner.live_status`'s wire value for a reachable runner. Referenced as a
+ *  constant rather than repeated, because the literal is what went wrong once. */
+export const RUNNER_STATUS_ONLINE = 'online'
+
+export interface RestConfig {
+  /** canopy's browser-facing base — a path prefix (`/canopy`) or an absolute URL. */
+  baseUrl: string
+  tokens: TokenStore
+  /** Stamped by the HOST server-side and used here only to FILTER the list to
+   *  this product's sessions. Never sent on a create — a client that could set
+   *  its own `origin_key` could read another tenant's chats. */
+  originKey?: string
+  /** `metadata.source` filter, e.g. `connect-labs`. */
+  source?: string
+  /** Injectable for tests and for a non-browser host. */
+  fetchImpl?: typeof fetch
+}
+
+export class CanopyRestError extends Error {
+  // Written out rather than declared as constructor parameter properties: the
+  // app's tsconfig sets `erasableSyntaxOnly`, which forbids them. Nothing under
+  // src/ imported this package until the embed entry did, so the whole package
+  // was type-checked for the first time then — and did not compile.
+  readonly status: number
+  readonly path: string
+
+  constructor(status: number, path: string) {
+    super(`canopy request failed (${status}): ${path}`)
+    this.status = status
+    this.path = path
+  }
+}
+
+export function createRest(config: RestConfig) {
+  const doFetch = config.fetchImpl ?? ((...a: Parameters<typeof fetch>) => fetch(...a))
+
+  async function raw(path: string, init: RequestInit = {}): Promise<Response> {
+    const send = (bearer: string) =>
+      doFetch(`${config.baseUrl}${path}`, {
+        ...init,
+        headers: {
+          ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+          ...init.headers,
+          Authorization: `Bearer ${bearer}`,
+        },
+      })
+
+    let response = await send(await config.tokens.get())
+    if (response.status === 401) {
+      // Exactly one retry, with a FORCED refresh — canopy has rejected the
+      // token, so our own expiry bookkeeping is not the authority here (it may
+      // have been revoked early, or the clocks may disagree).
+      response = await send(await config.tokens.get(true))
+    }
+    return response
+  }
+
+  async function json<T>(path: string, init?: RequestInit): Promise<T> {
+    const response = await raw(path, init)
+    if (!response.ok) throw new CanopyRestError(response.status, path)
+    if (response.status === 204) return undefined as T
+    return (await response.json()) as T
+  }
+
+  function mapSummary(r: Record<string, unknown>): CanopySessionSummary {
+    return {
+      id: r.id as string,
+      title: r.title as string,
+      agentSlug: (r.agent_slug as string | null | undefined) ?? null,
+      updatedAt: (r.last_activity_at as string | undefined) ?? (r.updated_at as string),
+      runnerName: (r.runner_name as string | null | undefined) ?? null,
+      runnerOnline: (r.runner_online as boolean | null | undefined) ?? null,
+    }
+  }
+
+  return {
+    raw,
+    json,
+
+    /** Agents this embedding app may offer this user — the picker's source.
+     *  The app is resolved from the bearer token server-side, so there is
+     *  deliberately no parameter here to get wrong. */
+    async listAgents(): Promise<
+      { slug: string; name: string; description: string; avatar_url: string; workspace: string }[]
+    > {
+      return json('/api/embed/agents')
+    },
+
+    async listSessions(
+      filters: { state?: string; agentSlug?: string } = {},
+    ): Promise<CanopySessionSummary[]> {
+      const params = new URLSearchParams()
+      if (config.source) params.set('source', config.source)
+      // Scopes the list to this product. Omitted when the host has no scope to
+      // apply, in which case canopy's own per-user filtering is the only limit.
+      if (config.originKey) params.set('origin_key', config.originKey)
+      if (filters.state) params.set('state', filters.state)
+      if (filters.agentSlug) params.set('agent_slug', filters.agentSlug)
+      const qs = params.toString()
+      const rows = await json<Record<string, unknown>[]>(
+        `/api/canopy-sessions/${qs ? `?${qs}` : ''}`,
+      )
+      return rows.map(mapSummary)
+    },
+
+    /** Single-session detail. NOT filtered by `state` or capped by a page limit,
+     *  so it is the right call for "does THIS session have a bound runner" and
+     *  "is there more history" — an archived or page-201st session vanishes from
+     *  the list but is still directly gettable. */
+    async getSession(id: string): Promise<CanopySessionDetail> {
+      const r = await json<Record<string, unknown>>(
+        `/api/canopy-sessions/${encodeURIComponent(id)}`,
+      )
+      return {
+        ...mapSummary(r),
+        hasMoreBefore: Boolean(r.has_more_before),
+        oldestLoadedTurnIndex: (r.oldest_loaded_turn_index as number | null | undefined) ?? null,
+      }
+    },
+
+    async send(id: string, text: string, clientId: string, origin?: string): Promise<unknown> {
+      return json(`/api/canopy-sessions/${encodeURIComponent(id)}/send`, {
+        method: 'POST',
+        body: JSON.stringify({ text, client_id: clientId, ...(origin ? { origin } : {}) }),
+      })
+    },
+
+    async fetchOlder(
+      id: string,
+      before: number,
+    ): Promise<{ messages: unknown[]; has_more_before: boolean }> {
+      return json(
+        `/api/canopy-sessions/${encodeURIComponent(id)}/messages?before=${encodeURIComponent(
+          String(before),
+        )}`,
+      )
+    },
+
+    // The viewer-liveness pair (`RunnerBinding.stream_desired`): attaching asks
+    // the bound runner to stream this session live, detaching lets it stop once
+    // the last viewer leaves. Best-effort by design — a caller fires these on
+    // mount/unmount and must never block rendering on the result.
+    async attach(id: string): Promise<void> {
+      await raw(`/api/canopy-sessions/${encodeURIComponent(id)}/attach`, { method: 'POST' })
+    },
+    async detach(id: string): Promise<void> {
+      await raw(`/api/canopy-sessions/${encodeURIComponent(id)}/detach`, { method: 'POST' })
+    },
+  }
+}
+
+export type CanopyRest = ReturnType<typeof createRest>

package/src/token.ts

@@ -0,0 +1,88 @@
+/**
+ * The delegated-token cache.
+ *
+ * Ported from ace-web's `frontend/src/canopy/token.ts`, with one dependency
+ * inverted and one global removed.
+ *
+ * **Inverted:** ace-web's version called ace-web's own `POST /api/canopy/token`
+ * through ace-web's generated API client. That is the one part of the flow that
+ * *must* stay host-specific — the `AppCredential` is a secret, so only the host
+ * backend can mint — so the client takes a `fetchToken` callback and knows
+ * nothing about how the host exchanges. That inversion is the whole reason this
+ * package can serve a Django host, a React SPA, and an iframe widget at once.
+ *
+ * **De-globalised:** ace-web held `cached` and `inflight` at module scope, which
+ * is fine for exactly one client per page. A widget can be mounted twice (two
+ * panels, or a host embedding two agents), and tests then leak state into each
+ * other. `createTokenStore` closes over its own state instead.
+ */
+
+/** What a host's token endpoint must return. `expiresAt` is opaque to the host
+ *  contract but must be parseable by `Date` — canopy sends ISO-8601. */
+export interface CanopyToken {
+  token: string
+  expiresAt: string
+}
+
+export type FetchToken = () => Promise<CanopyToken>
+
+export interface TokenStore {
+  /** Cached token, refetching when it is near expiry. `force` bypasses the
+   *  cache outright — used by the 401 retry, which must not trust our own
+   *  expiry bookkeeping when canopy has already rejected the token. */
+  get(force?: boolean): Promise<string>
+  /** Sync read for callers that cannot await — the WS URL builder, which has to
+   *  put the token in a query string. `null` before the first mint. */
+  peek(): string | null
+  /** Drop the cached token. For a host that knows the user signed out. */
+  clear(): void
+}
+
+/** Refetch this long before real expiry, so a request kicked off just under the
+ *  wire does not race expiry mid-flight. */
+const REFRESH_SKEW_MS = 5 * 60 * 1000
+
+/** A non-parseable `expiresAt` is treated as already-expired rather than cached
+ *  with `NaN`. `now < NaN - skew` is always false, so this was already forcing a
+ *  refetch every call in ace-web; making it explicit means the behaviour is
+ *  intended rather than a coincidence of NaN comparison. */
+function expiresAtMs(expiresAt: string): number {
+  const ms = new Date(expiresAt).getTime()
+  return Number.isNaN(ms) ? 0 : ms
+}
+
+export function createTokenStore(fetchToken: FetchToken): TokenStore {
+  let cached: { token: string; expiresAtMs: number } | null = null
+  // In-flight dedup. Without it, several components mounting in the same tick
+  // each call get() before any has a cached result, firing N concurrent mints —
+  // and N new DelegatedToken rows server-side. Every caller in that tick awaits
+  // the one request already underway.
+  let inflight: Promise<string> | null = null
+
+  return {
+    get(force = false) {
+      if (!force && cached && Date.now() < cached.expiresAtMs - REFRESH_SKEW_MS) {
+        return Promise.resolve(cached.token)
+      }
+      if (!inflight) {
+        inflight = fetchToken()
+          .then(({ token, expiresAt }) => {
+            cached = { token, expiresAtMs: expiresAtMs(expiresAt) }
+            return token
+          })
+          .finally(() => {
+            // Cleared even on rejection, so a transient failure does not poison
+            // every later call with the same stale rejected promise.
+            inflight = null
+          })
+      }
+      return inflight
+    },
+    peek() {
+      return cached ? cached.token : null
+    },
+    clear() {
+      cached = null
+    },
+  }
+}

package/src/ws.ts

@@ -0,0 +1,61 @@
+/**
+ * The session WebSocket URL.
+ *
+ * Ported from ace-web's `frontend/src/canopy/ws.ts`. The only change is that the
+ * token is passed in rather than read from a module global, so this is a pure
+ * function and testable without a token store.
+ *
+ * `base` is one of two shapes:
+ *   - a same-origin PATH (`/canopy` — a vite proxy in dev, or a shared ALB path
+ *     prefix in prod) with no scheme or host of its own;
+ *   - an absolute `http(s)://host[/path]` URL (canopy on a different host, which
+ *     is the normal case for an embedded widget).
+ *
+ * `WebSocket` needs an absolute `ws(s)://` URL either way, so a bare path
+ * borrows the current location's scheme and host; an absolute base keeps its own
+ * and only has its scheme swapped.
+ *
+ * The token rides as `?token=` because a WebSocket handshake cannot carry an
+ * `Authorization` header. canopy's `channels_auth` accepts DelegatedTokens on
+ * that query parameter for exactly this reason.
+ */
+
+export interface WsLocation {
+  protocol: string
+  host: string
+}
+
+/** `location` is injectable so this works in a worker, in a test, and in an
+ *  iframe — anywhere `window` may be absent or not the one you mean. */
+export function buildSessionWsUrl(
+  base: string,
+  sessionId: string,
+  token: string | null,
+  location?: WsLocation,
+): string {
+  const isAbsolute = /^https?:\/\//i.test(base)
+
+  let origin: string
+  let pathPrefix: string
+
+  if (isAbsolute) {
+    const url = new URL(base)
+    origin = `${url.protocol === 'https:' ? 'wss:' : 'ws:'}//${url.host}`
+    pathPrefix = url.pathname.replace(/\/$/, '')
+  } else {
+    const loc =
+      location ??
+      (typeof window !== 'undefined'
+        ? { protocol: window.location.protocol, host: window.location.host }
+        : { protocol: 'http:', host: 'localhost' })
+    origin = `${loc.protocol === 'https:' ? 'wss:' : 'ws:'}//${loc.host}`
+    pathPrefix = base.replace(/\/$/, '')
+  }
+
+  // No token means no session has been minted yet, in which case the caller
+  // should not be opening a socket. Left as a tokenless URL rather than thrown,
+  // matching ace-web: the connect will fail loudly at the server instead of
+  // turning a race into an exception in a render path.
+  const query = token ? `?token=${encodeURIComponent(token)}` : ''
+  return `${origin}${pathPrefix}/ws/canopy-sessions/${encodeURIComponent(sessionId)}/${query}`
+}