@ai4b-team/fsaos-gateway-sdk 3.26.2 → 3.27.0

package/dist/index.d.cts

@@ -2464,6 +2464,56 @@ declare function useArrangement(paramsOrPath: string | {
     fetchStatus: _tanstack_react_query.FetchStatus;
     promise: Promise<any>;
 };
+/** The honest life of a tool-produced file, as the system actually reports it. */
+type MintedAssetState = 'idle' | 'pending' | 'materializing' | 'ready' | 'failed';
+interface MintedAsset {
+    state: MintedAssetState;
+    /** Set when `asset.materialized` identifies the durable item. */
+    itemId?: string;
+    itemPath?: string;
+    displayName?: string;
+    /** The tool's transient provider URL. Correct immediately; may expire. */
+    fallbackUrl?: string;
+    error?: string;
+}
+/**
+ * Follow a tool result's file from "the tool returned" to "safe to render".
+ *
+ * WHY THIS EXISTS. A media tool returns a provider URL AND mints a durable FSAOS
+ * asset, but the mint completes *after* the reply — deliberately, because waiting
+ * in-reply just delays the user's answer. So at card-render time the asset does
+ * not exist yet. Cards that looked for it found nothing and showed a bare link;
+ * cards that showed the provider URL displayed something that later expires.
+ *
+ * The producer announces completion instead of the consumer asking: `kernel_signal`
+ * emits `asset.materialized` when an item lands, carrying `origin` (the message
+ * path that produced it) and `has_bytes`. Byte fetch is a separate async step, so
+ * `has_bytes:false` is normal on arrival — `content.written` follows. Those two
+ * events are what separate "saving" from "ready", and why this hook never claims
+ * a file is displayable before its bytes exist.
+ *
+ * Correlation is by ORIGIN (the producing message), not by path or name, so a
+ * rename or a move cannot break the link.
+ *
+ * NOTE ON CONNECTIONS: subscribeToEvents is a local listener — it does not open a
+ * socket by itself and silently receives nothing unless a scope/path subscription
+ * exists. That failure is invisible (a skeleton that never resolves), so this hook
+ * holds its own scope subscription for as long as it is waiting. An indexed,
+ * account-scoped asset lookup closes the startup/history gap when the
+ * materialization event arrived before this consumer subscribed.
+ */
+declare function useMintedAsset(params: {
+    /** `fsaos_origin_message_path` — the message that produced the file. */
+    origin?: string | null;
+    /** The tool's own URL, shown while the durable asset is still landing. */
+    fallbackUrl?: string | null;
+    /** The producer's mint error, if it reported one. */
+    mintError?: string | null;
+    /** Scope to subscribe under — required for the socket to be open. */
+    scopeId?: string | null;
+    /** Account scope path for indexed historical recovery. */
+    scopePath?: string | null;
+}): MintedAsset;
 
 /**
  * @fsaos/gateway — Schema Interpretation Utilities
@@ -2971,4 +3021,4 @@ declare function fetchTimelineHistory(channelPath: string, options?: Pick<Timeli
  */
 declare function useTimelineHistory(channelPath: string | null | undefined, options?: TimelineHistoryOptions): UseTimelineHistoryReturn;
 
-export { type AccountInfo, type ArtifactDeltaEvent, type ArtifactDoneEvent, type ArtifactEvent, type ArtifactOpenedEvent, type ArtifactState, type ArtifactStatus, type ArtifactStreamState, type ArtifactSurfaceType, type CancelQueuedTurnOptions, type CancelQueuedTurnResponse, type CancelQueuedTurnState, type CancelTurnOptions, type CancelTurnResponse, type CancelTurnState, type Channel, type ChannelCard, type ChannelMessage, type ChannelMessagesOptions, type ChannelMessagesPage, type ChannelMessagesResponse, type ChannelsOptions, type ComponentOpener, ComponentRenderer, type ConnectionState, type CreateParams, type DeleteParams, EnforcementDeniedError, type EnforcementPayload, type FieldDescriptor, type FileRef, FormSubmissionError, type FormSubmissionReceipt, type FsaosRuntime, type GatewayParams, GatewayRequestError, type GatewayResponse, type InfiniteChannelMessagesOptions, type InitializeFsaosOptions, type InteractionReceipt, InteractionTrackingError, type ItemVersionsOptions, type ItemVersionsResult, type ItemsFilter, KernelProvider, type LinkParams, type MountRef, type MoveParams, type Notification, type NotificationsOptions, type OpenEnvelope, type OpenOptions, type PathSubscriptionState, type PrincipalData, type PublicSourceConfig, type ResolveItemsResponse, type ResolveParams, type ResolveResponse, type ResolveResultItem, type ResolvedItem, type SessionEntry, type SourceCaptureAdapter, type SourceIdentityStorage, type StartTrackingOptions, type SteerTurnOptions, type SteerTurnResponse, type SteerTurnState, type SubmitFormOptions, type TimelineEvent, type TimelineHistoryEvent, type TimelineHistoryOptions, type TrackEventOptions, type TurnQueueEntry, type TurnQueueEntryState, type TypeDefinition, type TypeHelpers, type TypeSchema, type UnreadCountsOptions, type UpdateParams, type UpdatePrincipalParams, type UploadItem, type UploadOptions, type UploadResult, type UseArtifactStreamReturn, type UseFileUploadReturn, type UseTimelineHistoryReturn, type VFSEdge, type VFSItem, type WorkCorrelation, auth, awaitAnchorReady, awaitScopeReady, callTool, cancelQueuedTurn, cancelTurn, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, electHomeAnchor, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchChannelMessagesWithCards, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchResolvedItems, fetchTimelineHistory, fetchTurnQueueEntries, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAnchor, getAnchorRef, getAnchorVersion, getAssetUrl, getDefaultSort, getHomeAnchor, getMountVersion, getMounts, getPathSubscriptionState, getQueryClient, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, initializeFsaos, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isAnchorReady, isScopeReady, listChildren, mount$1 as mount, mountRealtimeScope, normalizeItem, onConnectionStateChange, pathSubscriptionMatches, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, resubscribePath, setAnchor, setCachedToken, setQueryClient, setScope, setupRequireShim, signal, startTracking, steerTurn, submitForm, subscribeAnchor, subscribeArtifactStream, subscribeMounts, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, trackAction, trackEvent, trackPageView, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAgentTimeline, useAllChannels, useArrangement, useArtifactStream, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMounts, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useResolvedItems, useScope, useScopeReady, useSearch, useTheme, useTimelineHistory, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, useUpdatePrincipal, vfsKeys, waitForPathReady };
+export { type AccountInfo, type ArtifactDeltaEvent, type ArtifactDoneEvent, type ArtifactEvent, type ArtifactOpenedEvent, type ArtifactState, type ArtifactStatus, type ArtifactStreamState, type ArtifactSurfaceType, type CancelQueuedTurnOptions, type CancelQueuedTurnResponse, type CancelQueuedTurnState, type CancelTurnOptions, type CancelTurnResponse, type CancelTurnState, type Channel, type ChannelCard, type ChannelMessage, type ChannelMessagesOptions, type ChannelMessagesPage, type ChannelMessagesResponse, type ChannelsOptions, type ComponentOpener, ComponentRenderer, type ConnectionState, type CreateParams, type DeleteParams, EnforcementDeniedError, type EnforcementPayload, type FieldDescriptor, type FileRef, FormSubmissionError, type FormSubmissionReceipt, type FsaosRuntime, type GatewayParams, GatewayRequestError, type GatewayResponse, type InfiniteChannelMessagesOptions, type InitializeFsaosOptions, type InteractionReceipt, InteractionTrackingError, type ItemVersionsOptions, type ItemVersionsResult, type ItemsFilter, KernelProvider, type LinkParams, type MintedAsset, type MintedAssetState, type MountRef, type MoveParams, type Notification, type NotificationsOptions, type OpenEnvelope, type OpenOptions, type PathSubscriptionState, type PrincipalData, type PublicSourceConfig, type ResolveItemsResponse, type ResolveParams, type ResolveResponse, type ResolveResultItem, type ResolvedItem, type SessionEntry, type SourceCaptureAdapter, type SourceIdentityStorage, type StartTrackingOptions, type SteerTurnOptions, type SteerTurnResponse, type SteerTurnState, type SubmitFormOptions, type TimelineEvent, type TimelineHistoryEvent, type TimelineHistoryOptions, type TrackEventOptions, type TurnQueueEntry, type TurnQueueEntryState, type TypeDefinition, type TypeHelpers, type TypeSchema, type UnreadCountsOptions, type UpdateParams, type UpdatePrincipalParams, type UploadItem, type UploadOptions, type UploadResult, type UseArtifactStreamReturn, type UseFileUploadReturn, type UseTimelineHistoryReturn, type VFSEdge, type VFSItem, type WorkCorrelation, auth, awaitAnchorReady, awaitScopeReady, callTool, cancelQueuedTurn, cancelTurn, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, electHomeAnchor, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchChannelMessagesWithCards, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchResolvedItems, fetchTimelineHistory, fetchTurnQueueEntries, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAnchor, getAnchorRef, getAnchorVersion, getAssetUrl, getDefaultSort, getHomeAnchor, getMountVersion, getMounts, getPathSubscriptionState, getQueryClient, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, initializeFsaos, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isAnchorReady, isScopeReady, listChildren, mount$1 as mount, mountRealtimeScope, normalizeItem, onConnectionStateChange, pathSubscriptionMatches, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, resubscribePath, setAnchor, setCachedToken, setQueryClient, setScope, setupRequireShim, signal, startTracking, steerTurn, submitForm, subscribeAnchor, subscribeArtifactStream, subscribeMounts, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, trackAction, trackEvent, trackPageView, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAgentTimeline, useAllChannels, useArrangement, useArtifactStream, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMintedAsset, useMounts, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useResolvedItems, useScope, useScopeReady, useSearch, useTheme, useTimelineHistory, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, useUpdatePrincipal, vfsKeys, waitForPathReady };

package/dist/index.d.ts

@@ -2464,6 +2464,56 @@ declare function useArrangement(paramsOrPath: string | {
     fetchStatus: _tanstack_react_query.FetchStatus;
     promise: Promise<any>;
 };
+/** The honest life of a tool-produced file, as the system actually reports it. */
+type MintedAssetState = 'idle' | 'pending' | 'materializing' | 'ready' | 'failed';
+interface MintedAsset {
+    state: MintedAssetState;
+    /** Set when `asset.materialized` identifies the durable item. */
+    itemId?: string;
+    itemPath?: string;
+    displayName?: string;
+    /** The tool's transient provider URL. Correct immediately; may expire. */
+    fallbackUrl?: string;
+    error?: string;
+}
+/**
+ * Follow a tool result's file from "the tool returned" to "safe to render".
+ *
+ * WHY THIS EXISTS. A media tool returns a provider URL AND mints a durable FSAOS
+ * asset, but the mint completes *after* the reply — deliberately, because waiting
+ * in-reply just delays the user's answer. So at card-render time the asset does
+ * not exist yet. Cards that looked for it found nothing and showed a bare link;
+ * cards that showed the provider URL displayed something that later expires.
+ *
+ * The producer announces completion instead of the consumer asking: `kernel_signal`
+ * emits `asset.materialized` when an item lands, carrying `origin` (the message
+ * path that produced it) and `has_bytes`. Byte fetch is a separate async step, so
+ * `has_bytes:false` is normal on arrival — `content.written` follows. Those two
+ * events are what separate "saving" from "ready", and why this hook never claims
+ * a file is displayable before its bytes exist.
+ *
+ * Correlation is by ORIGIN (the producing message), not by path or name, so a
+ * rename or a move cannot break the link.
+ *
+ * NOTE ON CONNECTIONS: subscribeToEvents is a local listener — it does not open a
+ * socket by itself and silently receives nothing unless a scope/path subscription
+ * exists. That failure is invisible (a skeleton that never resolves), so this hook
+ * holds its own scope subscription for as long as it is waiting. An indexed,
+ * account-scoped asset lookup closes the startup/history gap when the
+ * materialization event arrived before this consumer subscribed.
+ */
+declare function useMintedAsset(params: {
+    /** `fsaos_origin_message_path` — the message that produced the file. */
+    origin?: string | null;
+    /** The tool's own URL, shown while the durable asset is still landing. */
+    fallbackUrl?: string | null;
+    /** The producer's mint error, if it reported one. */
+    mintError?: string | null;
+    /** Scope to subscribe under — required for the socket to be open. */
+    scopeId?: string | null;
+    /** Account scope path for indexed historical recovery. */
+    scopePath?: string | null;
+}): MintedAsset;
 
 /**
  * @fsaos/gateway — Schema Interpretation Utilities
@@ -2971,4 +3021,4 @@ declare function fetchTimelineHistory(channelPath: string, options?: Pick<Timeli
  */
 declare function useTimelineHistory(channelPath: string | null | undefined, options?: TimelineHistoryOptions): UseTimelineHistoryReturn;
 
-export { type AccountInfo, type ArtifactDeltaEvent, type ArtifactDoneEvent, type ArtifactEvent, type ArtifactOpenedEvent, type ArtifactState, type ArtifactStatus, type ArtifactStreamState, type ArtifactSurfaceType, type CancelQueuedTurnOptions, type CancelQueuedTurnResponse, type CancelQueuedTurnState, type CancelTurnOptions, type CancelTurnResponse, type CancelTurnState, type Channel, type ChannelCard, type ChannelMessage, type ChannelMessagesOptions, type ChannelMessagesPage, type ChannelMessagesResponse, type ChannelsOptions, type ComponentOpener, ComponentRenderer, type ConnectionState, type CreateParams, type DeleteParams, EnforcementDeniedError, type EnforcementPayload, type FieldDescriptor, type FileRef, FormSubmissionError, type FormSubmissionReceipt, type FsaosRuntime, type GatewayParams, GatewayRequestError, type GatewayResponse, type InfiniteChannelMessagesOptions, type InitializeFsaosOptions, type InteractionReceipt, InteractionTrackingError, type ItemVersionsOptions, type ItemVersionsResult, type ItemsFilter, KernelProvider, type LinkParams, type MountRef, type MoveParams, type Notification, type NotificationsOptions, type OpenEnvelope, type OpenOptions, type PathSubscriptionState, type PrincipalData, type PublicSourceConfig, type ResolveItemsResponse, type ResolveParams, type ResolveResponse, type ResolveResultItem, type ResolvedItem, type SessionEntry, type SourceCaptureAdapter, type SourceIdentityStorage, type StartTrackingOptions, type SteerTurnOptions, type SteerTurnResponse, type SteerTurnState, type SubmitFormOptions, type TimelineEvent, type TimelineHistoryEvent, type TimelineHistoryOptions, type TrackEventOptions, type TurnQueueEntry, type TurnQueueEntryState, type TypeDefinition, type TypeHelpers, type TypeSchema, type UnreadCountsOptions, type UpdateParams, type UpdatePrincipalParams, type UploadItem, type UploadOptions, type UploadResult, type UseArtifactStreamReturn, type UseFileUploadReturn, type UseTimelineHistoryReturn, type VFSEdge, type VFSItem, type WorkCorrelation, auth, awaitAnchorReady, awaitScopeReady, callTool, cancelQueuedTurn, cancelTurn, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, electHomeAnchor, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchChannelMessagesWithCards, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchResolvedItems, fetchTimelineHistory, fetchTurnQueueEntries, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAnchor, getAnchorRef, getAnchorVersion, getAssetUrl, getDefaultSort, getHomeAnchor, getMountVersion, getMounts, getPathSubscriptionState, getQueryClient, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, initializeFsaos, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isAnchorReady, isScopeReady, listChildren, mount$1 as mount, mountRealtimeScope, normalizeItem, onConnectionStateChange, pathSubscriptionMatches, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, resubscribePath, setAnchor, setCachedToken, setQueryClient, setScope, setupRequireShim, signal, startTracking, steerTurn, submitForm, subscribeAnchor, subscribeArtifactStream, subscribeMounts, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, trackAction, trackEvent, trackPageView, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAgentTimeline, useAllChannels, useArrangement, useArtifactStream, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMounts, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useResolvedItems, useScope, useScopeReady, useSearch, useTheme, useTimelineHistory, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, useUpdatePrincipal, vfsKeys, waitForPathReady };
+export { type AccountInfo, type ArtifactDeltaEvent, type ArtifactDoneEvent, type ArtifactEvent, type ArtifactOpenedEvent, type ArtifactState, type ArtifactStatus, type ArtifactStreamState, type ArtifactSurfaceType, type CancelQueuedTurnOptions, type CancelQueuedTurnResponse, type CancelQueuedTurnState, type CancelTurnOptions, type CancelTurnResponse, type CancelTurnState, type Channel, type ChannelCard, type ChannelMessage, type ChannelMessagesOptions, type ChannelMessagesPage, type ChannelMessagesResponse, type ChannelsOptions, type ComponentOpener, ComponentRenderer, type ConnectionState, type CreateParams, type DeleteParams, EnforcementDeniedError, type EnforcementPayload, type FieldDescriptor, type FileRef, FormSubmissionError, type FormSubmissionReceipt, type FsaosRuntime, type GatewayParams, GatewayRequestError, type GatewayResponse, type InfiniteChannelMessagesOptions, type InitializeFsaosOptions, type InteractionReceipt, InteractionTrackingError, type ItemVersionsOptions, type ItemVersionsResult, type ItemsFilter, KernelProvider, type LinkParams, type MintedAsset, type MintedAssetState, type MountRef, type MoveParams, type Notification, type NotificationsOptions, type OpenEnvelope, type OpenOptions, type PathSubscriptionState, type PrincipalData, type PublicSourceConfig, type ResolveItemsResponse, type ResolveParams, type ResolveResponse, type ResolveResultItem, type ResolvedItem, type SessionEntry, type SourceCaptureAdapter, type SourceIdentityStorage, type StartTrackingOptions, type SteerTurnOptions, type SteerTurnResponse, type SteerTurnState, type SubmitFormOptions, type TimelineEvent, type TimelineHistoryEvent, type TimelineHistoryOptions, type TrackEventOptions, type TurnQueueEntry, type TurnQueueEntryState, type TypeDefinition, type TypeHelpers, type TypeSchema, type UnreadCountsOptions, type UpdateParams, type UpdatePrincipalParams, type UploadItem, type UploadOptions, type UploadResult, type UseArtifactStreamReturn, type UseFileUploadReturn, type UseTimelineHistoryReturn, type VFSEdge, type VFSItem, type WorkCorrelation, auth, awaitAnchorReady, awaitScopeReady, callTool, cancelQueuedTurn, cancelTurn, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, electHomeAnchor, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchChannelMessagesWithCards, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchResolvedItems, fetchTimelineHistory, fetchTurnQueueEntries, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAnchor, getAnchorRef, getAnchorVersion, getAssetUrl, getDefaultSort, getHomeAnchor, getMountVersion, getMounts, getPathSubscriptionState, getQueryClient, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, initializeFsaos, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isAnchorReady, isScopeReady, listChildren, mount$1 as mount, mountRealtimeScope, normalizeItem, onConnectionStateChange, pathSubscriptionMatches, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, resubscribePath, setAnchor, setCachedToken, setQueryClient, setScope, setupRequireShim, signal, startTracking, steerTurn, submitForm, subscribeAnchor, subscribeArtifactStream, subscribeMounts, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, trackAction, trackEvent, trackPageView, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAgentTimeline, useAllChannels, useArrangement, useArtifactStream, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMintedAsset, useMounts, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useResolvedItems, useScope, useScopeReady, useSearch, useTheme, useTimelineHistory, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, useUpdatePrincipal, vfsKeys, waitForPathReady };

package/dist/index.js

@@ -1,7 +1,7 @@
 import { createClient } from '@supabase/supabase-js';
 import { QueryClient, QueryClientProvider, useQuery, useInfiniteQuery, useQueryClient, useMutation as useMutation$1 } from '@tanstack/react-query';
 export { QueryClientProvider } from '@tanstack/react-query';
-import React, { createElement, useMemo, useState, useEffect, useRef, useSyncExternalStore, useCallback } from 'react';
+import React, { createElement, useMemo, useState, useEffect, useRef, useSyncExternalStore, useCallback, useLayoutEffect } from 'react';
 import { createRoot } from 'react-dom/client';
 import * as ReactDOM from 'react-dom';
 import * as JsxRuntime from 'react/jsx-runtime';
@@ -148,6 +148,7 @@ __export(src_exports, {
   useLink: () => useLink,
   useList: () => useList,
   useMemberFocus: () => useMemberFocus,
+  useMintedAsset: () => useMintedAsset,
   useMounts: () => useMounts,
   useMove: () => useMove,
   useMutation: () => useMutation,
@@ -1750,7 +1751,29 @@ function pathSubscriptionMatches(subscribedPath, eventPath) {
 }
 var typedListeners = [];
 var activeScopes = /* @__PURE__ */ new Map();
+var scopeLeases = /* @__PURE__ */ new Map();
 var activePaths = /* @__PURE__ */ new Map();
+function scopeEventTypes(scopeId) {
+  const leases = scopeLeases.get(scopeId);
+  if (!leases) return [];
+  return Array.from(
+    new Set(Array.from(leases.values()).flatMap((lease) => lease.event_types))
+  ).sort();
+}
+function sameEventTypes(a, b) {
+  if (!a) return false;
+  return a.length === b.length && a.every((eventType, index) => eventType === b[index]);
+}
+function refreshScopeSubscription(scopeId) {
+  const eventTypes = scopeEventTypes(scopeId);
+  if (eventTypes.length === 0) {
+    activeScopes.delete(scopeId);
+    return null;
+  }
+  const subscription = { scope_id: scopeId, event_types: eventTypes };
+  activeScopes.set(scopeId, subscription);
+  return subscription;
+}
 var pathStates = /* @__PURE__ */ new Map();
 var pathReadyWaiters = /* @__PURE__ */ new Map();
 var connectionState = "disconnected";
@@ -2010,15 +2033,47 @@ function subscribeToEvents(eventType, callback, filter) {
   };
 }
 function subscribeToScope(scopeId, eventTypes = ["vfs_change", "ccm_change"]) {
-  log("subscribeToScope:", scopeId, eventTypes);
-  activeScopes.set(scopeId, { scope_id: scopeId, event_types: eventTypes });
-  if (ws && ws.readyState === WebSocket.OPEN) {
-    sendMessage({ type: "subscribe", scope_id: scopeId, event_types: eventTypes });
+  const leaseId = Symbol(scopeId);
+  const normalizedEventTypes = Array.from(new Set(eventTypes)).sort();
+  if (normalizedEventTypes.length === 0) return () => {
+  };
+  const leases = scopeLeases.get(scopeId) ?? /* @__PURE__ */ new Map();
+  const previousEventTypes = activeScopes.get(scopeId)?.event_types;
+  leases.set(leaseId, { event_types: normalizedEventTypes });
+  scopeLeases.set(scopeId, leases);
+  const subscription = refreshScopeSubscription(scopeId);
+  if (!subscription) return () => {
+  };
+  log("subscribeToScope:", scopeId, subscription.event_types);
+  if (ws && ws.readyState === WebSocket.OPEN && !sameEventTypes(previousEventTypes, subscription.event_types)) {
+    sendMessage({
+      type: "subscribe",
+      scope_id: scopeId,
+      event_types: subscription.event_types
+    });
   }
   ensureConnection();
+  let active = true;
   return () => {
-    activeScopes.delete(scopeId);
-    sendMessage({ type: "unsubscribe", scope_id: scopeId });
+    if (!active) return;
+    active = false;
+    const currentLeases = scopeLeases.get(scopeId);
+    if (!currentLeases?.delete(leaseId)) return;
+    const previous = activeScopes.get(scopeId)?.event_types;
+    if (currentLeases.size === 0) {
+      scopeLeases.delete(scopeId);
+      activeScopes.delete(scopeId);
+      sendMessage({ type: "unsubscribe", scope_id: scopeId });
+    } else {
+      const next = refreshScopeSubscription(scopeId);
+      if (next && ws && ws.readyState === WebSocket.OPEN && !sameEventTypes(previous, next.event_types)) {
+        sendMessage({
+          type: "subscribe",
+          scope_id: scopeId,
+          event_types: next.event_types
+        });
+      }
+    }
     maybeDisconnect();
   };
 }
@@ -2045,6 +2100,7 @@ function disconnectSSE() {
   }
   typedListeners.length = 0;
   activeScopes.clear();
+  scopeLeases.clear();
   activePaths.clear();
   pathStates.clear();
   pathReadyWaiters.clear();
@@ -4041,6 +4097,165 @@ function useArrangement(paramsOrPath) {
     applyTo
   };
 }
+function useMintedAsset(params) {
+  const { origin, fallbackUrl, mintError, scopeId, scopePath } = params;
+  const sdkGeneration = useScopeKey();
+  const session = getSessionEntry();
+  const resolvedScopeId = scopeId ?? session?.scope_id ?? null;
+  const originAccountScope = useMemo(() => {
+    if (!origin) return null;
+    const marker = "/accounts/";
+    const markerIndex = origin.indexOf(marker);
+    if (markerIndex === -1) return null;
+    const accountEnd = origin.indexOf("/", markerIndex + marker.length);
+    return accountEnd === -1 ? origin : origin.slice(0, accountEnd);
+  }, [origin]);
+  const resolvedScopePath = scopePath ?? originAccountScope ?? session?.scope_path ?? null;
+  const correlationKey = `${sdkGeneration}
+${resolvedScopeId ?? ""}
+${resolvedScopePath ?? ""}
+${origin ?? ""}`;
+  const [found, setFound] = useState(null);
+  const activeRef = useRef({
+    key: correlationKey,
+    found: null,
+    earlyContentPaths: /* @__PURE__ */ new Set()
+  });
+  const currentFound = found?.key === correlationKey ? found : null;
+  useLayoutEffect(() => {
+    activeRef.current = {
+      key: correlationKey,
+      found: currentFound,
+      earlyContentPaths: /* @__PURE__ */ new Set()
+    };
+  }, [correlationKey]);
+  const recovery = useQuery({
+    queryKey: [
+      "vfs",
+      resolvedScopePath ?? "__unscoped__",
+      "minted-asset",
+      origin ?? ""
+    ],
+    queryFn: async () => {
+      const response = await gatewayCall("query", {
+        scope_path: resolvedScopePath,
+        filters: { "field.fsaos_origin_message_path": origin },
+        limit: 1
+      });
+      const rawItems = response.content?.items ?? response.items ?? [];
+      const asset = rawItems[0] ? normalizeItem(rawItems[0]) : null;
+      if (!asset) return null;
+      const children = await fetchVfsChildren(asset.path);
+      const hasBytes = children.some(
+        (child) => child.item_type === "file" && Boolean(child.type_data?.file_ref)
+      );
+      return { asset, hasBytes };
+    },
+    enabled: Boolean(origin && resolvedScopePath && !mintError),
+    refetchInterval: (query) => {
+      if (activeRef.current.key === correlationKey && activeRef.current.found?.hasBytes) {
+        return false;
+      }
+      return query.state.data?.hasBytes ? false : 1500;
+    }
+  });
+  useEffect(() => {
+    const recovered = recovery.data;
+    if (!recovered || activeRef.current.key !== correlationKey) return;
+    const previous = activeRef.current.found;
+    const next = {
+      key: correlationKey,
+      itemId: recovered.asset.id,
+      itemPath: recovered.asset.path,
+      displayName: typeof recovered.asset.type_data?.display_name === "string" ? recovered.asset.type_data.display_name : recovered.asset.name,
+      hasBytes: recovered.hasBytes || Boolean(previous?.itemId === recovered.asset.id && previous.hasBytes)
+    };
+    activeRef.current.found = next;
+    setFound(next);
+  }, [recovery.data, correlationKey]);
+  const waiting = Boolean(origin && resolvedScopeId) && !mintError && !currentFound?.hasBytes;
+  useEffect(() => {
+    if (!waiting || !resolvedScopeId) return;
+    return subscribeToScope(
+      resolvedScopeId,
+      ["asset.materialized", "content.written"]
+    );
+  }, [waiting, resolvedScopeId]);
+  useEffect(() => {
+    if (!waiting || !origin || !resolvedScopeId) return;
+    const generationKey = correlationKey;
+    const payload = (data) => data?.payload ?? data;
+    const eventScope = (data) => {
+      const p = payload(data);
+      const value = p?.scope_id ?? data?.scope_id;
+      return typeof value === "string" ? value : void 0;
+    };
+    const contentPath = (data) => {
+      const p = payload(data);
+      const value = p?.item_path ?? data?.item_path;
+      return typeof value === "string" && value ? value : void 0;
+    };
+    const belongsToAsset = (itemPath, assetPath) => {
+      const normalizedAssetPath = assetPath.replace(/\/+$/, "");
+      return itemPath === normalizedAssetPath || itemPath.startsWith(`${normalizedAssetPath}/`);
+    };
+    const unsubscribes = [
+      subscribeToEvents("asset.materialized", (data) => {
+        if (activeRef.current.key !== generationKey) return;
+        const p = payload(data);
+        if (typeof p?.item_id !== "string" || !p.item_id) return;
+        const previous = activeRef.current.found;
+        const itemPath = typeof p.item_path === "string" ? p.item_path : void 0;
+        const hasBytes = Boolean(p.has_bytes) || Boolean(
+          itemPath && Array.from(activeRef.current.earlyContentPaths).some((path) => belongsToAsset(path, itemPath))
+        ) || Boolean(previous && previous.itemId === p.item_id && previous.hasBytes);
+        const next = {
+          key: generationKey,
+          itemId: p.item_id,
+          itemPath,
+          displayName: typeof p.display_name === "string" ? p.display_name : void 0,
+          hasBytes
+        };
+        activeRef.current.found = next;
+        setFound(next);
+      }, (data) => {
+        const scope = eventScope(data);
+        return (!scope || scope === resolvedScopeId) && payload(data)?.origin === origin;
+      }),
+      subscribeToEvents("content.written", (data) => {
+        if (activeRef.current.key !== generationKey) return;
+        const itemPath = contentPath(data);
+        if (!itemPath) return;
+        const previous = activeRef.current.found;
+        if (!previous?.itemPath || !belongsToAsset(itemPath, previous.itemPath)) {
+          activeRef.current.earlyContentPaths.add(itemPath);
+          if (activeRef.current.earlyContentPaths.size > 128) {
+            const oldest = activeRef.current.earlyContentPaths.values().next().value;
+            if (oldest) activeRef.current.earlyContentPaths.delete(oldest);
+          }
+          return;
+        }
+        if (previous.hasBytes) return;
+        const next = { ...previous, hasBytes: true };
+        activeRef.current.found = next;
+        setFound(next);
+      }, (data) => {
+        const scope = eventScope(data);
+        return (!scope || scope === resolvedScopeId) && Boolean(contentPath(data));
+      })
+    ];
+    return () => unsubscribes.forEach((fn) => fn());
+  }, [waiting, origin, resolvedScopeId, correlationKey]);
+  const state = mintError ? "failed" : !origin ? "idle" : currentFound ? currentFound.hasBytes ? "ready" : "materializing" : "pending";
+  return {
+    state,
+    itemId: currentFound?.itemId,
+    itemPath: currentFound?.itemPath,
+    displayName: currentFound?.displayName,
+    fallbackUrl: fallbackUrl ?? void 0,
+    error: mintError ?? void 0
+  };
+}
 
 // src/schema-utils.ts
 function keyToLabel(key) {
@@ -4702,6 +4917,6 @@ function normalizeRow(row) {
 // src/index.ts
 __registerSdkExports(src_exports);
 
-export { ComponentRenderer, EnforcementDeniedError, FormSubmissionError, GatewayRequestError, InteractionTrackingError, KernelProvider, auth, awaitAnchorReady, awaitScopeReady, callTool, cancelQueuedTurn, cancelTurn, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, electHomeAnchor, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchChannelMessagesWithCards, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchResolvedItems, fetchTimelineHistory, fetchTurnQueueEntries, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAnchor, getAnchorRef, getAnchorVersion, getAssetUrl, getDefaultSort, getHomeAnchor, getMountVersion, getMounts, getPathSubscriptionState, getQueryClient, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, initializeFsaos, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isAnchorReady, isScopeReady, listChildren, mount, mountRealtimeScope, normalizeItem, onConnectionStateChange, pathSubscriptionMatches, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, resubscribePath, setAnchor, setCachedToken, setQueryClient, setScope, setupRequireShim, signal, startTracking, steerTurn, submitForm, subscribeAnchor, subscribeArtifactStream, subscribeMounts, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, trackAction, trackEvent, trackPageView, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAgentTimeline, useAllChannels, useArrangement, useArtifactStream, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMounts, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useResolvedItems, useScope, useScopeReady, useSearch, useTheme, useTimelineHistory, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, useUpdatePrincipal, vfsKeys, waitForPathReady };
+export { ComponentRenderer, EnforcementDeniedError, FormSubmissionError, GatewayRequestError, InteractionTrackingError, KernelProvider, auth, awaitAnchorReady, awaitScopeReady, callTool, cancelQueuedTurn, cancelTurn, clearCachedToken, clearSession, createItem, disconnectSSE, disposeVfsRealtimeWs, electHomeAnchor, emitEvent, fetchChannelMessages, fetchChannelMessagesPage, fetchChannelMessagesWithCards, fetchEdgesForItem, fetchItemHistory, fetchItemVersions, fetchItems, fetchMemberFocus, fetchOpenEnvelope, fetchRecentActivity, fetchResolvedItems, fetchTimelineHistory, fetchTurnQueueEntries, fetchTypeDefinitions, fetchVfsChildren, fetchVfsChildrenPage, fetchVfsItem, fetchVfsItemById, fetchVfsTree, gatewayCall, getAccessToken, getAnchor, getAnchorRef, getAnchorVersion, getAssetUrl, getDefaultSort, getHomeAnchor, getMountVersion, getMounts, getPathSubscriptionState, getQueryClient, getRequiredFormFields, getScope, getScopeVersion, getSessionEntry, initSession, initVfsRealtimeWs, initializeFsaos, interpretSchema, invalidateAllVfs, invalidateChannelMessages, invalidateChildren, invalidateItem, invalidateOpenEnvelope, invalidatePathAndParent, invalidateSubtree, invalidateTypes, isAnchorReady, isScopeReady, listChildren, mount, mountRealtimeScope, normalizeItem, onConnectionStateChange, pathSubscriptionMatches, ping, pushChanges, queryClient, readItem, registerCleanup, resetAllSdkState, resolvePrincipalId, resubscribePath, setAnchor, setCachedToken, setQueryClient, setScope, setupRequireShim, signal, startTracking, steerTurn, submitForm, subscribeAnchor, subscribeArtifactStream, subscribeMounts, subscribeScope, subscribeToEvents, subscribeToPath, subscribeToScope, trackAction, trackEvent, trackPageView, unmountRealtimeScope, updateItem, uploadFile, useAccounts, useAgentTimeline, useAllChannels, useArrangement, useArtifactStream, useAsset, useAuth, useChannelMessages, useChannels, useChildren, useComponent, useCreate, useDelete, useDmChannels, useEdges, useEventStream, useFileUpload, useInfiniteChannelMessages, useInfiniteChildren, useInfiniteItems, useItem, useItemById, useItemHistory, useItemVersions, useItems, useLink, useList, useMemberFocus, useMintedAsset, useMounts, useMove, useMutation, useNotifications, useOpen, usePermission, usePermissions, usePrincipal, useRealtimeQuery, useRecentActivity, useResolve, useResolvedItems, useScope, useScopeReady, useSearch, useTheme, useTimelineHistory, useTool, useTree, useType, useTypeHelpers, useTypes, useUnreadCounts, useUpdate, useUpdatePrincipal, vfsKeys, waitForPathReady };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map