@yottagraph-app/aether-instructions 1.1.3 → 1.1.5

package/package.json

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

package/rules/agents.mdc

@@ -168,14 +168,189 @@ Once deployed, the agent is reachable through the Portal Gateway:
 ```
 Chat UI (pages/chat.vue)
   → POST NUXT_PUBLIC_GATEWAY_URL/api/agents/{tenantId}/{agentId}/query
-  → Portal Gateway proxies to Vertex AI Agent Engine
-  → Agent runs, returns response
+  → Portal Gateway proxies to Vertex AI Agent Engine (streamQuery)
+  → Agent runs (may invoke tools, make multiple LLM calls)
+  → Gateway collects the ADK event stream, extracts final text
   → Chat UI displays it
 ```
 
 The gateway URL and tenant ID come from `broadchurch.yaml` (injected as
-`NUXT_PUBLIC_GATEWAY_URL` and `NUXT_PUBLIC_TENANT_ORG_ID`). The chat page
-discovers available agents from the Portal config endpoint.
+`NUXT_PUBLIC_GATEWAY_URL` and `NUXT_PUBLIC_TENANT_ORG_ID`).
+
+### Agent Discovery
+
+The chat page discovers deployed agents by fetching the tenant config:
+
+```
+GET {NUXT_PUBLIC_GATEWAY_URL}/api/config/{NUXT_PUBLIC_TENANT_ORG_ID}
+```
+
+The response includes an `agents` array:
+
+```json
+{
+  "agents": [
+    { "name": "filing_analyst", "display_name": "Filing Analyst", "engine_id": "1234567890" },
+    { "name": "research_bot", "display_name": "Research Bot", "engine_id": "0987654321" }
+  ],
+  "features": { "chat": true, ... },
+  ...
+}
+```
+
+Each agent entry has:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Agent directory name (e.g. `filing_analyst`) |
+| `display_name` | `string` | Human-readable name for the UI |
+| `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`.
+
+**How agents get populated:** The portal discovers agents from two sources:
+1. **Firestore** — agents registered by the deploy workflow (`deploy-agent.yml`
+   calls `POST /api/agents/{tenantId}` to register)
+2. **Agent Engine API** — the portal also queries Vertex AI for reasoning
+   engines whose display name starts with the project name (e.g.
+   `my-project--filing_analyst`), catching agents that were deployed but
+   not yet registered
+
+Both sources are merged and deduplicated by name. If the config endpoint
+returns an empty `agents` array, no agents have been deployed yet.
+
+Use `useTenantConfig()` to fetch this config from Vue code:
+
+```typescript
+import { useTenantConfig } from '~/composables/useTenantConfig';
+
+const { config, fetchConfig } = useTenantConfig();
+await fetchConfig();
+
+const agents = config.value?.agents ?? [];
+const agentId = agents[0]?.engine_id; // use as {agentId} in query URLs
+```
+
+### Gateway Request
+
+```
+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" }
+```
+
+Omit `session_id` on the first message — the gateway auto-creates one.
+
+### Gateway Response Format
+
+```json
+{
+  "output": "The agent's final text response",
+  "session_id": "session-abc-123",
+  "events": [ /* raw ADK event stream */ ]
+}
+```
+
+| 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
+has `content.parts[]` where each part is one of:
+
+```json
+{ "text": "The agent's text response..." }
+{ "functionCall": { "name": "search", "args": { "q": "AAPL" } } }
+{ "functionResponse": { "name": "search", "response": { "results": [...] } } }
+```
+
+A typical stream for an agent that uses a tool:
+
+```json
+[
+  { "content": { "parts": [{ "functionCall": { "name": "search", "args": {"q": "AAPL 8-K"} } }], "role": "model" } },
+  { "content": { "parts": [{ "functionResponse": { "name": "search", "response": {"results": ["..."]} } }], "role": "tool" } },
+  { "content": { "parts": [{ "text": "Here is the summary of the 8-K filing..." }], "role": "model" } }
+]
+```
+
+The final text is the last `text` part that isn't in a `functionCall` or
+`functionResponse` event. Events may also arrive as JSON strings rather
+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`:
+
+```typescript
+import { extractAgentText } from '~/composables/useAgentChat';
+
+const response = await $fetch(url, { method: 'POST', body: { message } });
+const text = extractAgentText(response.output);
+```
+
+`extractAgentText` handles: plain strings, ADK event stream arrays (with
+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
+
+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`
+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:
+
+| 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 |
+| `done` | `{ "session_id": "...", "text": "..." }` | Stream complete with final text |
+
+For custom agent UIs that need streaming, import `readSSE`:
+
+```typescript
+import { readSSE } from '~/composables/useAgentChat';
+
+const res = await fetch(streamUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message: 'Hello' }),
+});
+
+for await (const { event, data } of readSSE(res)) {
+    if (event === 'text') console.log('Agent says:', data.text);
+    if (event === 'function_call') console.log('Calling:', data.name);
+    if (event === 'done') console.log('Session:', data.session_id);
+}
+```
+
+The `done` event always includes the final extracted text, so you don't
+need to track text deltas yourself.
 
 ## Agent Design Guidelines
 

