create-astram-app 0.14.0 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "license": "MIT",
   "description": "Scaffolder for a new Astram app — emits a running, framework-enforced NestJS server (deny-by-default, built-in auth/identity to switch on) and, with --with-frontend, a React admin/auth UI, over the immutable @astram/* framework packages.",
   "type": "module",

package/template/frontend/package.json

@@ -12,7 +12,7 @@
     "test": "node scripts/run-tests.mjs"
   },
   "dependencies": {
-    "@astram/frontend-core": "^0.11.0",
+    "@astram/frontend-core": "^0.12.0",
     "@astram/sdk": "^0.2.1",
     "@radix-ui/react-alert-dialog": "^1.1.19",
     "@radix-ui/react-avatar": "^1.1.10",

package/template/frontend/src/auth/AuthContext.jsx

@@ -13,6 +13,7 @@ import { createContext, useContext, useEffect, useMemo, useRef, useState } from
 import { createShieldClient, systemClock } from '@astram/sdk';
 import {
   createAccountService,
+  createAgentService,
   createAuditService,
   createAuthService,
   createCrossTenantService,
@@ -29,6 +30,7 @@ import {
 import { createWebHttpClient } from '../platform/httpClient';
 import { createWebSessionStore } from '../platform/sessionStore';
 import { createWebShieldTransport } from '../platform/shieldTransport';
+import { createAgentStreamTransport } from '../platform/agentStreamTransport';
 import { saveReturnPath } from '../platform/returnPathStore';
 import {
   afterDeviceConfirmed,
@@ -121,6 +123,16 @@ export function AuthProvider({ children }) {
       // In-app notices (G-027): the header bell and Announcements menus and their unread counts
       // (`/account/notifications`; shell/useNotificationCounts.js polls the counts).
       notifications: createNotificationService(http),
+      // The AI assistant client (G-036): JSON calls (cancel, task view) over `http`; the SSE
+      // streams over the web stream transport, which reads the live token and, on a 401 before
+      // the first byte only, shares `http`'s single-flight refresh. No chat UI ships yet.
+      agent: createAgentService(
+        http,
+        createAgentStreamTransport({
+          getToken: () => tokenRef.current,
+          refreshAfterUnauthorized: (sentToken) => http.refreshAfterUnauthorized(sentToken),
+        }),
+      ),
       // The @astram/sdk ShieldClient (Phase E slice 1) — a UX-convenience projection of
       // the caller's OWN coarse grants, fetched once per session via `getAuthFacts`.
       // Built once, so every session boundary calls `shield.reset()` (establishSession,
@@ -152,6 +164,7 @@ export function AuthProvider({ children }) {
     serviceAccounts,
     account,
     notifications,
+    agent,
     shield,
     store,
     rawAuth,
@@ -457,6 +470,9 @@ export function AuthProvider({ children }) {
       account,
       // The shared notification service (list / unread count / mark read; G-027) — same client.
       notifications,
+      // The AI assistant client (open/continue/cancel/view/replay; G-036). Gate any UI on
+      // `can('identity:agent:chat')`; the server's decide() is the real check.
+      agent,
       // The @astram/sdk ShieldClient (Phase E slice 1) — exposed for any page that needs
       // direct access (e.g. a forced re-fetch). Most call sites should prefer `useCan`.
       shield,
@@ -491,6 +507,7 @@ export function AuthProvider({ children }) {
       serviceAccounts,
       account,
       notifications,
+      agent,
       shield,
       profile,
       mustReenroll,

package/template/frontend/src/platform/agentStreamTransport.js

@@ -0,0 +1,168 @@
+/**
+ * The WEB agent stream transport — the platform half of @astram/frontend-core's injected
+ * `AgentStreamTransport` (G-036 M1). `fetch` with a streamed body (never `EventSource`, which
+ * cannot send a bearer token or a POST body) to the same `/api` base as `httpClient.js`,
+ * decoded with `TextDecoder` (stream mode, so a UTF-8 sequence split across reads is kept
+ * whole). The service in frontend-core parses the SSE frames, folds them and runs the stall
+ * watchdog; this file only moves bytes.
+ *
+ * Auth: `Authorization: Bearer <getToken()>`. A `401` BEFORE THE FIRST BYTE (the response status,
+ * so no stream byte has been read) runs `refreshAfterUnauthorized(sentToken)` once — the
+ * refreshing http client's shared single-flight refresh, so the stream never spends a refresh
+ * token in parallel with a JSON call — then retries once with the rotated token. `expired` /
+ * `superseded` ⇒ status 401, `unavailable` ⇒ status 0, no retry. Once a `200` has arrived there is
+ * never a refresh: the stream is bound to the session, not the access token (SPEC §10), so token
+ * expiry mid-stream does not cut it.
+ *
+ * `open()` never throws: a network failure or abort is `{ status: 0 }`. A refusal (any non-200)
+ * carries its parsed `{ code, retryable }` body, else `error: null`.
+ */
+
+const BASE = '/api'; // the same base as httpClient.js (Vite proxies /api to the server)
+
+function refusalBody(data) {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) return null;
+  return typeof data.code === 'string' && data.code !== '' && typeof data.retryable === 'boolean'
+    ? { code: data.code, retryable: data.retryable }
+    : null;
+}
+
+async function readJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+/** Release a response body we will not read (best-effort). */
+function discard(res) {
+  try {
+    const p = res.body && typeof res.body.cancel === 'function' ? res.body.cancel() : null;
+    if (p && typeof p.catch === 'function') p.catch(() => {});
+  } catch {
+    /* nothing to release */
+  }
+}
+
+const noop = () => {};
+
+/**
+ * @param {{ getToken: () => (string | null),
+ *           refreshAfterUnauthorized?: (sentToken: string) => Promise<
+ *             { kind: 'rotated', accessToken: string } | { kind: 'expired' | 'superseded' | 'unavailable' }>,
+ *           fetchImpl?: typeof fetch }} deps
+ *   `getToken` — the current access token (AuthContext's token ref).
+ *   `refreshAfterUnauthorized` — the refreshing http client's method of the same name.
+ *   `fetchImpl` — for tests; defaults to the global `fetch`.
+ * @returns {import('@astram/frontend-core').AgentStreamTransport}
+ */
+export function createAgentStreamTransport({ getToken, refreshAfterUnauthorized, fetchImpl } = {}) {
+  const doFetch = (...args) => (fetchImpl ?? globalThis.fetch)(...args);
+
+  return {
+    async open({ method, path, body, lastEventId, signal }) {
+      // Our own controller, so close() can stop the read; the caller's signal feeds it.
+      const ctl = new AbortController();
+      const onAbort = () => ctl.abort();
+      if (signal) {
+        if (signal.aborted) ctl.abort();
+        else signal.addEventListener('abort', onAbort);
+      }
+      const detach = () => {
+        if (signal) signal.removeEventListener('abort', onAbort);
+      };
+      const failed = (status, error = null) => {
+        detach();
+        return { status, error, chunks: null, close: noop };
+      };
+
+      const send = (token) => {
+        const headers = { accept: 'text/event-stream' };
+        if (token) headers.authorization = `Bearer ${token}`;
+        if (method === 'POST') headers['content-type'] = 'application/json';
+        if (typeof lastEventId === 'number') headers['last-event-id'] = String(lastEventId);
+        return doFetch(`${BASE}${path}`, {
+          method,
+          headers,
+          body: method === 'POST' ? JSON.stringify(body ?? {}) : undefined,
+          cache: 'no-store',
+          signal: ctl.signal,
+        });
+      };
+
+      let res;
+      const sent = getToken ? getToken() : null;
+      try {
+        res = await send(sent);
+      } catch {
+        return failed(0);
+      }
+
+      // 401 before the first byte: one shared refresh, then one retry.
+      if (res.status === 401 && sent && typeof refreshAfterUnauthorized === 'function') {
+        discard(res);
+        let outcome;
+        try {
+          outcome = await refreshAfterUnauthorized(sent);
+        } catch {
+          outcome = { kind: 'unavailable' };
+        }
+        if (outcome && outcome.kind === 'rotated' && outcome.accessToken) {
+          try {
+            res = await send(outcome.accessToken);
+          } catch {
+            return failed(0);
+          }
+        } else if (outcome && (outcome.kind === 'expired' || outcome.kind === 'superseded')) {
+          return failed(401);
+        } else {
+          return failed(0);
+        }
+      }
+
+      if (res.status !== 200) {
+        const error = refusalBody(await readJson(res));
+        return failed(res.status, error);
+      }
+      if (!res.body || typeof res.body.getReader !== 'function') {
+        return failed(0);
+      }
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let closed = false;
+      const close = () => {
+        if (closed) return;
+        closed = true;
+        detach();
+        try {
+          const p = reader.cancel();
+          if (p && typeof p.catch === 'function') p.catch(() => {});
+        } catch {
+          /* already released */
+        }
+        ctl.abort();
+      };
+
+      async function* chunks() {
+        try {
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+              const tail = decoder.decode();
+              if (tail) yield tail;
+              return;
+            }
+            const text = decoder.decode(value, { stream: true });
+            if (text) yield text;
+          }
+        } finally {
+          close();
+        }
+      }
+
+      return { status: 200, error: null, chunks: chunks(), close };
+    },
+  };
+}

package/template/frontend/src/platform/agentStreamTransport.test.mjs

@@ -0,0 +1,273 @@
+// agentStreamTransport.test.mjs — the web agent stream transport (G-036 M1, SPEC
+// agent-read-capabilities §5 frontend-core, §14 item 7): fetch with a streamed body, bearer token,
+// and a refresh ONLY before the first byte (one shared refresh, one retry); never after a 200.
+//
+//   node --test src/platform/agentStreamTransport.test.mjs
+//
+// `fetch` is injected (`fetchImpl`), so this runs under plain Node (>= 20: Response,
+// ReadableStream, TextEncoder/TextDecoder are globals).
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { createAgentStreamTransport } from './agentStreamTransport.js';
+
+const enc = new TextEncoder();
+
+/** A 200 SSE response whose body yields `parts` (strings or byte arrays), then optionally fails. */
+function sseResponse(parts, { failAfter = false } = {}) {
+  let i = 0;
+  const body = new ReadableStream({
+    pull(controller) {
+      if (i < parts.length) {
+        const p = parts[i++];
+        controller.enqueue(typeof p === 'string' ? enc.encode(p) : p);
+      } else if (failAfter) {
+        controller.error(new Error('connection reset'));
+      } else {
+        controller.close();
+      }
+    },
+  });
+  return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } });
+}
+
+const json = (status, data) =>
+  new Response(JSON.stringify(data), { status, headers: { 'content-type': 'application/json' } });
+
+/** fetch stub: answers in order, records each call. */
+function fetchSeq(...answers) {
+  const calls = [];
+  const fetchImpl = async (url, init) => {
+    calls.push({ url, init });
+    const a = answers.shift();
+    if (a instanceof Error) throw a;
+    return typeof a === 'function' ? a() : a;
+  };
+  return { fetchImpl, calls };
+}
+
+async function readAll(chunks) {
+  let text = '';
+  for await (const c of chunks) text += c;
+  return text;
+}
+
+const signal = () => new AbortController().signal;
+const FRAME = 'id: 1\nevent: step\ndata: {}\n\n';
+
+describe('createAgentStreamTransport', () => {
+  test('POST to /api with bearer, JSON body and SSE accept; 200 streams decoded text', async () => {
+    const { fetchImpl, calls } = fetchSeq(sseResponse([': hb\n\n', FRAME]));
+    const t = createAgentStreamTransport({ getToken: () => 'tok-1', fetchImpl });
+    const res = await t.open({
+      method: 'POST',
+      path: '/agent/tasks',
+      body: { message: 'Hi' },
+      signal: signal(),
+    });
+    assert.equal(res.status, 200);
+    assert.equal(res.error, null);
+    assert.equal(await readAll(res.chunks), `: hb\n\n${FRAME}`);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].url, '/api/agent/tasks');
+    assert.equal(calls[0].init.method, 'POST');
+    assert.equal(calls[0].init.headers.authorization, 'Bearer tok-1');
+    assert.equal(calls[0].init.headers.accept, 'text/event-stream');
+    assert.equal(calls[0].init.headers['content-type'], 'application/json');
+    assert.equal(calls[0].init.body, '{"message":"Hi"}');
+  });
+
+  test('GET replay sends Last-Event-ID and no body', async () => {
+    const { fetchImpl, calls } = fetchSeq(sseResponse([]));
+    const t = createAgentStreamTransport({ getToken: () => 'tok-1', fetchImpl });
+    const res = await t.open({
+      method: 'GET',
+      path: '/agent/tasks/x/events',
+      body: null,
+      lastEventId: 7,
+      signal: signal(),
+    });
+    assert.equal(res.status, 200);
+    assert.equal(calls[0].init.headers['last-event-id'], '7');
+    assert.equal(calls[0].init.body, undefined);
+    assert.equal(calls[0].init.headers['content-type'], undefined);
+  });
+
+  test('a UTF-8 sequence split across reads is decoded whole', async () => {
+    const bytes = enc.encode('data: "— 𝔸"\n\n');
+    const { fetchImpl } = fetchSeq(
+      sseResponse([bytes.subarray(0, 8), bytes.subarray(8, 10), bytes.subarray(10)]),
+    );
+    const res = await createAgentStreamTransport({ getToken: () => 't', fetchImpl }).open({
+      method: 'GET',
+      path: '/p',
+      body: null,
+      signal: signal(),
+    });
+    assert.equal(await readAll(res.chunks), 'data: "— 𝔸"\n\n');
+  });
+
+  test('401 before the first byte: one refresh, one retry with the rotated token', async () => {
+    const { fetchImpl, calls } = fetchSeq(
+      json(401, { message: 'Unauthorized' }),
+      sseResponse([FRAME]),
+    );
+    const refreshes = [];
+    const t = createAgentStreamTransport({
+      getToken: () => 'old',
+      refreshAfterUnauthorized: async (sent) => {
+        refreshes.push(sent);
+        return { kind: 'rotated', accessToken: 'new' };
+      },
+      fetchImpl,
+    });
+    const res = await t.open({
+      method: 'POST',
+      path: '/agent/tasks',
+      body: { message: 'Hi' },
+      signal: signal(),
+    });
+    assert.deepEqual(refreshes, ['old']);
+    assert.equal(calls.length, 2);
+    assert.equal(calls[1].init.headers.authorization, 'Bearer new');
+    assert.equal(calls[1].init.body, '{"message":"Hi"}');
+    assert.equal(res.status, 200);
+    assert.equal(await readAll(res.chunks), FRAME);
+  });
+
+  test('a second 401 after the retry is returned: no second refresh', async () => {
+    const { fetchImpl, calls } = fetchSeq(json(401, null), json(401, null));
+    let refreshes = 0;
+    const t = createAgentStreamTransport({
+      getToken: () => 'old',
+      refreshAfterUnauthorized: async () => {
+        refreshes += 1;
+        return { kind: 'rotated', accessToken: 'new' };
+      },
+      fetchImpl,
+    });
+    const res = await t.open({ method: 'POST', path: '/p', body: {}, signal: signal() });
+    assert.equal(res.status, 401);
+    assert.equal(res.chunks, null);
+    assert.equal(refreshes, 1);
+    assert.equal(calls.length, 2);
+  });
+
+  test('expired / superseded ⇒ 401, unavailable ⇒ 0, a throwing refresh ⇒ 0; never a retry', async () => {
+    for (const [outcome, status] of [
+      [{ kind: 'expired' }, 401],
+      [{ kind: 'superseded' }, 401],
+      [{ kind: 'unavailable' }, 0],
+      [new Error('boom'), 0],
+    ]) {
+      const { fetchImpl, calls } = fetchSeq(json(401, null));
+      const t = createAgentStreamTransport({
+        getToken: () => 'old',
+        refreshAfterUnauthorized: async () => {
+          if (outcome instanceof Error) throw outcome;
+          return outcome;
+        },
+        fetchImpl,
+      });
+      const res = await t.open({ method: 'POST', path: '/p', body: {}, signal: signal() });
+      assert.equal(res.status, status);
+      assert.equal(res.chunks, null);
+      assert.equal(calls.length, 1);
+    }
+  });
+
+  test('after a 200 there is never a refresh: a failing stream or a token change mid-stream', async () => {
+    const { fetchImpl, calls } = fetchSeq(sseResponse([FRAME], { failAfter: true }));
+    let token = 'tok-1';
+    let refreshes = 0;
+    const t = createAgentStreamTransport({
+      getToken: () => token,
+      refreshAfterUnauthorized: async () => {
+        refreshes += 1;
+        return { kind: 'rotated', accessToken: 'x' };
+      },
+      fetchImpl,
+    });
+    const res = await t.open({ method: 'POST', path: '/p', body: {}, signal: signal() });
+    assert.equal(res.status, 200);
+    const it = res.chunks[Symbol.asyncIterator]();
+    assert.equal((await it.next()).value, FRAME);
+    token = 'tok-2'; // another tab refreshed: the open stream is unaffected
+    await assert.rejects(it.next());
+    assert.equal(refreshes, 0);
+    assert.equal(calls.length, 1);
+  });
+
+  test('no token ⇒ no Authorization header and no refresh on 401', async () => {
+    const { fetchImpl, calls } = fetchSeq(json(401, null));
+    let refreshes = 0;
+    const t = createAgentStreamTransport({
+      getToken: () => null,
+      refreshAfterUnauthorized: async () => {
+        refreshes += 1;
+        return { kind: 'rotated', accessToken: 'x' };
+      },
+      fetchImpl,
+    });
+    const res = await t.open({ method: 'POST', path: '/p', body: {}, signal: signal() });
+    assert.equal(res.status, 401);
+    assert.equal(calls[0].init.headers.authorization, undefined);
+    assert.equal(refreshes, 0);
+  });
+
+  test('a refusal carries its parsed { code, retryable } body; other bodies ⇒ null', async () => {
+    const { fetchImpl } = fetchSeq(
+      json(409, { code: 'task_busy', retryable: true, extra: 'ignored' }),
+      json(503, { message: 'server text' }),
+    );
+    const t = createAgentStreamTransport({ getToken: () => 't', fetchImpl });
+    const a = await t.open({ method: 'POST', path: '/p', body: {}, signal: signal() });
+    assert.deepEqual(a.error, { code: 'task_busy', retryable: true });
+    assert.equal(a.status, 409);
+    const b = await t.open({ method: 'POST', path: '/p', body: {}, signal: signal() });
+    assert.equal(b.status, 503);
+    assert.equal(b.error, null);
+  });
+
+  test('network failure ⇒ status 0; an aborted signal aborts the fetch', async () => {
+    const { fetchImpl } = fetchSeq(new TypeError('Failed to fetch'));
+    const t = createAgentStreamTransport({ getToken: () => 't', fetchImpl });
+    assert.equal(
+      (await t.open({ method: 'POST', path: '/p', body: {}, signal: signal() })).status,
+      0,
+    );
+
+    let seenSignal;
+    const t2 = createAgentStreamTransport({
+      getToken: () => 't',
+      fetchImpl: async (_u, init) => {
+        seenSignal = init.signal;
+        throw new DOMException('aborted', 'AbortError');
+      },
+    });
+    const ctl = new AbortController();
+    ctl.abort();
+    assert.equal(
+      (await t2.open({ method: 'POST', path: '/p', body: {}, signal: ctl.signal })).status,
+      0,
+    );
+    assert.equal(seenSignal.aborted, true);
+  });
+
+  test('close() ends the stream and aborts the request', async () => {
+    let seenSignal;
+    const t = createAgentStreamTransport({
+      getToken: () => 't',
+      fetchImpl: async (_u, init) => {
+        seenSignal = init.signal;
+        return sseResponse([FRAME, FRAME, FRAME]);
+      },
+    });
+    const res = await t.open({ method: 'GET', path: '/p', body: null, signal: signal() });
+    const it = res.chunks[Symbol.asyncIterator]();
+    await it.next();
+    res.close();
+    assert.equal(seenSignal.aborted, true);
+    const next = await it.next().catch(() => ({ done: true }));
+    assert.equal(next.done, true);
+  });
+});

