@superatomai/sdk-node 0.0.56-dsp → 0.0.57-dsp

package/dist/index.d.ts

@@ -254,6 +254,12 @@ interface ScriptQueryResult {
      * sentinel toolId so the frontend resolves it via the queryCache short-circuit.
      */
     virtual?: boolean;
+    /**
+     * Restrictions an authorization policy injected into THIS query before it
+     * ran. Handed to getAnalysis/getComponents as `scope` so the answer can name
+     * the restriction without the recipe hardcoding a value that goes stale.
+     */
+    appliedPolicies?: string[];
 }
 /**
  * Match tier returned by the LLM script matcher.
@@ -514,6 +520,13 @@ interface ExecutedToolInfo {
         _summary?: any;
         /** Up to MAIN_AGENT_COMPLETE_ROWS rows — the complete result when small. */
         _mainAgentRows?: any[];
+        /**
+         * Set when an authorization policy restricted the query before it ran.
+         * Read by BOTH agents: the source agent's tool response and the main
+         * agent's result block, because the main agent is the one that writes the
+         * titles, analysis and method line that must state the restriction.
+         */
+        _ACCESS_POLICY_APPLIED?: string;
     };
     /**
      * THIS call's rows, at render size — deliberately a sibling of `result`, not a
@@ -2867,6 +2880,22 @@ declare class ScriptStore {
      * specs, a stale spec array beside a live program is how the wrong one gets
      * read later. See backend/docs/COMPONENTS-AS-PROGRAM-DESIGN.md § 4.4.
      */
+    /**
+     * Body text as it stands now, for reverting an attach that turns out to be
+     * invalid.
+     *
+     * getComponents can only be VALIDATED by running it, and it can only be run
+     * once it is on disk — so attachComponents necessarily writes before anyone
+     * knows whether the body is good. Without a revert, a rejected body stays
+     * attached: promote() then sees the recipe "exports getComponents", clears
+     * the specs the fallback generator produced, and the recipe is verified with
+     * component code that was already rejected. Confirmed live on
+     * "Total Bookings by Branch", which shipped a sourceRef of 'computed:_final'
+     * that validateSpecs had refused.
+     */
+    snapshotBody(recipeId: string): Promise<string | null>;
+    /** Put back a body captured by {@link snapshotBody}. */
+    restoreBody(recipeId: string, body: string): Promise<boolean>;
     attachComponents(recipeId: string, componentsBody: string): Promise<boolean>;
     /**
      * Append (or replace) the `getAnalysis` export on an existing draft body.
@@ -3028,6 +3057,14 @@ declare class MainAgent {
      * is never trusted because it is a program, exactly as an authored spec is not.
      */
     private handleWriteComponents;
+    /**
+     * Restrictions the seam reported while this run's queries executed.
+     *
+     * getData does NOT re-run for write_components/write_analysis, so the child
+     * cannot observe these itself — the parent hands them across, exactly as it
+     * does for `entities`.
+     */
+    private observedPolicies;
     /**
      * Author the answer as a program. Runs after execute_script, so the body is
      * written with the result already known and can react to what it found.
@@ -4430,6 +4467,15 @@ declare class QueryCache {
      * Get the current TTL in minutes
      */
     getTTL(): number;