package/rules/api.mdc

@@ -20,7 +20,9 @@ For full endpoint documentation, read the **elemental-api skill** in
 `skills/elemental-api/`. Start with `SKILL.md`, then `overview.md`.
 These files are copied from `@yottagraph-app/elemental-api-skill` during
 `npm install` (postinstall step) — if the directory is empty, run
-`npm install` first.
+`npm install` first. The skill docs contain detailed response shapes and
+edge cases that go beyond this rule's quick reference — **run `npm install`
+early** to make them available during initial exploration.
 
 Key files:
 - `entities.md` — entity search, details, and properties
@@ -51,6 +53,57 @@ Types are also imported from the client:
 import type { NamedEntityReport, GetNEIDResponse } from '@yottagraph-app/elemental-api/client';
 ```
 
+### Client Method Quick Reference
+
+All methods return data directly and throw on non-2xx responses.
+
+**Entity search and lookup:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getNEID` | `(params: { entityName, maxResults?, includeNames? })` | Lookup entity by name |
+| `findEntities` | `(body: FindEntitiesBody)` | Expression-based search (see `find.md`) |
+| `getNamedEntityReport` | `(neid: string)` | Entity details (name, aliases, type) |
+| `getEntityDetails` | `(neid: string)` | Alias for entity reports |
+
+**Properties and schema:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getSchema` | `()` | All entity types (flavors) and properties (PIDs) |
+| `getPropertyValues` | `(body: { eids: string, pids: string })` | Property values (eids/pids are JSON-stringified arrays!) |
+| `summarizeProperty` | `(pid: number)` | Summary stats for a property |
+
+**Relationships and graph:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getLinkedEntities` | `(neid, params?: { entity_type?, link_type? })` | Linked entities (person/org/location only) |
+| `getLinks` | `(sourceNeid, targetNeid, params?)` | Links between two specific entities |
+| `getLinkCounts` | `(sourceNeid, targetNeid)` | Link counts between entities |
+| `getNeighborhood` | `(centerNeid, params?)` | Neighboring entities |
+| `getGraphLayout` | `(centerNeid, params?)` | Graph layout for visualization |
+
+**News, events, and sentiment:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getArticle` | `(artid: string)` | Article by ID |
+| `getArticleText` | `(artid: string)` | Article full text |
+| `getEvent` | `(eveid: string)` | Event by ID |
+| `getEventsForEntity` | `(params: { neid, startTime?, endTime? })` | Events involving an entity |
+| `getMentions` | `(params: { neid, startTime?, endTime? })` | Mention codes for entities |
+| `getMentionCounts` | `(params: { neid, ... })` | Bucketed mention counts |
+| `getNamedEntitySentiment` | `(neid: string)` | Sentiment for an entity |
+
+**Other:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getHealth` | `()` | Health check |
+| `getStatus` | `()` | Server status and capabilities |
+| `adaMessage` | `(body: AdaMessageBody)` | Ada AI chat |
+
 ## Discovery-First Pattern
 
 The knowledge graph contains many entity types and properties, and new datasets
