@yottagraph-app/aether-instructions 1.1.28 → 1.1.29

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.28",
+    "version": "1.1.29",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/agents.mdc

@@ -111,19 +111,20 @@ adk deploy agent_engine \
 
 ## How Agents Reach the App
 
-Once deployed, the agent is reachable through the Portal Gateway:
+Once deployed, the app talks to Agent Engine directly — the portal is only
+in the auth path:
 
 ```
-App (useAgentChat composable)
-  → POST NUXT_PUBLIC_GATEWAY_URL/api/agents/{tenantId}/{agentId}/query
-  → Portal Gateway proxies to Vertex AI Agent Engine (streamQuery)
+Browser → Tenant Nitro Server (POST /api/agent/:agentId/stream)
+  → Portal /authorize (gets short-lived tenant SA token, cached 15 min)
+  → Agent Engine :streamQuery (direct, single hop)
   → Agent runs (may invoke tools, make multiple LLM calls)
-  → Gateway collects the ADK event stream, extracts final text
-  → App displays it
+  → Nitro re-emits ADK events as clean SSE to the browser
 ```
 
 The gateway URL and tenant ID come from `broadchurch.yaml` (injected as
-`NUXT_PUBLIC_GATEWAY_URL` and `NUXT_PUBLIC_TENANT_ORG_ID`).
+`NUXT_PUBLIC_GATEWAY_URL` and `NUXT_PUBLIC_TENANT_ORG_ID`). The token is
+minted for the tenant's GCP service account via SA impersonation.
 
 ### Agent Discovery
 
@@ -155,7 +156,8 @@ Each agent entry has:
 | `engine_id` | `string` | Vertex AI Agent Engine resource ID — used as `{agentId}` in query/stream URLs |
 
 The `engine_id` is the key value — it becomes the `{agentId}` path
-parameter in `POST /api/agents/{tenantId}/{agentId}/query`.
+parameter in `/api/agent/{agentId}/stream` (the local Nitro route) and
+the portal's `/authorize` endpoint.
 
 **How agents get populated:** The portal discovers agents from two sources:
 1. **Firestore** — agents registered by the deploy workflow (`deploy-agent.yml`
@@ -180,39 +182,24 @@ const agents = config.value?.agents ?? [];
 const agentId = agents[0]?.engine_id; // use as {agentId} in query URLs
 ```
 
-### Gateway Request
+### Streaming via the Local Nitro Route
 
-```
-POST {NUXT_PUBLIC_GATEWAY_URL}/api/agents/{tenantId}/{agentId}/query
-Content-Type: application/json
-
-{ "message": "Summarize the latest 8-K filing", "session_id": "optional-session-id" }
-```
+The `useAgentChat` composable calls `POST /api/agent/:agentId/stream` (the
+local Nitro route). This route handles token acquisition, session creation,
+and SSE parsing — the browser just sees clean Server-Sent Events.
 
-Omit `session_id` on the first message — the gateway auto-creates one.
+For custom server-side agent calls (e.g. background tasks), you can call the
+portal's `/authorize` endpoint directly and then use the token against
+Agent Engine:
 
-### Gateway Response Format
-
-```json
-{
-  "output": "The agent's final text response",
-  "session_id": "session-abc-123",
-  "events": [ /* raw ADK event stream */ ]
-}
+```typescript
+const auth = await $fetch(`${gatewayUrl}/api/agents/${orgId}/${agentId}/authorize`, {
+    method: 'POST',
+    body: { user_id: 'background-task', create_session: false },
+});
+// auth.token, auth.engine_url, auth.expires_in
 ```
 
-| Field | Type | Description |
-|---|---|---|
-| `output` | `string \| any[]` | Usually the agent's final text. Falls back to the raw `events` array if the gateway couldn't extract text. |
-| `session_id` | `string` | Pass back on subsequent messages to continue the conversation. |
-| `events` | `any[]` | Full ADK event stream. Useful for debugging or building UIs that show intermediate agent steps. |
-
-**Important:** `output` is NOT always a string. When the agent's response
-involves complex tool chains, the gateway's server-side extraction may miss
-the text and return the raw events array instead. Always use
-`extractAgentText()` to parse `output` safely rather than treating it as a
-string directly.
-
 ### ADK Event Stream Format
 
 The `events` array contains one object per step the agent took. Each event
@@ -240,13 +227,11 @@ than objects — always handle both.
 
 ### Parsing Agent Responses (Non-Streaming)
 
-For one-shot calls (server routes, background tasks) where streaming isn't
-needed, use the buffered `/query` endpoint with `extractAgentText`:
+For non-streaming use cases (e.g. extracting text from a buffered response),
+use `extractAgentText`:
 
 ```typescript
 import { extractAgentText } from '~/composables/useAgentChat';
-
-const response = await $fetch(url, { method: 'POST', body: { message } });
 const text = extractAgentText(response.output);
 ```
 
@@ -255,28 +240,20 @@ JSON-string or object elements), single event objects, and several legacy
 Agent Engine response shapes. It skips `functionCall` / `functionResponse`
 events and returns the agent's final text.
 