+    /**
+     * Which access bucket this call reads and writes.
+     *
+     * `''` means the unrestricted bucket and produces a key identical to the one
+     * used before authorization existed. `null` means do not touch the cache.
+     */
+    private scope;
+    /** The stored key: the scope namespace, then the caller's key. NUL cannot occur in SQL. */
+    private scopedKey;
     /**
      * Store query result in data cache.
      * If the key already exists, it's removed first so the re-insert places it
@@ -4500,6 +4546,246 @@ declare class QueryCache {
 }
 declare const queryCache: QueryCache;
 
+/**
+ * Request context — who is asking, carried to wherever it is needed.
+ *
+ * The data seam (`BaseSource.prepareSql()` in the backend) has to know which
+ * user a query is for, so the SQL rewriter has a policy to inject. Identity
+ * arrives here, in the SDK's message handlers; the seam is several layers and
+ * one package away. This module is the carrier for the paths where the async
+ * chain stays intact.
+ *
+ * Design and the paths where it does NOT reach:
+ * backend/docs/REQUEST-CONTEXT-DESIGN.md
+ *
+ * Two rules the rest of the system depends on:
+ *
+ *   1. **Absence is not `system`.** No context means we do not know who is
+ *      asking, which is a different thing from knowing this is a trusted job.
+ *      Conflating them turns every call site anyone forgets into an unpoliced
+ *      one. Trust has to be written down, by name, via `runAsSystem()`.
+ *
+ *   2. **This is not a security boundary on its own.** It carries whatever it
+ *      is given. It is only worth something once the value it carries comes
+ *      from a verified identity rather than the request payload — see the
+ *      Prerequisite section of SQL-AUTHORIZATION-DESIGN.md.
+ */
+/**
+ * Who a unit of work is running on behalf of.
+ *
+ * `system` requires a reason because it appears in the audit log and because
+ * an unexplained escalation is indistinguishable from a bug.
+ */
+type Principal = {
+    kind: 'user';
+    userId: string;
+    orgId?: string;
+    role?: string;
+} | {
+    kind: 'system';
+    reason: string;
+};
+/**
+ * One row restriction, in the shape the rewriter's inject_policies() consumes
+ * directly — no translation layer, deliberately: a mapping step between what an
+ * admin writes and what gets injected is somewhere for the two to drift apart.
+ */
+interface RowFilter {
+    /** Unqualified matches on table name alone; qualified ("dw.FactSales") must match exactly. */
+    table?: string;
+    column: string;
+    op?: 'in' | 'not_in' | 'eq' | 'ne';
+    values: unknown[];
+    /**
+     * How to SAY this restriction to an end user, e.g. "Hyderabad branch".
+     *
+     * Without it the agent has only the predicate, and pastes
+     * `com_trn_documentstamp.LocationId IN (110)` into the answer — accurate and
+     * meaningless to the person reading it. Only whoever writes the policy knows
+     * that 110 is Hyderabad, so only they can supply this.
+     */
+    label?: string;
+}
+/**
+ * What one user may see in one source. `sourceId` is not optional in spirit: a
+ * filter naming a column of one database must never be injected into another's
+ * SQL. Omitting it means "every source", which is only correct for a column that
+ * genuinely exists everywhere.
+ */
+interface SourcePolicy {
+    sourceId?: string | null;
+    /** Default {@link RowFilter.label} for every filter in this policy that lacks its own. */
+    label?: string;
+    rowFilters?: RowFilter[];
+    /** Gate 3. Empty means no table restriction — see SQL-AUTHORIZATION-DESIGN.md. */
+    readableTables?: string[];
+}
+interface RequestContext {
+    principal: Principal;
+    projectId?: string;
+    /**
+     * Access policies resolved ONCE per request, not per query. Empty means
+     * "no restrictions apply". Narrowed to the source being queried at the seam
+     * — see the backend's policy-gate.
+     */
+    policies?: SourcePolicy[];
+    /** Correlates the audit log with a chat turn. */
+    requestId?: string;
+}
+/** The context for the current async chain, or `undefined` if none was established. */
+declare function getRequestContext(): RequestContext | undefined;
+/**
+ * Like `getRequestContext()`, but throws when there is none.
+ *
+ * For call sites that must not proceed anonymously. Prefer this over
+ * `getRequestContext() ?? somethingPermissive` — the fallback is exactly the
+ * silent bypass this module exists to prevent.
+ */
+declare function requireRequestContext(what?: string): RequestContext;
+declare class MissingRequestContextError extends Error {
+    constructor(message: string);
+}
+/** Run `fn` with `ctx` visible to everything it awaits. */
+declare function runWithContext<T>(ctx: RequestContext, fn: () => T): T;
+/** Convenience for the common case: a request on behalf of a signed-in user. */
+declare function runAsUser<T>(user: {
+    userId: string;
+    orgId?: string;
+    role?: string;
+    projectId?: string;
+    requestId?: string;
+    policies?: SourcePolicy[];
+}, fn: () => T): T;
+/**
+ * Declare a unit of work as trusted, naming why.
+ *
+ * For entry points with no user behind them: schedulers, admin tooling, the
+ * cross-machine proxy. `reason` is not decoration — it is what the audit log
+ * shows in place of a user, and it is what makes these paths greppable when
+ * someone asks "what runs unpoliced?".
+ *
+ * Nesting inside a user context deliberately REPLACES it: a system subtask is
+ * an escalation, and it should look like one in the log rather than silently
+ * inheriting a user's restrictions.
+ */
+declare function runAsSystem<T>(reason: string, fn: () => T, opts?: {
+    projectId?: string;
+    requestId?: string;
+}): T;
+/**
+ * Capture the current context so it can be re-entered later.
+ *
+ * For boundaries where the async chain breaks but a reference survives — an
+ * event listener registered outside the request, a callback stored in a
+ * registry. Does NOT help across a process or HTTP boundary (the script
+ * bridge); that needs a token, see the design doc.
+ */
+declare function captureContext(): RequestContext | undefined;
+/** Re-enter a captured context. A no-op wrapper when `ctx` is undefined. */
+declare function withCapturedContext<T>(ctx: RequestContext | undefined, fn: () => T): T;
+/**
+ * Bind a function to the context active at bind time.
+ *
+ * The trap this exists for, stated the right way round (verified, because it
+ * is easy to get backwards): context propagates through ASYNC RESOURCE
+ * creation, and `EventEmitter.emit` is an ordinary synchronous call. So a
+ * plain listener runs in the context active at EMIT time, whatever it was
+ * registered inside. A handler registered during a request and fired later
+ * from another chain therefore sees nothing at all.
+ *
+ * Bind it when the registering context is the one that matters.
+ */
+declare function bindContext<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R;
+/** Short label for logs and audit rows: `user:u_123` / `system:alert-scheduler` / `anonymous`. */
+declare function describeContext(ctx?: RequestContext | undefined): string;
+/** True when the context represents a signed-in user rather than a trusted job. */
+declare function isUserContext(ctx?: RequestContext | undefined): boolean;
+
+/**
+ * Deriving "who is asking" from an incoming WebSocket message.
+ *
+ * Separate from `utils/request-context.ts` on purpose: that module is a pure
+ * carrier with no opinion about where identity comes from, this one knows the
+ * message shape and the trust level of each field.
+ *
+ * See backend/docs/REQUEST-CONTEXT-DESIGN.md and the Prerequisite section of
+ * backend/docs/SQL-AUTHORIZATION-DESIGN.md.
+ */
+
+/**
+ * Read access policies out of the admin-authored per-user config.
+ *
+ * The config is free-form JSON typed by a human into an admin field, so every
+ * step here is defensive: a malformed entry is DROPPED, never guessed at. That
+ * is a deliberate trade-off with a sharp edge — a typo'd policy silently
+ * becomes no policy, i.e. unrestricted. Validating shapes against the source
+ * schema (and refusing, rather than dropping) is the fix, and is not built yet.
+ *
+ * Accepts either a single object or an array, so one user can be scoped across
+ * several sources.
+ */
+declare function policiesFromConfig(config: unknown): SourcePolicy[];
+/**
+ * Run `fn` with the caller's identity established.
+ *
+ * Trust order:
+ *
+ *   1. `message.authContext` — stamped by the relay from a verified session.
+ *      Trustworthy. Does not exist yet.
+ *   2. `payload.userId` — sent by the browser, which can put anything there.
+ *      Enough to prove the plumbing works end to end; NOT enough to enforce
+ *      anything on. Used because it is what exists today.
+ *   3. Neither — no context is established at all.
+ *
+ * Case 3 is deliberately not a `system` context. "We don't know who this is"
+ * and "this is a trusted job" must stay distinguishable, or every path that
+ * loses identity silently becomes an unpoliced one. With no context, the data
+ * seam decides what to do (see SA_SQL_POLICY_ENFORCE), and the honest answer
+ * there is a refusal rather than an unfiltered read.
+ */
+declare function runWithMessageIdentity<T>(message: any, fn: () => T): T;
+
+/**
+ * Context tokens — carrying identity across a boundary AsyncLocalStorage cannot.
+ *
+ * The script flow is the one path where the async chain genuinely breaks:
+ * scripts run in a separate OS process and call back into the backend over
+ * loopback HTTP (`script-bootstrap.ts` → `script-bridge.ts`), so the bridge's
+ * request handler starts a fresh async context with no relationship to the
+ * chat turn that launched the script. Nothing ambient crosses that; the
+ * identity has to be handed over explicitly.
+ *
+ * So: the parent mints a token bound to the live context before spawning, the
+ * child presents it on every bridge call, and the bridge resolves it back and
+ * runs the query inside that context.
+ *
+ * The registry is in-memory and process-local, which is exactly right here —
+ * the minting side (script-runner) and the resolving side (script-bridge) are
+ * both in the backend process; only the script itself is elsewhere. A token is
+ * therefore never valid anywhere but the process that issued it, and never
+ * outlives that process.
+ *
+ * See backend/docs/REQUEST-CONTEXT-DESIGN.md.
+ */
+
+/**
+ * Mint a token for the context active right now.
+ *
+ * Returns `undefined` when there is no context — deliberately, so that an
+ * unidentified script run stays unidentified rather than being handed a token
+ * that vouches for nothing. The bridge then sees no token and the data seam
+ * treats it as anonymous, which is the truth.
+ */
+declare function mintContextToken(ttlMs?: number): string | undefined;
+/** Resolve a token back to its context, or `undefined` if unknown or expired. */
+declare function resolveContextToken(token: string | undefined | null): RequestContext | undefined;
+/** Drop a token. Call when the work it was minted for is finished. */
+declare function revokeContextToken(token: string | undefined | null): void;
+/** Diagnostics only. */
+declare function contextTokenCount(): number;
+/** Test seam. */
+declare function clearContextTokens(): void;
+
 /**
  * Manages conversation history scoped per user + dashboard.
  * Each user-dashboard pair has its own isolated history that expires after a configurable TTL.
@@ -5375,6 +5661,17 @@ interface RunScriptOptions {
      * subsidiary's name" from being a reason to rewrite getData and re-query.
      */
     entities?: ResolvedEntityRef[];