@@ -81,17 +134,49 @@ knowledge of what's in the graph.
 
 ## API Gotchas
 
-> **WARNING -- `getSchema()` response nesting**: The generated TypeScript types
-> put `flavors` and `properties` at the top level, but the actual API response
-> nests them under a `schema` key. Using `response.properties` directly will
-> crash with `Cannot read properties of undefined`. Always use:
+### `getSchema()` response is nested — WILL crash if you don't handle it
+
+The generated TypeScript types suggest `response.properties` and
+`response.flavors` exist at the top level. **They don't.** The API nests
+them under `response.schema`. This mismatch between types and reality
+causes `Cannot read properties of undefined` every time.
 
 ```typescript
+// WRONG — will crash at runtime despite TypeScript compiling fine:
+const res = await client.getSchema();
+const props = res.properties; // undefined!
+
+// CORRECT — always access through .schema:
 const res = await client.getSchema();
 const properties = res.schema?.properties ?? (res as any).properties ?? [];
 const flavors = res.schema?.flavors ?? (res as any).flavors ?? [];
 ```
 
+The `(res as any).properties` fallback is there in case the API is ever
+fixed to match the types. Use this pattern every time.
+
+### `getNamedEntityReport()` response is nested under `.report`
+
+Same problem as `getSchema()`. The TypeScript types suggest entity fields
+(`name`, `aliases`, `type`) exist at the top level. **They don't.** The
+API wraps them in a `.report` container. The generated client does NOT
+unwrap this automatically.
+
+```typescript
+// WRONG — name will be undefined:
+const res = await client.getNamedEntityReport(neid);
+const name = res.name; // undefined!
+
+// CORRECT — always access through .report:
+const res = await client.getNamedEntityReport(neid);
+const name = res.report?.name ?? (res as any).name ?? neid;
+const aliases = res.report?.aliases ?? (res as any).aliases ?? [];
+const type = res.report?.type ?? (res as any).type;
+```
+
+The `(res as any).name` fallback handles the case where the client is
+eventually fixed to unwrap the response.
+
 > **WARNING -- `getPropertyValues()` takes JSON-stringified arrays**: The `eids`
 > and `pids` parameters must be JSON-encoded strings, NOT native arrays. The
 > TypeScript type is `string`, not `string[]`. Passing a raw array will silently
@@ -114,6 +199,17 @@ financial instruments, events, and all other types are excluded — even
 though the schema shows relationships like `filed` connecting organizations
 to documents.
 
+**Why?** The knowledge graph has two layers. The **graph layer** models
+first-class entities (people, organizations, locations) as nodes with
+edges between them — this is what `getLinkedEntities` traverses. The
+**property layer** attaches everything else (documents, filings, financial
+instruments, events) as property values on graph nodes. Documents aren't
+"lesser" entities — they're stored differently because they're associated
+with specific graph nodes rather than standing independently in the graph.
+Understanding this distinction helps you generalize: if a target entity
+type doesn't appear in the `getLinkedEntities` response, it's a property-
+layer entity and you need `getPropertyValues` with the relationship PID.
+
 To traverse relationships to non-graph-node types, use `getPropertyValues`
 with the relationship PID instead. Relationship properties (`data_nindex`)
 return linked entity IDs as values. Zero-pad the returned IDs to 20
@@ -139,6 +235,51 @@ See the **cookbook** rule for a full "Get filings for a company" recipe.
   (`POST /elemental/find`). Best for filtered searches (by type, property,
   relationship). See `find.md` for the expression language.
 
