@guuey/agent-client 0.16.11 → 0.16.12

package/dist/index.d.ts

@@ -11,5 +11,5 @@ export { ingestMessageFrame } from "./blocks.js";
 export { sortHistoryCards, toolNameFor } from "./history.js";
 export { Reducer } from "@silverprotocol/core";
 export type { AgEvent, AgReduceResult, AgMessage, AgBlock, AgClientCapabilities, AgHitlAnswer, } from "@silverprotocol/core";
-export type { AgentMessage, HistoryCard, ProfileLinkRequest, ThreadIdStore, GenerateId, InvokeRequest, InvokeTransport, AgentInvokeAdapters, AgentInvokeHistoryAdapter, AgentInvokeStatus, HistoryLoadResult, StallRecoveryOptions, UseAgentInvokeOptions, UseAgentInvokeReturn, } from "./types.js";
+export type { AgentMessage, HistoryCard, ProfileLinkRequest, ThreadIdStore, GenerateId, InvokeRequest, InvokeTransport, AgentInvokeAdapters, AgentInvokeHistoryAdapter, AgentInvokeStatus, HistoryLoadResult, StallRecoveryOptions, UseAgentInvokeOptions, PageContext, UseAgentInvokeReturn, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,gBAAgB,EAChB,KAAK,cAAc,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,sBAAsB,EACtB,KAAK,6BAA6B,EAClC,iBAAiB,EACjB,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,uBAAuB,EACvB,aAAa,EACb,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,KAAK,2BAA2B,GACjC,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,eAAe,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAKjD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAM7D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EACV,OAAO,EACP,cAAc,EACd,SAAS,EACT,OAAO,EAIP,oBAAoB,EACpB,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,gBAAgB,EAChB,KAAK,cAAc,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,sBAAsB,EACtB,KAAK,6BAA6B,EAClC,iBAAiB,EACjB,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,uBAAuB,EACvB,aAAa,EACb,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,KAAK,2BAA2B,GACjC,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,eAAe,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAKjD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAM7D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EACV,OAAO,EACP,cAAc,EACd,SAAS,EACT,OAAO,EAIP,oBAAoB,EACpB,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -152,6 +152,16 @@ export interface StallRecoveryOptions {
      */
     probeAttempts?: number;
 }
+/**
+ * Where the user is standing (guuey#524): the embedding page, as the host
+ * knows it. `path` + `title` only by design — nothing scraped; `context` is
+ * an optional short host-declared line (the pod caps it server-side).
+ */
+export interface PageContext {
+    path: string;
+    title: string;
+    context?: string;
+}
 export interface UseAgentInvokeOptions {
     /** Pod base URL (with or without a trailing `/agent/invoke`). Chat is disabled when null. */
     endpointUrl: string | null;
@@ -179,14 +189,28 @@ export interface UseAgentInvokeOptions {
      */
     capabilities?: AgClientCapabilities;
     /**
-     * Where the user IS (guuey#398) — a short context line the embedding
-     * surface owns ("The user is signed in to the guuey builder console…"),
-     * sent on every invoke. The pod composes it into the MODEL's input only:
-     * the persisted thread and this hook's optimistic user message never
-     * contain it. ≤500 chars (the pod refuses longer). The surface is the
-     * one place that knows this; the agent's static system prompt cannot.
+    /**
+     * The host PAGE the user is viewing (guuey#524 v1 — the page-aware
+     * ephemeral turn): URL path + title, plus an optional short host-declared
+     * context string. Sent on the invoke body per turn; read at send time, so
+     * an SPA host updates it on route change and the next turn carries the
+     * new page. TRUST LIVES POD-SIDE, none here: the pod frames this as
+     * UNTRUSTED page content into the model input for that turn only, flags
+     * the turn `pageContextPresent` (never client-claimed), and switches the
+     * durable sinks off for it (memory/profile/fold/home — the pass-3
+     * ephemeral-turn contract). The client's only job is carriage.
+     */
+    pageContext?: PageContext;
+    /**
+     * The agent-mode PIN for this surface (guuey#527/#566 — the guest/auth
+     * axis). Selection is SERVER-DERIVED from the caller's REAL auth state;
+     * this param only pins WITHIN permission: an authed caller may pin
+     * `"guest"` (preview-as-visitor), a guest pinning `"auth"` is clamped
+     * server-side, and an unrecognized key is ignored — all fail-soft, an
+     * embed never breaks. Absent = pure derivation. Modes are subset-only
+     * voice overlays, never added privilege.
      */
-    surfaceContext?: string;
+    mode?: string;
     /**
      * Stall recovery for a half-dead stream (guuey#192). A connection that dies
      * WITHOUT erroring (TCP alive, zero bytes, no `done`) would otherwise leave

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/useAgentInvoke.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAgentInvoke.d.ts","sourceRoot":"","sources":["../src/useAgentInvoke.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAW,KAAK,oBAAoB,EAAuB,MAAM,sBAAsB,CAAC;AAM/F,OAAO,KAAK,EAGV,YAAY,EAEZ,iBAAiB,EAGjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAMpB;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC,EAAE,oBAEnD,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,eAAe,EAAE,YAAY,EAAE,GAC9B,kBAAkB,CAIpB;AAED,uFAAuF;AACvF,eAAO,MAAM,uBAAuB;;;IAGlC;;;;;;;OAOG;;CAEK,CAAC;AAcX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EAAE,EACvB,cAAc,EAAE,MAAM,GACrB,OAAO,GAAG,WAAW,CAOvB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CAygBhF"}
+{"version":3,"file":"useAgentInvoke.d.ts","sourceRoot":"","sources":["../src/useAgentInvoke.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAW,KAAK,oBAAoB,EAAuB,MAAM,sBAAsB,CAAC;AAM/F,OAAO,KAAK,EAGV,YAAY,EAEZ,iBAAiB,EAGjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAMpB;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC,EAAE,oBAEnD,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,eAAe,EAAE,YAAY,EAAE,GAC9B,kBAAkB,CAIpB;AAED,uFAAuF;AACvF,eAAO,MAAM,uBAAuB;;;IAGlC;;;;;;;OAOG;;CAEK,CAAC;AAcX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EAAE,EACvB,cAAc,EAAE,MAAM,GACrB,OAAO,GAAG,WAAW,CAOvB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CA0hBhF"}

package/dist/useAgentInvoke.js

@@ -322,6 +322,18 @@ export function useAgentInvoke(opts) {
     const clearProfileLinkRequest = useCallback(() => {
         setProfileLinkRequest(null);
     }, []);
+    // guuey#524: `send` is memoized on [endpointUrl, appId, status, signal] —
+    // options read inside it are otherwise frozen at memo time. pageContext's
+    // whole contract is read-at-SEND-time freshness (SPA route changes must
+    // ride the next turn), so it goes through a live ref, the same discipline
+    // as every live-read value in the kit layer.
+    const pageContextRef = useRef(opts.pageContext);
+    pageContextRef.current = opts.pageContext;
+    // guuey#566: same live-ref discipline — a surface's mode can change
+    // mid-session (a guest signs in and the host flips rep → agent); the
+    // NEXT turn carries the new mode.
+    const modeRef = useRef(opts.mode);
+    modeRef.current = opts.mode;
     const send = useCallback(async (input) => {
         // An already-aborted external signal refuses the send outright —
         // before the optimistic transcript push, so nothing is left to undo.
@@ -509,12 +521,16 @@ export function useAgentInvoke(opts) {
                 ...(threadIdRef.current ? { threadId: threadIdRef.current } : {}),
                 clientMessageId,
                 ...(capabilities !== undefined ? { capabilities } : {}),
-                // guuey#398: the embedding surface's context line — the pod
-                // composes it into the MODEL's input only; the persisted thread
-                // and this hook's optimistic user message stay clean.
-                ...(opts.surfaceContext !== undefined
-                    ? { surfaceContext: opts.surfaceContext }
+                // guuey#524: the page-aware turn's carriage — read at send time
+                // (SPA route changes ride the NEXT turn). All trust semantics
+                // are pod-side; see the option's docblock.
+                ...(pageContextRef.current !== undefined
+                    ? { pageContext: pageContextRef.current }
                     : {}),
+                // guuey#566: the client-named agent mode — carriage only (live
+                // ref, read at send time); every semantic (validation, fallback,
+                // subset) is pod-side.
+                ...(modeRef.current !== undefined ? { mode: modeRef.current } : {}),
             };
             // The wire walk lives in `invokeTurn` (the pure per-turn generator —
             // its docblock owns the switch semantics); this hook only maps each

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/agent-client",
-  "version": "0.16.11",
+  "version": "0.16.12",
   "description": "Client SDK for Guuey's agent runtime: the `useAgentInvoke` React hook + pure SSE helpers that speak the /agent/invoke streaming contract, plus the paginated thread-history read plane. Host adapters (storage / id / transport) are injected, so it runs on web (Next) and React Native alike.",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@silverprotocol/core": "0.5.3",
-    "@guuey/mcp-apps-host": "0.16.11"
+    "@guuey/mcp-apps-host": "0.16.12"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/index.ts

@@ -104,5 +104,6 @@ export type {
   HistoryLoadResult,
   StallRecoveryOptions,
   UseAgentInvokeOptions,
+  PageContext,
   UseAgentInvokeReturn,
 } from "./types.js";

package/src/types.ts

@@ -162,6 +162,17 @@ export interface StallRecoveryOptions {
   probeAttempts?: number;
 }
 
+
+/**
+ * Where the user is standing (guuey#524): the embedding page, as the host
+ * knows it. `path` + `title` only by design — nothing scraped; `context` is
+ * an optional short host-declared line (the pod caps it server-side).
+ */
+export interface PageContext {
+  path: string;
+  title: string;
+  context?: string;
+}
 export interface UseAgentInvokeOptions {
   /** Pod base URL (with or without a trailing `/agent/invoke`). Chat is disabled when null. */
   endpointUrl: string | null;
@@ -189,14 +200,28 @@ export interface UseAgentInvokeOptions {
    */
   capabilities?: AgClientCapabilities;
   /**
-   * Where the user IS (guuey#398) — a short context line the embedding
-   * surface owns ("The user is signed in to the guuey builder console…"),
-   * sent on every invoke. The pod composes it into the MODEL's input only:
-   * the persisted thread and this hook's optimistic user message never
-   * contain it. ≤500 chars (the pod refuses longer). The surface is the
-   * one place that knows this; the agent's static system prompt cannot.
+  /**
+   * The host PAGE the user is viewing (guuey#524 v1 — the page-aware
+   * ephemeral turn): URL path + title, plus an optional short host-declared
+   * context string. Sent on the invoke body per turn; read at send time, so
+   * an SPA host updates it on route change and the next turn carries the
+   * new page. TRUST LIVES POD-SIDE, none here: the pod frames this as
+   * UNTRUSTED page content into the model input for that turn only, flags
+   * the turn `pageContextPresent` (never client-claimed), and switches the
+   * durable sinks off for it (memory/profile/fold/home — the pass-3
+   * ephemeral-turn contract). The client's only job is carriage.
+   */
+  pageContext?: PageContext;
+  /**
+   * The agent-mode PIN for this surface (guuey#527/#566 — the guest/auth
+   * axis). Selection is SERVER-DERIVED from the caller's REAL auth state;
+   * this param only pins WITHIN permission: an authed caller may pin
+   * `"guest"` (preview-as-visitor), a guest pinning `"auth"` is clamped
+   * server-side, and an unrecognized key is ignored — all fail-soft, an
+   * embed never breaks. Absent = pure derivation. Modes are subset-only
+   * voice overlays, never added privilege.
    */
-  surfaceContext?: string;
+  mode?: string;
   /**
    * Stall recovery for a half-dead stream (guuey#192). A connection that dies
    * WITHOUT erroring (TCP alive, zero bytes, no `done`) would otherwise leave

package/src/useAgentInvoke.ts

@@ -356,6 +356,19 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     setProfileLinkRequest(null);
   }, []);
 
+  // guuey#524: `send` is memoized on [endpointUrl, appId, status, signal] —
+  // options read inside it are otherwise frozen at memo time. pageContext's
+  // whole contract is read-at-SEND-time freshness (SPA route changes must
+  // ride the next turn), so it goes through a live ref, the same discipline
+  // as every live-read value in the kit layer.
+  const pageContextRef = useRef(opts.pageContext);
+  pageContextRef.current = opts.pageContext;
+  // guuey#566: same live-ref discipline — a surface's mode can change
+  // mid-session (a guest signs in and the host flips rep → agent); the
+  // NEXT turn carries the new mode.
+  const modeRef = useRef(opts.mode);
+  modeRef.current = opts.mode;
+
   const send = useCallback(
     async (input: string) => {
       // An already-aborted external signal refuses the send outright —
@@ -538,12 +551,16 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
           ...(threadIdRef.current ? { threadId: threadIdRef.current } : {}),
           clientMessageId,
           ...(capabilities !== undefined ? { capabilities } : {}),
-          // guuey#398: the embedding surface's context line — the pod
-          // composes it into the MODEL's input only; the persisted thread
-          // and this hook's optimistic user message stay clean.
-          ...(opts.surfaceContext !== undefined
-            ? { surfaceContext: opts.surfaceContext }
+          // guuey#524: the page-aware turn's carriage — read at send time
+          // (SPA route changes ride the NEXT turn). All trust semantics
+          // are pod-side; see the option's docblock.
+          ...(pageContextRef.current !== undefined
+            ? { pageContext: pageContextRef.current }
             : {}),
+          // guuey#566: the client-named agent mode — carriage only (live
+          // ref, read at send time); every semantic (validation, fallback,
+          // subset) is pod-side.
+          ...(modeRef.current !== undefined ? { mode: modeRef.current } : {}),
         };
 
         // The wire walk lives in `invokeTurn` (the pure per-turn generator —