+    /**
+     * Restrictions an authorization policy imposed on this run, handed to
+     * getAnalysis/getComponents as their 6th argument.
+     *
+     * Supplied at RUN time rather than written into the recipe: a policy is
+     * per-request and mutable, a recipe is durable. Baked in, it goes stale the
+     * moment the user's scope changes — the recipe would keep naming the old
+     * scope while the seam injects the new one. Supplied here, a replay always
+     * describes what was actually applied to THAT run.
+     */
+    appliedPolicies?: string[];
 }
 /**
  * Execute a recipe by spawning a tsx child on the script's .ts file.
@@ -5585,4 +5882,4 @@ declare class SuperatomSDK {
     getConversationSimilarityThreshold(): number;
 }
 
-export { type AgentConfig, type AgentEvent, type AgentResponse, type AgentRunContext, type AgentRunHandlers, type AgentRunRecord, type AgentRunResult, type AgentTrigger, type AgentUsage, type ApplySummary, BM25L, type BM25LOptions, type BaseLLMConfig, type BuildTriggerInput, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CodexSessionOptions, type CodingAgentCollectionConfig, type CodingAgentDefinition, type CodingAgentSession, type CodingAgentSessionOptions, type CodingAgentsConfig, type CollectionHandler, type CollectionOperation, type DBUIBlock, DEFAULT_AGENT_CONFIG, type DashboardAgentCollectionConfig, type DatabaseType, type Harness, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type McpServerSpec, type Message, type ModelStrategy, type OutputContract, type OutputField, type OutputValidator, type RerankedResult, type RunAgentOptions, STORAGE_CONFIG, type ScriptComponentSpec, ScriptMatcher, type ScriptParameter, type ScriptRecipe, type ScriptRecipeMetaRow, type ScriptRecipeStore, type ScriptResult, ScriptStore, type ScriptStoreOptions, type SelectedWorkflow, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, type Workspace, anthropicLLM, assertReadOnlySql, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeTriggers, emitAgentEvent, extractNamedExport, geminiLLM, getCodingAgent, getCodingAgentsConfig, groqLLM, hybridRerank, listCodingAgents, llmUsageLogger, logger, normalizeScriptBody, onAgentRun, openaiLLM, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, rerankChromaResults, rerankConversationResults, resolveScriptRecipeStore, runCodingAgent, runScript, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, writeBridgeShims };
+export { type AgentConfig, type AgentEvent, type AgentResponse, type AgentRunContext, type AgentRunHandlers, type AgentRunRecord, type AgentRunResult, type AgentTrigger, type AgentUsage, type ApplySummary, BM25L, type BM25LOptions, type BaseLLMConfig, type BuildTriggerInput, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CodexSessionOptions, type CodingAgentCollectionConfig, type CodingAgentDefinition, type CodingAgentSession, type CodingAgentSessionOptions, type CodingAgentsConfig, type CollectionHandler, type CollectionOperation, type DBUIBlock, DEFAULT_AGENT_CONFIG, type DashboardAgentCollectionConfig, type DatabaseType, type Harness, type HybridSearchOptions, type IncomingMessage, type KbNodesQueryFilters, type KbNodesRequestPayload, LLM, type LLMUsageEntry, type LogLevel, MainAgent, type McpServerSpec, type Message, MissingRequestContextError, type ModelStrategy, type OutputContract, type OutputField, type OutputValidator, type Principal, type RequestContext, type RerankedResult, type RowFilter, type RunAgentOptions, STORAGE_CONFIG, type ScriptComponentSpec, ScriptMatcher, type ScriptParameter, type ScriptRecipe, type ScriptRecipeMetaRow, type ScriptRecipeStore, type ScriptResult, ScriptStore, type ScriptStoreOptions, type SelectedWorkflow, type SourcePolicy, SuperatomSDK, type SuperatomSDKConfig, type TaskType, Thread, ThreadManager, type Tool$1 as Tool, type ToolOutputSchema, type TriggerEvent, type TriggerFireInfo, UIBlock, UILogCollector, type User, UserManager, type UsersData, type WorkflowDescriptor, type Workspace, anthropicLLM, assertReadOnlySql, bindContext, captureContext, clearContextTokens, contextTokenCount, createCodexSession, createCodingAgentSession, dashboardConversationHistory, dataFingerprint, describeContext, describeTriggers, emitAgentEvent, extractNamedExport, geminiLLM, getCodingAgent, getCodingAgentsConfig, getRequestContext, groqLLM, hybridRerank, isUserContext, listCodingAgents, llmUsageLogger, logger, mintContextToken, normalizeScriptBody, onAgentRun, openaiLLM, policiesFromConfig, queryCache, registerCodingAgentCollection, registerCodingAgents, registerDashboardAgentCollection, requireRequestContext, rerankChromaResults, rerankConversationResults, resolveContextToken, resolveScriptRecipeStore, revokeContextToken, runAsSystem, runAsUser, runCodingAgent, runScript, runWithContext, runWithMessageIdentity, startAgentTriggers, stopAgentTriggers, userPromptErrorLogger, withCapturedContext, writeBridgeShims };