@tangle-network/sandbox-ui 0.113.6 → 0.114.0

package/dist/use-sidecar-auth-CCTJcrq7.d.ts

@@ -0,0 +1,145 @@
+import { ReasoningEffort } from "@tangle-network/agent-interface";
+import { SessionMessage, SessionPart } from "@tangle-network/ui/types";
+//#region src/hooks/use-session-stream.d.ts
+/** Minimal session info returned by the listing API. */
+interface SessionInfo {
+  id: string;
+  title: string;
+  parentID?: string;
+}
+interface UseSessionStreamOptions {
+  /** Base URL of the session proxy (e.g. "http://localhost:9100"). */
+  apiUrl: string;
+  /** Bearer token for authentication. */
+  token: string | null;
+  /** Session ID to stream events for. */
+  sessionId: string;
+  /** Only connect when true. Defaults to true. */
+  enabled?: boolean;
+}
+/**
+ * Per-message overrides forwarded to the sidecar's send-message endpoint.
+ * Every field is optional — omitted fields fall back to the session's
+ * backend configuration. Matches `SendMessageRequestSchema` on the sidecar.
+ */
+interface SendMessageOptions {
+  /** Backend agent identifier override (e.g. a named opencode agent). */
+  agent?: string;
+  /** Per-turn model override; session backend supplies apiKey/baseUrl. */
+  model?: {
+    providerID: string;
+    modelID: string;
+  };
+  /** Per-turn system prompt override. */
+  system?: string;
+  /** Thinking-effort hint; the sidecar maps it to a thinking-token budget. The full canonical
+   *  `ReasoningEffort` (`@tangle-network/agent-interface`) — the UI shows only the levels the
+   *  selected harness/model actually supports (a capability filter), never a hard-coded subset. */
+  reasoningEffort?: ReasoningEffort;
+}
+/**
+ * A sandbox-level condition that degrades the session without ending it.
+ *
+ * Distinct from `error`, which reports a turn that failed: the session here is
+ * running and will answer, it is just missing something the caller asked for.
+ * Reported separately so it is not cleared by the next successful turn — the
+ * condition outlives the turn that revealed it.
+ */
+interface SessionDegradation {
+  /** Which capability is degraded. A union so this can grow without a break. */
+  readonly kind: 'hub-connections';
+  /** Machine-readable cause. */
+  readonly reason: string;
+  /** Operator/user-facing sentence, authored by the sidecar. */
+  readonly message: string;
+  /**
+   * What the session asked for, NOT how much it lost.
+   *
+   * There is deliberately no count of missing integrations: the sidecar reaches
+   * this state only for an attach-all request, and the call that would
+   * enumerate the tenant's connections is the one that failed authentication.
+   * Any number rendered here would be fabricated.
+   */
+  readonly requestShape: string;
+}
+interface UseSessionStreamResult {
+  /** All messages in the session (fetched + streaming). */
+  messages: SessionMessage[];
+  /** Part map: messageId → SessionPart[]. */
+  partMap: Record<string, SessionPart[]>;
+  /** Whether the agent is currently streaming a response. */
+  isStreaming: boolean;
+  /** Send a text message to the agent, with optional per-turn overrides. */
+  send: (text: string, options?: SendMessageOptions) => Promise<void>;
+  /** Abort the current agent execution. */
+  abort: () => Promise<void>;
+  /** Refetch full message history from the API. */
+  refetch: () => Promise<void>;
+  /** Connection or stream error, if any. */
+  error: string | null;
+  /** Whether the SSE connection is active. */
+  connected: boolean;
+  /**
+   * The degradation currently reported for THIS session, or `null`.
+   *
+   * Today the only one is a Hub credential the sandbox could not present, which
+   * leaves the agent with an EMPTY toolbelt while the session otherwise runs
+   * normally. Without surfacing it, that state is indistinguishable to the user
+   * from having connected no integrations at all — so a caller that renders a
+   * transcript should render this too.
+   *
+   * Seeded from session status rather than derived from the live stream alone:
+   * the sidecar's bus never replays, so a reload — or attaching a beat after
+   * spawn — would otherwise show a normal-looking session with no tools and no
+   * explanation. Live frames update it, and a recovered credential clears it.
+   */
+  degradation: SessionDegradation | null;
+}
+declare class SessionStreamError extends Error {
+  readonly code: string;
+  readonly status?: number;
+  constructor(code: string, message: string, status?: number);
+}
+declare const SESSION_STREAM_RECONNECT_DELAY_MS = 1000;
+/**
+ * Streams chat messages from a sidecar session gateway via SSE.
+ *
+ * Fetches existing message history on mount, then subscribes to SSE for
+ * real-time updates. Maps the sidecar's message format to agent-ui's
+ * SessionMessage + partMap format.
+ */
+declare function useSessionStream({ apiUrl, token, sessionId, enabled }: UseSessionStreamOptions): UseSessionStreamResult;
+//#endregion
+//#region src/hooks/use-sidecar-auth.d.ts
+interface UseSidecarAuthOptions {
+  /** Scoping key for token storage (e.g. botId, sandboxId). */
+  resourceId: string;
+  /** Base URL of the sidecar or operator API. */
+  apiUrl: string;
+  /**
+   * Sign a plaintext message and return the hex signature.
+   * Consuming apps wire this to their wallet library (e.g. wagmi's signMessageAsync).
+   */
+  signMessage: (message: string) => Promise<string>;
+}
+interface SidecarAuth {
+  token: string | null;
+  isAuthenticated: boolean;
+  isAuthenticating: boolean;
+  authenticate: () => Promise<string | null>;
+  clearCachedToken: () => void;
+  error: string | null;
+}
+/**
+ * Generic sidecar PASETO challenge/response auth.
+ *
+ * Flow:
+ * 1. POST /api/auth/challenge  → { nonce, message, expires_at }
+ * 2. signMessage(message)       → signature (provided by consuming app)
+ * 3. POST /api/auth/session     → { token, address, expires_at }
+ *
+ * Tokens are cached in localStorage and auto-refreshed 5 minutes before expiry.
+ */
+declare function useSidecarAuth({ resourceId, apiUrl, signMessage }: UseSidecarAuthOptions): SidecarAuth;
+//#endregion
+export { SendMessageOptions as a, SessionStreamError as c, useSessionStream as d, SESSION_STREAM_RECONNECT_DELAY_MS as i, UseSessionStreamOptions as l, UseSidecarAuthOptions as n, SessionDegradation as o, useSidecarAuth as r, SessionInfo as s, SidecarAuth as t, UseSessionStreamResult as u };