+## Common Entity Relationships
+
+The knowledge graph connects entities through relationship properties
+(`data_nindex` PIDs). These are the most common patterns:
+
+| From | PID | To | How to traverse |
+|---|---|---|---|
+| Organization | `filed` | Document (filings) | `getPropertyValues` with the `filed` PID on the org's NEID |
+| Organization | `employs` | Person | `getLinkedEntities` (person is a graph node type) |
+| Person | `employed_by` | Organization | `getLinkedEntities` (organization is a graph node type) |
+| Organization | `headquartered_in` | Location | `getLinkedEntities` (location is a graph node type) |
+| Any entity | `related_to` | Any entity | `getLinkedEntities` for person/org/location; `getPropertyValues` for others |
+
+**Key constraint:** `getLinkedEntities` only works for three target types:
+**person**, **organization**, **location**. For documents, filings,
+articles, financial instruments, and events, use `getPropertyValues` with
+the relationship PID. See the cookbook rule (recipe #7) for a full filings
+example.
+
+**Traversal pattern for non-graph-node types:**
+
+```typescript
+// 1. Get the PID for the relationship
+const schema = await client.getSchema();
+const pids = schema.schema?.properties ?? [];
+const filedPid = pids.find((p: any) => p.name === 'filed')?.pid;
+
+// 2. Get linked entity IDs via getPropertyValues
+const res = await client.getPropertyValues({
+    eids: JSON.stringify([orgNeid]),
+    pids: JSON.stringify([filedPid]),
+});
+
+// 3. Pad IDs to 20 chars to form valid NEIDs
+const docNeids = res.values.map((v: any) => String(v.value).padStart(20, '0'));
+
+// 4. Get details for each linked entity (response is nested under .report)
+const reports = await Promise.all(
+    docNeids.map(async (neid: string) => {
+        const r = await client.getNamedEntityReport(neid);
+        return r.report ?? r;
+    }),
+);
+```
+
 ## Error Handling
 
 ```typescript

package/rules/architecture.mdc

@@ -133,9 +133,21 @@ Tenant-specific configuration generated during provisioning. Contains GCP projec
 
 ## Built-in Pages
 
-These pages ship with the template and can be kept, modified, or removed based on the app's needs:
-
-- `pages/chat.vue` -- Agent chat UI. Talks to deployed ADK agents through the Portal Gateway. Keep if the app uses AI agents.
-- `pages/mcp.vue` -- MCP Explorer. Browse and test MCP server tools. Keep if the app uses MCP servers.
-- `pages/entity-lookup.vue` -- Entity search tool. Useful for looking up NEIDs. Keep or remove based on the app.
+Recent template versions include these pages. They can be kept, modified,
+or removed based on the app's needs:
+
+- `pages/chat.vue` -- Agent chat UI. Uses `useAgentChat()` and
+  `useTenantConfig()` to discover deployed agents and stream responses
+  through the Portal Gateway. Keep if the app uses AI agents.
+- `pages/mcp.vue` -- MCP Explorer. Browse and test MCP server tools. Keep
+  if the app uses MCP servers.
+- `pages/entity-lookup.vue` -- Entity search tool. Useful for looking up
+  NEIDs. Keep or remove based on the app.
+
+**If these pages are missing** from your project, your project was created
+from an older template version. Create them from scratch — they're
+straightforward Vuetify pages. The key composables (`useAgentChat`,
+`useTenantConfig`) are included in all template versions and provide the
+connection logic. See the `agents` cursor rule for the gateway endpoints
+and response formats these pages use.
 

package/rules/cookbook.mdc

@@ -467,7 +467,7 @@ NOT supported — use `getPropertyValues` with the relationship PID instead.
                 docNeids.map(async (neid: string) => {
                     try {
                         const r = await client.getNamedEntityReport(neid);
-                        return r.name || neid;
+                        return r.report?.name ?? (r as any).name ?? neid;
                     } catch {
                         return neid;
                     }