-### Streaming Responses
+### Streaming SSE Events
 
-The gateway also exposes a streaming endpoint that returns Server-Sent
-Events as the agent executes. **The `useAgentChat` composable uses this by
-default** — it tries `/stream` first and falls back to `/query`
+The local Nitro route (`POST /api/agent/:agentId/stream`) returns
+Server-Sent Events. The `useAgentChat` composable handles these
 automatically.
 
-```
-POST {NUXT_PUBLIC_GATEWAY_URL}/api/agents/{tenantId}/{agentId}/stream
-Content-Type: application/json
-
-{ "message": "Summarize the latest 8-K filing", "session_id": "optional" }
-```
-
-The response is an SSE stream with these event types:
+SSE event types:
 
 | Event | Data Shape | Description |
 |---|---|---|
 | `text` | `{ "text": "..." }` | Agent text output (replaces previous text) |
 | `function_call` | `{ "name": "...", "args": {...} }` | Agent is calling a tool |
 | `function_response` | `{ "name": "...", "response": {...} }` | Tool returned a result |
-| `error` | `{ "message": "..." }` | Error during processing |
+| `error` | `{ "message": "...", "code": "..." }` | Error during processing (`code` is `PERMISSION_DENIED` for IAM failures) |
 | `done` | `{ "session_id": "...", "text": "..." }` | Stream complete with final text |
 
 For custom agent UIs that need streaming, import `readSSE`:

package/rules/architecture.mdc

@@ -125,7 +125,21 @@ Aether apps are more than just a Nuxt SPA. The project contains three additional
 
 ### `agents/` -- ADK Agents (Python)
 
-Each subdirectory is a self-contained Python agent that deploys to Vertex AI Agent Engine. See the `agents` cursor rule for development patterns. Agents are deployed via the Broadchurch Portal UI or the `/deploy_agent` Cursor command, both of which trigger `deploy-agent.yml`. Once deployed, agents are reachable through the Portal Gateway (`NUXT_PUBLIC_GATEWAY_URL`). Use the `useAgentChat` composable to build a chat UI that talks to them.
+Each subdirectory is a self-contained Python agent that deploys to Vertex AI Agent Engine. See the `agents` cursor rule for development patterns. Agents are deployed via the Broadchurch Portal UI or the `/deploy_agent` Cursor command, both of which trigger `deploy-agent.yml`. Use the `useAgentChat` composable to build a chat UI that talks to them.
+
+**Agent query path:** The app talks to Agent Engine directly — the portal is
+only in the auth path. The flow is:
+
+1. Tenant Nitro route (`server/api/agent/[agentId]/stream.post.ts`) calls the
+   Portal Gateway's `/authorize` endpoint to get a short-lived (15 min) GCP
+   access token minted for the tenant's service account.
+2. The Nitro route uses that token to call Agent Engine's `:streamQuery`
+   directly — streaming data does NOT flow through the portal.
+3. Tokens are cached server-side for their TTL.
+
+If you see a 403 from Agent Engine, the tenant's service account is missing
+IAM permissions (`roles/aiplatform.user`). Check the Broadchurch portal's
+project detail page for IAM health status.
 
 ### `mcp-servers/` -- MCP Servers (Python)
 
@@ -140,10 +154,11 @@ Tenant-specific configuration generated during provisioning. Contains GCP projec
 The template ships composables for interacting with the Lovelace platform.
 Use these to build whatever UI fits the app:
 
-- **`useAgentChat()`** -- Send messages to deployed ADK agents through the
-  Portal Gateway. Handles streaming, session management, and response
-  parsing. See the `agents` cursor rule for gateway endpoints and response
-  formats.
+- **`useAgentChat()`** -- Send messages to deployed ADK agents. Uses the
+  local Nitro streaming route (`/api/agent/:agentId/stream`) which calls
+  Agent Engine directly with a tenant SA token. Handles streaming, session
+  management, and response parsing. Shows clear error messages when IAM
+  permissions are missing. See the `agents` cursor rule for details.
 - **`useTenantConfig()`** -- Fetch the tenant's runtime config (deployed
   agents, feature flags, MCP servers) from the Portal Gateway.
 - **`useElementalClient()`** -- When using the Elemental API from the client,