@ai-matrx/chat 0.7.16 → 0.7.17

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @ai-matrx/chat
 
+## 0.7.17
+### Unreleased
+### a turn carries what the person attached (lane A1, Applet builder)
+
+- **`runHeadlessAgentJson({ resources })`** and **`continueAgentJson({ resources })`**: the person's "+" picks (`Resource[]`) go
+  through THE attach path (`attachResourceToConversation`) on the turn's conversation before it executes — a stored file by its
+  file id (`processed_document` in request.context, then the server's `file → conversation` edge), every other kind as its typed
+  resource block. Never the message (THE USER-INPUT LAW). A pick that cannot be attached fails the turn naming it.
+  New export `attachTurnResources`. Tests: `a-turn-carries-what-the-person-attached.test.ts`.
+- **Consumer action:** none (additive options).
+
 ## 0.7.16
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/dist/agents/redux/execution-system/thunks/continue-agent-json.d.ts

@@ -19,6 +19,7 @@
  */
 import type { ChatDispatch, ChatRootState } from "../../../../store/root-state.js";
 import type { RequestInitiation } from "../../../types/instance.types.js";
+import type { Resource } from "../../../resources/types.js";
 import { type HostTurnInput } from "./execute-instance.thunk.js";
 import { type AdoptedAgentJsonOptions, type HeadlessAgentJsonResult } from "./run-headless-agent-json.js";
 export interface ContinueAgentJsonOptions extends Pick<AdoptedAgentJsonOptions, "surfaceKey" | "timeoutMs" | "pollIntervalMs" | "settleMs" | "expect" | "onResult" | "signal" | "failureMessages"> {
@@ -29,6 +30,12 @@ export interface ContinueAgentJsonOptions extends Pick<AdoptedAgentJsonOptions,
     hostTurn?: HostTurnInput;
     /** Per-turn named context: each key is written on the instance; `null` removes it. */
     context?: Record<string, unknown>;
+    /**
+     * What the person attached, sent with THIS turn through THE attach path (see
+     * `HeadlessAgentJsonOptions.resources`). A file already on the conversation is an
+     * idempotent no-op; every other kind rides this turn again.
+     */
+    resources?: readonly Resource[];
     /** "user" when the person pressed send; "auto" for a host-started round. Default by turn kind. */
     initiation?: RequestInitiation;
     /** Fires the instant the turn's request exists (a live view binds to it). */

package/dist/agents/redux/execution-system/thunks/continue-agent-json.js

@@ -3,7 +3,8 @@ import { setUserInputText } from "../instance-user-input/instance-user-input.sli
 import { executeInstance } from "./execute-instance.thunk.js";
 import { loadConversation } from "./load-conversation.thunk.js";
 import {
-  adoptHeadlessAgentJson
+  adoptHeadlessAgentJson,
+  attachTurnResources
 } from "./run-headless-agent-json.js";
 function continuationTurnProblem(opts) {
   const typed = typeof opts.userInput === "string" && opts.userInput.trim().length > 0;
@@ -25,6 +26,7 @@ async function continueAgentJson(dispatch, getState, opts) {
     for (const [key] of context.filter(([, value]) => value === null)) dispatch(removeContextEntry({ conversationId, key }));
     if (writes.length) dispatch(setContextEntries({ conversationId, entries: writes.map(([key, value]) => ({ key, value })) }));
     if (opts.userInput) dispatch(setUserInputText({ conversationId, text: opts.userInput }));
+    await attachTurnResources(dispatch, getState, conversationId, opts.resources);
     let requestId = null;
     const sent = await dispatch(
       executeInstance({

package/dist/agents/redux/execution-system/thunks/run-headless-agent-json.d.ts

@@ -30,6 +30,7 @@ import type { MessagePart } from "@ai-matrx/agents/generated/stream-events";
 import type { ContextAnchor, SourceFeature, RequestInitiation } from "../../../types/instance.types.js";
 import type { ApplicationScope } from "../../../types/scope.types.js";
 import type { AnyMandateKey } from "@ai-matrx/agents/mandates";
+import type { Resource } from "../../../resources/types.js";
 export interface HeadlessAgentJsonOptions {
     /** Exact agent to run. Mutually exclusive with mandateKey and shortcutId. */
     agentId?: string;
@@ -185,6 +186,17 @@ export interface HeadlessAgentJsonOptions {
      * exists once, not per call site — blocked on launcher-level attach support.
      */
     messageParts?: MessagePart[];
+    /**
+     * What the person ATTACHED for this run (files, notes, links, documents — the
+     * "+" picker's `Resource`s). Each goes through THE attach path
+     * (`attachResourceToConversation`) on the launched conversation before it
+     * executes: a stored file is held by its file id (`processed_document` in
+     * request.context until the server keeps its `file → conversation` edge), every
+     * other kind rides the turn as its typed resource block. Never pasted into
+     * `userInput` (THE USER-INPUT LAW). Forces the two-step path, like
+     * `messageParts`. A pick that cannot be attached fails the run, out loud.
+     */
+    resources?: readonly Resource[];
     /** Per-feature user-facing failure copy. */
     failureMessages?: {
         /** Stream errored and the request carries no usable message. */
@@ -338,3 +350,10 @@ export interface AdoptedAgentJsonOptions {
  * throws; resolves a structured result, exactly like `runHeadlessAgentJson`.
  */
 export declare function adoptHeadlessAgentJson(dispatch: ChatDispatch, getState: () => ChatRootState, opts: AdoptedAgentJsonOptions): Promise<HeadlessAgentJsonResult>;
+/**
+ * Attach the person's picks to a conversation before its turn executes — THE attach
+ * path, loaded on demand (only a run that carries resources pays for it). Throws
+ * naming the first pick that could not be attached (the attach path has already
+ * said why on screen).
+ */
+export declare function attachTurnResources(dispatch: ChatDispatch, getState: () => ChatRootState, conversationId: string, resources: readonly Resource[] | undefined): Promise<void>;

package/dist/agents/redux/execution-system/thunks/run-headless-agent-json.js

@@ -279,7 +279,7 @@ async function launchAndWait(dispatch, getState, opts) {
   const pollMs = Math.max(opts.pollIntervalMs ?? DEFAULT_POLL_MS, 100);
   const settleMs = opts.settleMs ?? DEFAULT_SETTLE_MS;
   const msgs = { ...DEFAULT_MESSAGES, ...opts.failureMessages };
-  const twoStep = opts.messageParts !== void 0;
+  const twoStep = opts.messageParts !== void 0 || (opts.resources?.length ?? 0) > 0;
   let conversationId = null;
   let requestIdAnnounced = false;
   const announceRequestId = (id) => {
@@ -350,12 +350,15 @@ async function launchAndWait(dispatch, getState, opts) {
     conversationId = launch.conversationId;
     let requestId = launch.requestId;
     if (twoStep) {
-      dispatch(
-        setUserInputMessageParts({
-          conversationId,
-          parts: opts.messageParts ?? null
-        })
-      );
+      if (opts.messageParts !== void 0) {
+        dispatch(
+          setUserInputMessageParts({
+            conversationId,
+            parts: opts.messageParts ?? null
+          })
+        );
+      }
+      await attachTurnResources(dispatch, getState, conversationId, opts.resources);
       const exec = await dispatch(
         executeInstance({ conversationId, onRequestId: announceRequestId })
       ).unwrap();
@@ -592,8 +595,17 @@ function fuzzyFallback(fullResponse) {
   if (!fullResponse) return null;
   return extractFirstJson(fullResponse, { allowFuzzy: true })?.value ?? null;
 }
+async function attachTurnResources(dispatch, getState, conversationId, resources) {
+  if (!resources?.length) return;
+  const { attachResourceToConversation, resourceLabel } = await import("../../../components/inputs/resources/attach-resource.js");
+  for (const resource of resources) {
+    const ok = await attachResourceToConversation({ dispatch, getState }, conversationId, resource);
+    if (!ok) throw new Error(`Could not attach ${resourceLabel(resource)}.`);
+  }
+}
 export {
   adoptHeadlessAgentJson,
+  attachTurnResources,
   failWarnedOutputMissingKeys,
   livePosture,
   mandateOutputUnusableSentence,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/chat",
-  "version": "0.7.16",
+  "version": "0.7.17",
   "description": "THE one AI Matrx person-to-agent chat system: the full chat (running agents, conversations, tool calls, streaming, context, surfaces, voice) as explicit per-module subpaths @ai-matrx/chat/<domain>/<module> (no wildcards: scripts/public-modules.json) over a host contract (/host, /host/react) whose only required value is a db. One chat, one renderer: the old kernel entries (., /external-store, /matrx, /react, /tools, styles.css, tokens.css) are retired.",
   "type": "module",
   "license": "MIT",
@@ -4681,15 +4681,16 @@
     "server-only": "^0.0.1",
     "uuid": "^14.0.2",
     "zod": "^4.6.5",
-    "@ai-matrx/alchemy": "latest",
+    "@ai-matrx/agents": "latest",
     "@ai-matrx/associations": "latest",
     "@ai-matrx/browser-audio": "latest",
-    "@ai-matrx/agents": "latest",
-    "@ai-matrx/canvas": "latest",
+    "@ai-matrx/alchemy": "latest",
     "@ai-matrx/content-ir": "latest",
+    "@ai-matrx/canvas": "latest",
+    "@ai-matrx/data": "latest",
     "@ai-matrx/design-system": "latest",
+    "@ai-matrx/diff": "latest",
     "@ai-matrx/icons": "latest",
-    "@ai-matrx/data": "latest",
     "@ai-matrx/kit": "latest",
     "@ai-matrx/media": "latest",
     "@ai-matrx/print": "latest",
@@ -4698,7 +4699,6 @@
     "@ai-matrx/records-ui": "latest",
     "@ai-matrx/rich-content": "latest",
     "@ai-matrx/rich-editor": "latest",
-    "@ai-matrx/diff": "latest",
     "@ai-matrx/content-ir-react": "latest"
   },
   "devDependencies": {
@@ -4818,5 +4818,5 @@
     "check:side-effects": "node ../scripts/check-side-effects-listed.mjs . && node ../scripts/check-side-effects-listed.mjs --self-test",
     "check:public-surface": "node ./scripts/sync-public-surface.mjs --check && node ./scripts/sync-public-surface.mjs --self-test"
   },
-  "gitHead": "6158809f49ab5fe092f5dc6c56c60898eb0f92a6"
+  "gitHead": "d9101c14c9a0338c4468cfd4c7d18aa5400a5762"
 }