@tangle-network/agent-app 0.45.58 → 0.45.60

package/dist/assistant/index.js

@@ -2,7 +2,7 @@ import {
   ChatComposer,
   ChatEmptyState,
   ChatMessages
-} from "../chunk-UPXDBHEE.js";
+} from "../chunk-FOXGPGXF.js";
 import "../chunk-FBVLEGEG.js";
 import "../chunk-ENLRJYVW.js";
 import "../chunk-GEYACSFW.js";

package/dist/chat-routes/attachment-store.d.ts

@@ -46,39 +46,82 @@ export type AttachmentReadResult = {
  * turn-level exception.
  */
 export type ReadAttachmentFn = (scopeId: string, path: string) => Promise<AttachmentReadResult>;
-/** Outcome of persisting one attachment. Mirrors `AttachmentReadResult`'s
- *  `ok`/`reason` shape and `upload.ts`'s `{ ok }` convention. */
+/** The ownership identity for one attempted write. The upload and promotion
+ * routes create a unique path for each attempt, and the product adapter stores
+ * this id with it. */
+export interface AttachmentWriteOwnership {
+    readonly id: string;
+    readonly path: string;
+}
+/** Public-safe outcome for a storage outage. Backend details belong in logs. */
+export declare const ATTACHMENT_STORAGE_FAILURE_MESSAGE = "Attachment storage is temporarily unavailable. Please try again.";
+/** Stable client error code when compensating cleanup did not complete. */
+export declare const ATTACHMENT_ROLLBACK_FAILURE_CODE = "rollback_failed";
+/** Public-safe outcome when compensating cleanup did not complete. */
+export declare const ATTACHMENT_ROLLBACK_FAILURE_MESSAGE = "Attachment cleanup failed. Please try again.";
+/** Add a path-safe ownership id to a logical path and return an immutable store key. */
+export declare function immutableAttachmentPath(logicalPath: string, ownershipId: string): string;
+/** Compensation for one attachment write. The adapter MUST compare the stored
+ * ownership id before deleting, so an older rollback cannot delete a newer
+ * overwrite. */
+export interface AttachmentWriteReceipt {
+    rollback(): void | Promise<void>;
+    ownership: AttachmentWriteOwnership;
+}
+/** Clean up a write whose function threw after the store may have committed.
+ * The adapter must delete only the supplied ownership, never the logical path
+ * unconditionally. */
+export type AbortAttachmentWriteFn = (scopeId: string, ownership: AttachmentWriteOwnership) => void | Promise<void>;
+/**
+ * The stable writer result from the original attachment-store contract.
+ * Existing products may return this shape and keep using the legacy writer
+ * lane. New products should use {@link AtomicAttachmentWriteResult}.
+ */
 export type AttachmentWriteResult = {
     ok: true;
 } | {
     ok: false;
     reason: string;
 };
-/**
- * Persist `content` for `scopeId` at `path`. `content` is either raw `bytes`
- * or a base64 `string` — a string argument is ALWAYS base64 (never utf8), so
- * a store that speaks base64 (gtm's vault) writes it verbatim and one that
- * speaks bytes decodes once. Like the reader, failures resolve to
- * `{ ok: false, reason }` rather than throwing.
- *
- * `opts` mirrors the vault frontmatter gtm's `writeAttachmentVaultFile`
- * persists alongside the body (promote-file-parts.ts:181-190), so a product
- * reimplementing that vault writer through this seam can reproduce it
- * exactly:
- * - `mediaType` — the resolved MIME type; gtm's frontmatter key `mime`.
- * - `name` — the sanitized (store-path-safe) display filename; gtm passes
- *   this only to shape its oversize message, not into frontmatter.
- * - `originalName` — the filename as the harness/browser reported it, BEFORE
- *   sanitization (`raw.filename ?? filename` — falls back to the sanitized
- *   name when the source carried none); gtm's frontmatter key `originalName`.
- *   This is the one field with no other recovery path once sanitization has
- *   run, so it must ride the write, not be re-derived after the fact.
- * - `size` — the authoritative decoded byte length being written; gtm's
- *   frontmatter key `size`.
- */
-export type WriteAttachmentFn = (scopeId: string, path: string, content: Uint8Array | string, opts: {
+/** Options from the stable attachment-store contract. */
+export interface AttachmentWriteOptions {
     mediaType?: string;
     name?: string;
     originalName?: string;
     size?: number;
-}) => Promise<AttachmentWriteResult>;
+}
+/**
+ * The stable writer port. It is intentionally unchanged so products released
+ * before the ownership receipt contract continue to compile.
+ *
+ * The legacy lane does not promise batch rollback. Use
+ * {@link createAtomicAttachmentWriter} for ownership-safe writes.
+ */
+export type WriteAttachmentFn = (scopeId: string, path: string, content: Uint8Array | string, opts: AttachmentWriteOptions) => Promise<AttachmentWriteResult>;
+/** Options for an ownership-safe writer. */
+export interface AtomicAttachmentWriteOptions extends AttachmentWriteOptions {
+    ownership: AttachmentWriteOwnership;
+}
+/** Result for an ownership-safe writer. A receipt is required on both paths. */
+export type AtomicAttachmentWriteResult = {
+    ok: true;
+    receipt: AttachmentWriteReceipt;
+} | {
+    ok: false;
+    reason: string;
+    receipt: AttachmentWriteReceipt;
+};
+/** Ownership-safe writer port used by the atomic upload and promotion lanes. */
+export type AtomicWriteAttachmentFn = (scopeId: string, path: string, content: Uint8Array | string, opts: AtomicAttachmentWriteOptions) => Promise<AtomicAttachmentWriteResult>;
+/** A complete ownership-safe attachment store adapter. */
+export interface AtomicAttachmentWriter {
+    write: AtomicWriteAttachmentFn;
+    abort: AbortAttachmentWriteFn;
+}
+/**
+ * Build the explicit atomic adapter used by new routes.
+ *
+ * Keeping the write and abort functions together prevents a caller from
+ * enabling ownership paths while forgetting the ambiguous-write cleanup.
+ */
+export declare function createAtomicAttachmentWriter(input: AtomicAttachmentWriter): AtomicAttachmentWriter;

package/dist/chat-routes/attachment-upload.d.ts

@@ -1,14 +1,16 @@
 /**
  * `createAttachmentUploadRoute` — the fleet-primitive durable-store upload
- * route: a two-phase atomic batch (every file is validated before any file is
- * written — a batch never partially lands), a content-sniffed type gate
+ * route: a two-phase batch (every file is validated before any file is written),
+ * with a stable legacy lane and an ownership-safe receipt lane for new callers,
+ * a content-sniffed type gate
  * (`checkAttachmentType` over `sniffBinary`'s magic-byte read, not the
  * extension or the browser-reported MIME), binary/text caps with optional
  * per-sniffed-mime overrides, an aggregate byte cap, and sanitized filenames.
  * Storage is fully seamed through the injected
- * `WriteAttachmentFn` (`./attachment-store`) — no default store, the product
- * owns where bytes actually live (vault, object store, …) — and auth/rate
- * limiting is entirely the injected `authorize` seam's job: this factory
+ * `WriteAttachmentFn` or `AtomicAttachmentWriter` (`./attachment-store`) — no
+ * default store, the product owns where bytes actually live (vault, object
+ * store, …), and auth/rate limiting is entirely the injected `authorize`
+ * seam's job: this factory
  * never invents a 401 or 429 response, it only returns `auth.response`
  * verbatim on failure.
  *
@@ -26,14 +28,9 @@
  * comment for the up-to-date framing between the two.
  */
 import type { ChatAttachmentKind } from './wire';
-import type { WriteAttachmentFn } from './attachment-store';
+import { type AtomicAttachmentWriter, type WriteAttachmentFn } from './attachment-store';
 import { type AttachmentPathCheck } from './resolve-attachments';
-/** Outcome of the injected `authorize` seam: auth + rate limiting +
- *  scope resolution, all in one place so a 429 rides `{ok:false, response}`
- *  exactly like a 401 does — this factory has no rate-limit opinion of its
- *  own. `writeAttachment` lets a single request override the option-level
- *  store (e.g. routing per-tenant), defaulting to `options.writeAttachment`
- *  when absent. */
+/** Stable authorization result for the original writer contract. */
 export type AttachmentUploadAuthorization = {
     ok: true;
     scopeId: string;
@@ -42,48 +39,72 @@ export type AttachmentUploadAuthorization = {
     ok: false;
     response: Response;
 };
-/** Define options to authorize, write, and limit attachment uploads in a route */
-export interface CreateAttachmentUploadRouteOptions {
-    /** Authenticate the caller, rate-limit, and resolve the store scope
-     *  (workspace/tenant id) — never a query param. */
-    authorize(args: {
-        request: Request;
-    }): Promise<AttachmentUploadAuthorization>;
-    /** Default store writer. `authorize` may override it per-request. */
-    writeAttachment: WriteAttachmentFn;
+/** Authorization result for an ownership-safe attachment writer. */
+export type AtomicAttachmentUploadAuthorization = {
+    ok: true;
+    scopeId: string;
+    attachmentWriter?: AtomicAttachmentWriter;
+} | {
+    ok: false;
+    response: Response;
+};
+/** The logger receives only sanitized backend details. The client receives the
+ * opaque message below, regardless of the store's failure text. */
+export type AttachmentUploadLogger = Pick<Console, 'error'>;
+interface AttachmentUploadRouteCommonOptions {
     /** Overridable caps. Defaults come from `./attachment-validation`. */
     limits?: {
         /** Most files one request may carry. Default {@link ATTACHMENT_MAX_COUNT}. */
         maxCount?: number;
         /** Ceiling on a binary file's raw size. Default {@link MAX_BINARY_ATTACHMENT_BYTES}. */
         maxBinaryBytes?: number;
-        /** Optional binary-file ceilings keyed by the content-sniffed mime. A
-         *  missing mime falls back to `maxBinaryBytes`; text files continue to use
-         *  `maxTextBytes`. */
+        /** Optional binary-file ceilings keyed by the content-sniffed mime. */
         maxBytesBySniffedMime?: ReadonlyMap<string, number>;
         /** Ceiling on a text file's raw size. Default {@link MAX_TEXT_ATTACHMENT_BYTES}. */
         maxTextBytes?: number;
-        /** Aggregate raw-byte ceiling across the batch. Default {@link MAX_ATTACHMENT_TOTAL_BYTES}. */
+        /** Aggregate raw-byte ceiling. Default {@link MAX_ATTACHMENT_TOTAL_BYTES}. */
         maxTotalBytes?: number;
     };
     /** Attachment kinds this route accepts. Default `['image', 'file']`. */
     allowedKinds?: ChatAttachmentKind[];
-    /** Sniffed-mime allowlist fed to `checkAttachmentType`. Default
-     *  {@link ALLOWED_ATTACHMENT_SNIFFED_MIMES}. Narrow it to accept less than
-     *  the default (`new Set(['application/pdf'])`), or widen it to accept a
-     *  format the default refuses — macro-enabled Office packages are the
-     *  shipped case:
-     *  `new Set([...ALLOWED_ATTACHMENT_SNIFFED_MIMES, ...MACRO_ENABLED_OOXML_SNIFFED_MIMES])`. */
+    /** Sniffed-mime allowlist fed to `checkAttachmentType`. */
     allowedSniffedMimes?: ReadonlySet<string>;
-    /** Sanitized-name → store path. Default identity (the sanitized name IS
-     *  the path); gtm passes `vaultFolderForFileName`, a tenant product a
-     *  scope prefix. */
+    /** Sanitized-name → logical store path. */
     pathFor?: (name: string) => string;
     /** Store-path validator. Default {@link defaultValidateAttachmentPath}. */
     validatePath?: (path: string) => AttachmentPathCheck;
-    /** Last-resort media-type hook for text content the sniffer can't type.
-     *  Default {@link sniffMimeFromName}. */
+    /** Last-resort media-type hook for text content the sniffer cannot type. */
     sniffMime?: (name: string) => string;
+    /** Unique id source for atomic ownership keys. */
+    createWriteId?: () => string;
+    /** Server-side error sink. Backend text is sanitized before it is logged. */
+    logger?: AttachmentUploadLogger;
+}
+/** Stable route options for products using the original writer contract. */
+export interface CreateLegacyAttachmentUploadRouteOptions extends AttachmentUploadRouteCommonOptions {
+    /** Authenticate the caller, rate-limit, and resolve the store scope
+     *  (workspace/tenant id) — never a query param. */
+    authorize(args: {
+        request: Request;
+    }): Promise<AttachmentUploadAuthorization>;
+    /** Stable writer. `authorize` may override it per-request. */
+    writeAttachment: WriteAttachmentFn;
+}
+/**
+ * The original public route-options interface remains available for consumers
+ * that extend it. Ownership-safe callers use the atomic interface below.
+ */
+export interface CreateAttachmentUploadRouteOptions extends CreateLegacyAttachmentUploadRouteOptions {
+}
+/** Ownership-safe route options for new products. */
+export interface CreateAtomicAttachmentUploadRouteOptions extends AttachmentUploadRouteCommonOptions {
+    /** Authenticate the caller, rate-limit, and resolve the store scope. */
+    authorize(args: {
+        request: Request;
+    }): Promise<AtomicAttachmentUploadAuthorization>;
+    /** Complete writer + ambiguous-write cleanup adapter. */
+    attachmentWriter: AtomicAttachmentWriter;
 }
-/** Resolve an attachment upload route handler with customizable limits and validation options */
-export declare function createAttachmentUploadRoute(options: CreateAttachmentUploadRouteOptions): (request: Request) => Promise<Response>;
+/** Resolve an attachment upload route handler with customizable limits and validation options. */
+export declare function createAttachmentUploadRoute(options: CreateAttachmentUploadRouteOptions | CreateAtomicAttachmentUploadRouteOptions): (request: Request) => Promise<Response>;
+export {};

package/dist/chat-routes/attachment-write-safety.d.ts

@@ -0,0 +1,11 @@
+import type { AtomicAttachmentWriteResult, AttachmentWriteOwnership, AttachmentWriteResult } from './attachment-store';
+/** Read an injected writer result without allowing hostile getters to escape. */
+export declare function inspectLegacyAttachmentWriteResult(value: unknown): AttachmentWriteResult | undefined;
+/**
+ * Read an ownership-aware writer result with strict runtime checks.
+ *
+ * The public types protect TypeScript callers only. The product adapter is an
+ * injection boundary, so a proxy, malformed value, or truthy non-boolean must
+ * fail closed before the route invokes cleanup or publishes a path.
+ */
+export declare function inspectAtomicAttachmentWriteResult(value: unknown, ownership: AttachmentWriteOwnership): AtomicAttachmentWriteResult | undefined;