@ai-matrx/agents 0.11.4 → 0.12.1

package/dist/content-transfer/index.d.cts

@@ -1,8 +1,58 @@
 import { B as MatrxTransport, w as MatrxRuntimeOperationEvent, v as MatrxRuntimeExecutionStatus, d as MatrxCancelResponse } from '../operations--f5ko9Su.cjs';
-import { Snapshot, Draft } from '@ai-matrx/kit/content-transfer';
+import { PageAction, Payload, Snapshot, Draft, TransferOutcome, TransferTarget } from '@ai-matrx/kit/content-transfer';
 import { MatrxStreamEnvelope } from '../stream/ndjson.cjs';
 import '../stream/sse.cjs';
 
+/** Bind once in a host; every menu and declared surface inherits these actions. */
+type MatrxTransferDestination = "notes" | "scratch" | "document" | "workbook" | "task" | "attach" | "chat" | "assistant" | "tools" | "code";
+interface MatrxTransferContent {
+    label: string;
+    markdown: string;
+    plainText: string;
+    payload: Payload;
+    snapshot: Snapshot;
+    draft: Draft;
+    table?: {
+        name: string;
+        headers: string[];
+        rows: string[][];
+    };
+    signal: AbortSignal;
+}
+type MatrxTransferPorts = Partial<Record<MatrxTransferDestination, (content: MatrxTransferContent) => Promise<TransferOutcome>>>;
+type MatrxTransferAction = PageAction & {
+    group: "save" | "chat";
+    hint: string;
+    /** Only these actions are offered for a manually prepared revision. */
+    prepared: true;
+};
+/** Serializes the captured CURRENT revision, never re-reads the host's source. */
+declare function createMatrxTransferActions(ports: MatrxTransferPorts): MatrxTransferAction[];
+
+type MatrxTransferIdentity = {
+    userId: string;
+    organizationId: string;
+};
+type SaveResult = {
+    ok: boolean;
+    id?: string;
+    href?: string;
+    error?: string;
+};
+interface MatrxTransferBindings {
+    getIdentity(): MatrxTransferIdentity;
+    saveNote(content: MatrxTransferContent, folder: string): Promise<TransferTarget>;
+    saveDocument(content: MatrxTransferContent): Promise<SaveResult>;
+    saveWorkbook(content: MatrxTransferContent): Promise<SaveResult>;
+    openNotes(content: MatrxTransferContent): void | Promise<void>;
+    openTask(content: MatrxTransferContent): void | Promise<void>;
+    openCode(content: MatrxTransferContent): void | Promise<void>;
+    openAttachment(target: TransferTarget): void | Promise<void>;
+    openChat(content: MatrxTransferContent, mode: "chat" | "assistant" | "tools", identity: MatrxTransferIdentity): void | Promise<void>;
+}
+/** Portable workflow and failure semantics; hosts bind only their concrete services and UI openers. */
+declare function createMatrxTransferPorts(bindings: MatrxTransferBindings): Required<MatrxTransferPorts>;
+
 type MatrxContentTransferStatus = "completed" | "failed" | "cancelled" | "detached" | "unavailable";
 interface MatrxContentTransferIdentity {
     requestId: string;
@@ -81,4 +131,4 @@ declare function createMatrxContentTransferAdapter(options: MatrxContentTransfer
 };
 type MatrxContentTransferAdapter = ReturnType<typeof createMatrxContentTransferAdapter>;
 
-export { type MatrxContentTransferAdapter, type MatrxContentTransferAdapterOptions, type MatrxContentTransferDbResponse, type MatrxContentTransferDbRow, type MatrxContentTransferIdentity, type MatrxContentTransferLaunchInput, type MatrxContentTransferProgress, type MatrxContentTransferQuery, type MatrxContentTransferResult, type MatrxContentTransferStatus, type MatrxContentTransferSupabase, createMatrxContentTransferAdapter };
+export { type MatrxContentTransferAdapter, type MatrxContentTransferAdapterOptions, type MatrxContentTransferDbResponse, type MatrxContentTransferDbRow, type MatrxContentTransferIdentity, type MatrxContentTransferLaunchInput, type MatrxContentTransferProgress, type MatrxContentTransferQuery, type MatrxContentTransferResult, type MatrxContentTransferStatus, type MatrxContentTransferSupabase, type MatrxTransferAction, type MatrxTransferBindings, type MatrxTransferContent, type MatrxTransferDestination, type MatrxTransferIdentity, type MatrxTransferPorts, createMatrxContentTransferAdapter, createMatrxTransferActions, createMatrxTransferPorts };

package/dist/content-transfer/index.d.ts

@@ -1,8 +1,58 @@
 import { B as MatrxTransport, w as MatrxRuntimeOperationEvent, v as MatrxRuntimeExecutionStatus, d as MatrxCancelResponse } from '../operations-Dp4ut-ac.js';
-import { Snapshot, Draft } from '@ai-matrx/kit/content-transfer';
+import { PageAction, Payload, Snapshot, Draft, TransferOutcome, TransferTarget } from '@ai-matrx/kit/content-transfer';
 import { MatrxStreamEnvelope } from '../stream/ndjson.js';
 import '../stream/sse.js';
 
+/** Bind once in a host; every menu and declared surface inherits these actions. */
+type MatrxTransferDestination = "notes" | "scratch" | "document" | "workbook" | "task" | "attach" | "chat" | "assistant" | "tools" | "code";
+interface MatrxTransferContent {
+    label: string;
+    markdown: string;
+    plainText: string;
+    payload: Payload;
+    snapshot: Snapshot;
+    draft: Draft;
+    table?: {
+        name: string;
+        headers: string[];
+        rows: string[][];
+    };
+    signal: AbortSignal;
+}
+type MatrxTransferPorts = Partial<Record<MatrxTransferDestination, (content: MatrxTransferContent) => Promise<TransferOutcome>>>;
+type MatrxTransferAction = PageAction & {
+    group: "save" | "chat";
+    hint: string;
+    /** Only these actions are offered for a manually prepared revision. */
+    prepared: true;
+};
+/** Serializes the captured CURRENT revision, never re-reads the host's source. */
+declare function createMatrxTransferActions(ports: MatrxTransferPorts): MatrxTransferAction[];
+
+type MatrxTransferIdentity = {
+    userId: string;
+    organizationId: string;
+};
+type SaveResult = {
+    ok: boolean;
+    id?: string;
+    href?: string;
+    error?: string;
+};
+interface MatrxTransferBindings {
+    getIdentity(): MatrxTransferIdentity;
+    saveNote(content: MatrxTransferContent, folder: string): Promise<TransferTarget>;
+    saveDocument(content: MatrxTransferContent): Promise<SaveResult>;
+    saveWorkbook(content: MatrxTransferContent): Promise<SaveResult>;
+    openNotes(content: MatrxTransferContent): void | Promise<void>;
+    openTask(content: MatrxTransferContent): void | Promise<void>;
+    openCode(content: MatrxTransferContent): void | Promise<void>;
+    openAttachment(target: TransferTarget): void | Promise<void>;
+    openChat(content: MatrxTransferContent, mode: "chat" | "assistant" | "tools", identity: MatrxTransferIdentity): void | Promise<void>;
+}
+/** Portable workflow and failure semantics; hosts bind only their concrete services and UI openers. */
+declare function createMatrxTransferPorts(bindings: MatrxTransferBindings): Required<MatrxTransferPorts>;
+
 type MatrxContentTransferStatus = "completed" | "failed" | "cancelled" | "detached" | "unavailable";
 interface MatrxContentTransferIdentity {
     requestId: string;
@@ -81,4 +131,4 @@ declare function createMatrxContentTransferAdapter(options: MatrxContentTransfer
 };
 type MatrxContentTransferAdapter = ReturnType<typeof createMatrxContentTransferAdapter>;
 
-export { type MatrxContentTransferAdapter, type MatrxContentTransferAdapterOptions, type MatrxContentTransferDbResponse, type MatrxContentTransferDbRow, type MatrxContentTransferIdentity, type MatrxContentTransferLaunchInput, type MatrxContentTransferProgress, type MatrxContentTransferQuery, type MatrxContentTransferResult, type MatrxContentTransferStatus, type MatrxContentTransferSupabase, createMatrxContentTransferAdapter };
+export { type MatrxContentTransferAdapter, type MatrxContentTransferAdapterOptions, type MatrxContentTransferDbResponse, type MatrxContentTransferDbRow, type MatrxContentTransferIdentity, type MatrxContentTransferLaunchInput, type MatrxContentTransferProgress, type MatrxContentTransferQuery, type MatrxContentTransferResult, type MatrxContentTransferStatus, type MatrxContentTransferSupabase, type MatrxTransferAction, type MatrxTransferBindings, type MatrxTransferContent, type MatrxTransferDestination, type MatrxTransferIdentity, type MatrxTransferPorts, createMatrxContentTransferAdapter, createMatrxTransferActions, createMatrxTransferPorts };

package/dist/content-transfer/index.js

@@ -1,7 +1,68 @@
+// content-transfer/destinations.ts
+import {
+  readTransferCell,
+  serialize
+} from "@ai-matrx/kit/content-transfer";
+var DESTINATIONS = [
+  { key: "notes", label: "Save to Notes", hint: "Choose a note or create one", group: "save" },
+  { key: "scratch", label: "Save to Scratch", hint: "Capture a new note immediately", group: "save" },
+  { key: "document", label: "Create a document", hint: "A native Matrx document", group: "save" },
+  { key: "workbook", label: "Create a workbook", hint: "Selected columns and rows in Matrx Sheets", group: "save" },
+  { key: "task", label: "Create a task", hint: "Review the title and content before saving", group: "save" },
+  { key: "attach", label: "Save and attach to a task or project", hint: "Save a note, then choose where it belongs", group: "save" },
+  { key: "code", label: "Save to Code", hint: "Choose a file and language", group: "save" },
+  { key: "chat", label: "Open in a new chat", hint: "Attach this content and write your request", group: "chat" },
+  { key: "assistant", label: "Open an assistant window", hint: "Keep this page open while you work", group: "chat" },
+  { key: "tools", label: "Use with connected tools", hint: "Open an assistant and choose tools or MCPs", group: "chat" }
+];
+function createMatrxTransferActions(ports) {
+  return DESTINATIONS.flatMap(({ key, ...presentation }) => {
+    const port = ports[key];
+    if (!port) return [];
+    const supports = (snapshot, draft) => key !== "workbook" || (draft?.payload ?? snapshot.payload).kind === "rows";
+    return [{
+      id: `matrx:${key}`,
+      ...presentation,
+      prepared: true,
+      supports,
+      async run({ snapshot, draft, signal }) {
+        signal.throwIfAborted();
+        if (draft.snapshotId !== snapshot.id || draft.sourceId !== snapshot.sourceId || draft.sourceRevision !== snapshot.revision)
+          throw new Error("The prepared content does not belong to this source revision. Refresh Alchemy before continuing.");
+        if (!supports(snapshot, draft))
+          throw new Error(`${presentation.label} is unavailable for this prepared content.`);
+        const current = draft;
+        const payload = current.payload;
+        const columns = payload.kind === "rows" ? payload.columns.filter((column) => column.visible && column.exportable !== false && column.classification !== "secret" && column.classification !== "credential") : [];
+        const table = payload.kind === "rows" ? {
+          name: snapshot.label,
+          headers: columns.map((column) => column.label),
+          rows: payload.rows.map((row) => columns.map((column) => {
+            const value = readTransferCell(row, column);
+            return value == null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+          }))
+        } : void 0;
+        const content = {
+          label: snapshot.label,
+          snapshot,
+          draft: current,
+          payload,
+          markdown: serialize(current, "markdown").plainText,
+          plainText: serialize(current, "plain").plainText,
+          signal,
+          ...table ? { table } : {}
+        };
+        signal.throwIfAborted();
+        return port(content);
+      }
+    }];
+  });
+}
+
 // content-transfer/index.ts
 import {
   editDraft,
-  serialize
+  serialize as serialize2
 } from "@ai-matrx/kit/content-transfer";
 
 // mandates/keys.generated.ts
@@ -1021,6 +1082,109 @@ async function rejoinRuntimeOperation(transport, requestId, options = {}) {
   return toRunHandle(response, options);
 }
 
+// content-transfer/destination-ports.ts
+var success = (message, target) => ({ status: "success", delivered: "action", mimeTypes: [], message, ...target ? { target } : {} });
+var active = (bindings, content, expected) => {
+  content.signal.throwIfAborted();
+  const identity = bindings.getIdentity();
+  if (!identity.userId || !identity.organizationId) throw new Error("Sign in and select an organization to use Matrx destinations.");
+  if (expected && (identity.userId !== expected.userId || identity.organizationId !== expected.organizationId)) throw new Error("Your account or organization changed while this action was being prepared.");
+  return identity;
+};
+var receipt = (bindings, content, identity, target, message) => {
+  try {
+    active(bindings, content, identity);
+    return success(message, target);
+  } catch {
+    return { status: "error", code: "saved-before-context-change", retryable: false, target, message: `${target.label} was saved. Your account or organization changed before it could be opened.` };
+  }
+};
+var failed = (kind, content, result) => ({
+  status: "error",
+  code: `${kind}-save-failed`,
+  retryable: false,
+  message: result.error ?? `${kind === "document" ? "Document" : "Workbook"} could not be saved.`,
+  ...result.id ? { target: { kind, id: result.id, label: content.label, ...result.href ? { href: result.href } : {} } } : {}
+});
+function createMatrxTransferPorts(bindings) {
+  const attached = /* @__PURE__ */ new Map();
+  return {
+    notes: async (content) => {
+      const identity = active(bindings, content);
+      await bindings.openNotes(content);
+      active(bindings, content, identity);
+      return success("Notes editor opened. Choose where to save this content.");
+    },
+    scratch: async (content) => {
+      const identity = active(bindings, content);
+      const target = await bindings.saveNote(content, "Scratch");
+      return receipt(bindings, content, identity, target, "Saved to Scratch.");
+    },
+    document: async (content) => {
+      const identity = active(bindings, content);
+      const result = await bindings.saveDocument(content);
+      if (!result.ok || !result.id || !result.href) return failed("document", content, result);
+      return receipt(bindings, content, identity, { kind: "document", id: result.id, label: content.label, href: result.href }, "Saved as a Matrx document.");
+    },
+    workbook: async (content) => {
+      const identity = active(bindings, content);
+      if (!content.table) throw new Error("A workbook requires tabular content.");
+      const result = await bindings.saveWorkbook(content);
+      if (!result.ok || !result.id || !result.href) return failed("workbook", content, result);
+      return receipt(bindings, content, identity, { kind: "workbook", id: result.id, label: content.label, href: result.href }, "Saved as a Matrx workbook.");
+    },
+    task: async (content) => {
+      const identity = active(bindings, content);
+      await bindings.openTask(content);
+      active(bindings, content, identity);
+      return success("Task editor opened with this content. Review and save the task.");
+    },
+    attach: async (content) => {
+      const identity = active(bindings, content);
+      const key = JSON.stringify([identity.userId, identity.organizationId, content.draft.sourceId, content.draft.sourceRevision, content.draft.revision, content.label, content.markdown]);
+      let pending = attached.get(key);
+      if (!pending) {
+        pending = bindings.saveNote(content, "Alchemy");
+        attached.set(key, pending);
+        pending.catch(() => attached.delete(key));
+      }
+      const target = await pending;
+      try {
+        active(bindings, content, identity);
+        await bindings.openAttachment(target);
+        active(bindings, content, identity);
+        return success("Note saved. Choose a task or project in the attachment window to finish attaching it.", target);
+      } catch {
+        return { status: "error", code: "note-saved-chooser-not-opened", retryable: false, target, message: "Note saved, but the attachment window did not open. Reopen this note to attach it; do not save another copy." };
+      }
+    },
+    code: async (content) => {
+      const identity = active(bindings, content);
+      await bindings.openCode(content);
+      active(bindings, content, identity);
+      return success("Code editor opened. Choose the file name and language before saving.");
+    },
+    chat: async (content) => {
+      const identity = active(bindings, content);
+      await bindings.openChat(content, "chat", identity);
+      active(bindings, content, identity);
+      return success("New chat opened with this content attached. Write your request when ready.");
+    },
+    assistant: async (content) => {
+      const identity = active(bindings, content);
+      await bindings.openChat(content, "assistant", identity);
+      active(bindings, content, identity);
+      return success("Assistant window opened with this content attached. Nothing has been sent yet.");
+    },
+    tools: async (content) => {
+      const identity = active(bindings, content);
+      await bindings.openChat(content, "tools", identity);
+      active(bindings, content, identity);
+      return success("Assistant opened with this content attached. Choose Tools in Chat Options to use your connected MCPs.");
+    }
+  };
+}
+
 // content-transfer/index.ts
 var SupersededRunError = class extends Error {
   constructor() {
@@ -1076,7 +1240,7 @@ function responseMessageId(metadata) {
 }
 function draftFromAssistant(source, text, identity) {
   const edited = editDraft(source, { kind: "markdown", text });
-  const reducedBy = serialize(source, "markdown").plainText.length - text.length;
+  const reducedBy = serialize2(source, "markdown").plainText.length - text.length;
   return deepFreeze({
     ...edited,
     manuallyEdited: source.manuallyEdited,
@@ -1293,7 +1457,7 @@ function createMatrxContentTransferAdapter(options) {
           executionId: null,
           status: "starting"
         });
-        const preparedContent = serialize(input.draft, "markdown").plainText;
+        const preparedContent = serialize2(input.draft, "markdown").plainText;
         let identity = null;
         try {
           const handle = await startMandateRun(
@@ -1407,6 +1571,8 @@ function createMatrxContentTransferAdapter(options) {
   };
 }
 export {
-  createMatrxContentTransferAdapter
+  createMatrxContentTransferAdapter,
+  createMatrxTransferActions,
+  createMatrxTransferPorts
 };
 //# sourceMappingURL=index.js.map