@ai-matrx/agents 0.29.1 → 0.31.0

package/dist/context/react/index.d.cts

@@ -61,8 +61,13 @@ interface ContextDeliveredRef {
     /** SHA-256 hex of that text (UTF-8). */
     sha256: string;
 }
-/** What to view: a value's `delivered` element, its `on_request` text, or a `block`. */
-type ContextViewKind = "delivered" | "on_request" | "block";
+/**
+ * What to view: a value's `delivered` element, its `on_request` text, a
+ * `block`, or what the agent can `fetchable` for a value through a tool (the
+ * Organization: its selected scopes' values via `scope_system` — rendered when
+ * opened, never on the receipt; `source: "fetched_now"`).
+ */
+type ContextViewKind = "delivered" | "on_request" | "block" | "fetchable";
 interface ContextViewTarget {
     kind: ContextViewKind;
     /** The value's key, or the block's id. */
@@ -78,7 +83,14 @@ interface ContextViewedText {
     text: string;
     chars: number;
     sha256: string;
-    source: "preview" | "wire" | "conversation_prompt" | "turn_record";
+    /** `fetched_now`: a `fetchable` text — what the agent gets if it asks now. */
+    source: "preview" | "wire" | "conversation_prompt" | "turn_record" | "fetched_now";
+    /**
+     * `fetchable` only: `false` when the turn's agent cannot call the tool that
+     * returns it (tools off, excluded, a structured-output turn). `text` is then
+     * `""`; the screen says so with state, never shows content as fetchable.
+     */
+    available?: boolean;
 }
 /** The host's door to the viewer API — called only when a person opens a value. */
 type ContextViewLoader = (target: ContextViewTarget) => Promise<ContextViewedText>;
@@ -269,7 +281,9 @@ declare function InlineMaxInput({ value, inherited, cap, onCommit, disabled, lab
  * What the model READ for one value — fetched from the viewer when the detail
  * opens, never pushed (RULES.md §5b): its own element (`delivered`), the blocks
  * it rode with (`deliveredBlocks` — the Organization's catalog), and for an
- * on-request value what the `context` tool returns (`onRequest`). Verbatim;
+ * on-request value what the `context` tool returns (`onRequest`), and for a
+ * value the agent reads through a tool (`CONTEXT_FETCHABLE_ROWS`) what that tool
+ * returns now (`fetchable`, sized once loaded). Verbatim;
  * never the client's copy. With no receipt yet: a server-authoritative value
  * says the server fills it; anything else renders nothing (the host may show
  * the value the page will send, labelled so).
@@ -284,7 +298,8 @@ declare function ContextDeliveredValue({ row, load, className, }: {
 declare function DeliveredSection({ title, target, ref_, load, }: {
     title: string;
     target: ContextViewTarget;
-    ref_: ContextDeliveredRef;
+    /** The receipt's size; absent for a `fetchable` text, sized once it loads. */
+    ref_?: ContextDeliveredRef | undefined;
     load?: ContextViewLoader | undefined;
 }): react.JSX.Element;
 

package/dist/context/react/index.d.ts

@@ -61,8 +61,13 @@ interface ContextDeliveredRef {
     /** SHA-256 hex of that text (UTF-8). */
     sha256: string;
 }
-/** What to view: a value's `delivered` element, its `on_request` text, or a `block`. */
-type ContextViewKind = "delivered" | "on_request" | "block";
+/**
+ * What to view: a value's `delivered` element, its `on_request` text, a
+ * `block`, or what the agent can `fetchable` for a value through a tool (the
+ * Organization: its selected scopes' values via `scope_system` — rendered when
+ * opened, never on the receipt; `source: "fetched_now"`).
+ */
+type ContextViewKind = "delivered" | "on_request" | "block" | "fetchable";
 interface ContextViewTarget {
     kind: ContextViewKind;
     /** The value's key, or the block's id. */
@@ -78,7 +83,14 @@ interface ContextViewedText {
     text: string;
     chars: number;
     sha256: string;
-    source: "preview" | "wire" | "conversation_prompt" | "turn_record";
+    /** `fetched_now`: a `fetchable` text — what the agent gets if it asks now. */
+    source: "preview" | "wire" | "conversation_prompt" | "turn_record" | "fetched_now";
+    /**
+     * `fetchable` only: `false` when the turn's agent cannot call the tool that
+     * returns it (tools off, excluded, a structured-output turn). `text` is then
+     * `""`; the screen says so with state, never shows content as fetchable.
+     */
+    available?: boolean;
 }
 /** The host's door to the viewer API — called only when a person opens a value. */
 type ContextViewLoader = (target: ContextViewTarget) => Promise<ContextViewedText>;
@@ -269,7 +281,9 @@ declare function InlineMaxInput({ value, inherited, cap, onCommit, disabled, lab
  * What the model READ for one value — fetched from the viewer when the detail
  * opens, never pushed (RULES.md §5b): its own element (`delivered`), the blocks
  * it rode with (`deliveredBlocks` — the Organization's catalog), and for an
- * on-request value what the `context` tool returns (`onRequest`). Verbatim;
+ * on-request value what the `context` tool returns (`onRequest`), and for a
+ * value the agent reads through a tool (`CONTEXT_FETCHABLE_ROWS`) what that tool
+ * returns now (`fetchable`, sized once loaded). Verbatim;
  * never the client's copy. With no receipt yet: a server-authoritative value
  * says the server fills it; anything else renders nothing (the host may show
  * the value the page will send, labelled so).
@@ -284,7 +298,8 @@ declare function ContextDeliveredValue({ row, load, className, }: {
 declare function DeliveredSection({ title, target, ref_, load, }: {
     title: string;
     target: ContextViewTarget;
-    ref_: ContextDeliveredRef;
+    /** The receipt's size; absent for a `fetchable` text, sized once it loads. */
+    ref_?: ContextDeliveredRef | undefined;
     load?: ContextViewLoader | undefined;
 }): react.JSX.Element;
 

package/dist/context/react/index.js

@@ -16,6 +16,9 @@ var DEFAULT_INLINE_CAP = 5e4;
 var CONTEXT_ROW_BLOCKS = {
   organization: ["organization_catalog"]
 };
+var CONTEXT_FETCHABLE_ROWS = {
+  organization: "scope_system"
+};
 function unclaimedBlocks(blocks, rowKeys) {
   const claimed = /* @__PURE__ */ new Set();
   for (const key of rowKeys) for (const id of CONTEXT_ROW_BLOCKS[key] ?? []) claimed.add(id);
@@ -404,7 +407,7 @@ function ContextRulesTable({
   const comfortable = density === "comfortable";
   const present = GROUPS.filter((g) => rows.some((r) => r.origin === g.origin));
   const grouped = present.length > 1;
-  return /* @__PURE__ */ jsx3(TooltipProvider, { delayDuration: 300, titleTooltips: false, children: /* @__PURE__ */ jsxs3("div", { role: "table", "aria-label": "Context", "data-density": density, className: cn2("text-xs", className), children: [
+  return /* @__PURE__ */ jsx3(TooltipProvider, { delayDuration: 300, titleTooltips: false, children: /* @__PURE__ */ jsxs3("div", { role: "table", "aria-label": "Values", "data-density": density, className: cn2("text-xs", className), children: [
     /* @__PURE__ */ jsxs3(
       "div",
       {
@@ -421,7 +424,7 @@ function ContextRulesTable({
         ]
       }
     ),
-    rows.length === 0 ? /* @__PURE__ */ jsx3("div", { className: "px-2 py-3 text-center text-muted-foreground", children: "Nothing in context" }) : present.map((g) => /* @__PURE__ */ jsxs3("div", { role: "rowgroup", "aria-label": grouped ? g.label : void 0, children: [
+    rows.length === 0 ? /* @__PURE__ */ jsx3("div", { className: "px-2 py-3 text-center text-muted-foreground", children: "None" }) : present.map((g) => /* @__PURE__ */ jsxs3("div", { role: "rowgroup", "aria-label": grouped ? g.label : void 0, children: [
       grouped ? /* @__PURE__ */ jsx3(
         "div",
         {
@@ -755,7 +758,7 @@ import {
 
 // context/react/ContextDeliveredValue.tsx
 import * as React3 from "react";
-import { Skeleton, cn as cn4 } from "@ai-matrx/design-system";
+import { ErrorBox, Skeleton, cn as cn4 } from "@ai-matrx/design-system";
 import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
 function ContextDeliveredValue({
   row,
@@ -794,6 +797,14 @@ function ContextDeliveredValue({
         ref_: row.onRequest,
         load
       }
+    ) : null,
+    row.delivered && CONTEXT_FETCHABLE_ROWS[row.key] ? /* @__PURE__ */ jsx5(
+      DeliveredSection,
+      {
+        title: "Agent can fetch",
+        target: { kind: "fetchable", key: row.key },
+        load
+      }
     ) : null
   ] });
 }
@@ -812,7 +823,13 @@ function DeliveredSection({
     setLoaded({ state: "loading" });
     load({ kind, key }).then(
       (viewed) => {
-        if (live) setLoaded({ state: "done", text: viewed.text });
+        if (live)
+          setLoaded({
+            state: "done",
+            text: viewed.text,
+            chars: viewed.chars,
+            available: viewed.available !== false
+          });
       },
       (error) => {
         if (live)
@@ -826,12 +843,20 @@ function DeliveredSection({
       live = false;
     };
   }, [load, kind, key, attempt]);
+  const unavailable = loaded.state === "done" && !loaded.available;
   return /* @__PURE__ */ jsxs5("section", { className: "flex flex-col gap-1", "aria-label": title, "data-view-kind": kind, "data-view-key": key, children: [
     /* @__PURE__ */ jsxs5("div", { className: "flex items-baseline gap-2 text-xs", children: [
       /* @__PURE__ */ jsx5("span", { className: "font-medium", children: title }),
-      /* @__PURE__ */ jsx5("span", { className: "tabular-nums text-muted-foreground", children: `${formatChars(ref_.chars)} chars` })
+      unavailable ? /* @__PURE__ */ jsx5(
+        "span",
+        {
+          "data-testid": "context-delivered-unavailable",
+          className: "rounded border border-border px-1.5 text-[11px] text-muted-foreground",
+          children: "Not available to this agent"
+        }
+      ) : ref_ || loaded.state === "done" ? /* @__PURE__ */ jsx5("span", { className: "tabular-nums text-muted-foreground", children: `${formatChars(ref_ ? ref_.chars : loaded.state === "done" ? loaded.chars : 0)} chars` }) : null
     ] }),
-    !load ? /* @__PURE__ */ jsx5("span", { className: "text-xs text-muted-foreground", children: "\u2014" }) : loaded.state === "loading" ? /* @__PURE__ */ jsx5(Skeleton, { "data-testid": "context-delivered-loading", className: "h-16 w-full" }) : loaded.state === "error" ? /* @__PURE__ */ jsxs5("div", { className: "flex items-center gap-2 text-xs text-destructive", role: "alert", children: [
+    unavailable ? null : !load ? /* @__PURE__ */ jsx5("span", { className: "text-xs text-muted-foreground", children: "\u2014" }) : loaded.state === "loading" ? /* @__PURE__ */ jsx5(Skeleton, { "data-testid": "context-delivered-loading", className: "h-16 w-full" }) : loaded.state === "error" ? /* @__PURE__ */ jsxs5(ErrorBox, { as: "div", message: loaded.message, className: "flex items-center gap-2 text-xs text-destructive", children: [
       /* @__PURE__ */ jsx5("span", { className: "min-w-0 truncate", title: loaded.message, children: loaded.message }),
       /* @__PURE__ */ jsx5(
         "button",
@@ -842,7 +867,7 @@ function DeliveredSection({
           children: "Retry"
         }
       )
-    ] }) : /* @__PURE__ */ jsx5(
+    ] }) : loaded.text === "" ? /* @__PURE__ */ jsx5("span", { "data-testid": "context-delivered-empty", className: "text-xs text-muted-foreground", children: "None" }) : /* @__PURE__ */ jsx5(
       "pre",
       {
         "data-testid": "context-delivered-text",
@@ -1089,7 +1114,7 @@ function ContextRulesPanelBody({
       Input2,
       {
         type: "search",
-        "aria-label": "Search context",
+        "aria-label": "Search values",
         placeholder: "Search",
         value: query,
         onChange: (e) => setQuery(e.target.value),