package/template/server/package.json

@@ -21,13 +21,13 @@
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
-    "@astram/core": "1.14.0",
-    "@astram/engine": "0.16.2",
-    "@astram/guard": "0.27.0",
+    "@astram/core": "1.15.0",
+    "@astram/engine": "0.17.0",
+    "@astram/guard": "0.28.0",
     "@astram/guide": "^0.2.8",
-    "@astram/identity": "0.25.0",
-    "@astram/messaging": "0.1.13",
-    "@astram/migrate": "0.7.4",
+    "@astram/identity": "0.26.0",
+    "@astram/messaging": "0.1.14",
+    "@astram/migrate": "0.7.5",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",
     "@nestjs/core": "^11.2.7",

package/template/server/src/main.ts

@@ -22,7 +22,13 @@ export async function bootstrap(): Promise<void> {
   await resolveBootSecrets();
   const { AppModule } = await import('./app.module');
   const config = loadAppConfig();
-  const app = await NestFactory.create<NestExpressApplication>(AppModule, { bufferLogs: false });
+  // `rawBody: true` keeps the request bytes in `req.rawBody` beside the parsed JSON. `@astram/agent`
+  // parses its own bodies from those bytes (strict JSON, duplicate keys refused); without it every
+  // agent POST answers 503 agent_unavailable. Other routes are unaffected.
+  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+    bufferLogs: false,
+    rawBody: true,
+  });
   // On SIGTERM/SIGINT (PM2 restart, deploy) run the framework's shutdown hooks: background jobs
   // stop, the HTTP server finishes its in-flight requests, then every DB pool and Redis client
   // closes. Without this line Node exits with no hook run. Give your process manager a stop