@tangle-network/agent-app 0.11.0 → 0.12.0

package/dist/runtime/index.d.ts

@@ -1,6 +1,7 @@
 export { C as CatalogModel, M as ModelCatalog, R as RouterModel, _ as __resetCatalogCache, b as buildCatalog, f as fetchModelCatalog, n as normalizeModelId } from '../model-catalog-BEAEVDaa.js';
 export { C as CreateTangleRouterModelConfigOptions, D as DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR, a as DEFAULT_TANGLE_ROUTER_BASE_URL, R as ResolveModelOptions, b as ResolveUserTangleExecutionKeyForUserOptions, c as ResolveUserTangleExecutionKeyOptions, d as ResolvedTangleExecutionKey, T as TangleBillingEnforcementOptions, e as TangleExecutionEnvironment, f as TangleExecutionKeyError, g as TangleExecutionKeyErrorCode, h as TangleExecutionKeyHttpError, i as TangleExecutionKeySource, j as TangleModelConfig, k as createTangleRouterModelConfig, l as isTangleBillingEnforcementDisabled, m as isTangleExecutionKeyError, r as resolveTangleExecutionEnvironment, n as resolveTangleModelConfig, o as resolveUserTangleExecutionKey, p as resolveUserTangleExecutionKeyForUser, t as tangleExecutionKeyHttpError } from '../model-CKzniMMr.js';
 import { b as AppToolContext, e as AppToolProducedEvent, f as AppToolTaxonomy, c as AppToolHandlers, d as AppToolOutcome } from '../types-By4B3K37.js';
+import { a as AppToolMcpServer } from '../mcp-CIupfjxV.js';
 
 /**
  * OpenAI-compatible stream → `LoopEvent` adapter, for NON-sandbox copilots.
@@ -170,6 +171,112 @@ interface AgentRuntime {
  */
 declare function createAgentRuntime(opts: CreateAgentRuntimeOptions): AgentRuntime;
 
+/**
+ * Surface-scoped profile overlay — the seam letting any product page (a
+ * sequence editor, a brief composer, a dataset view) add MCP servers, a prompt
+ * addendum, and permission tightening to the workspace agent profile for turns
+ * initiated FROM that surface, without the chat orchestrator knowing any
+ * surface's specifics. The orchestrator resolves `(kind, ctx)` through a
+ * registry the REQUEST HANDLER constructs per request (construction is a Map
+ * build — cheap) and merges the result into the base profile it was about to
+ * send to the sandbox. Per-request construction is the trust mechanism, not an
+ * optimization target: each `build()` closes over server-trusted request state
+ * (env bindings, secrets, the AUTHENTICATED user/workspace), which on Workers
+ * exists only per request — a startup-built registry would force identity
+ * through the untrusted client `ctx`.
+ *
+ * SECURITY INVARIANT: the surface `kind` and the ids inside `ctx` arrive on
+ * the client request and are pure ROUTING data — never trusted content, never
+ * identity. Identity comes from the closure (see above). The registered
+ * `build()` runs server-side only: it validates the routing ids against the
+ * product's access control, then mints its own URLs and capability tokens from
+ * server configuration (`buildHttpMcpServer` + `createCapabilityToken` in
+ * ../tools). A client can therefore never inject an arbitrary MCP url, header,
+ * or token into the agent profile: the overlay's `mcp` values are typed as
+ * {@link SurfaceMcpServer} (= the server-built `AppToolMcpServer` entry shape),
+ * and only build() constructs them.
+ */
+
+/** Sandbox permission posture values, ranked deny > ask > allow for merging. */
+type SurfacePermissionValue = 'allow' | 'ask' | 'deny';
+/** The only MCP entry shape an overlay may carry: the server-built bridge
+ *  entry from ../tools/mcp (transport, url, headers, and capability token all
+ *  assembled server-side). The alias exists so overlay authors reach for the
+ *  builders in ../tools rather than hand-rolling `{ url: ctx.url }` shapes
+ *  that would let request data become a dialable endpoint. */
+type SurfaceMcpServer = AppToolMcpServer;
+/** What one surface contributes to the agent profile for a single turn. */
+interface SurfaceOverlay {
+    /** MCP servers to mount for this turn, keyed by tool-routing name. Names
+     *  must not collide with the base profile's — see {@link mergeSurfaceOverlay}. */
+    mcp?: Record<string, SurfaceMcpServer>;
+    /** Appended to the base system-prompt addendum with a blank-line separator. */
+    promptAddendum?: string;
+    /** Per-key posture the surface wants for its turns. Merging is monotone
+     *  fail-closed: the stricter of base/overlay wins, so a surface can tighten
+     *  the workspace posture but never relax it. */
+    permissions?: Record<string, SurfacePermissionValue>;
+}
+/**
+ * One registered surface kind. `TCtx` is the shape build() expects — a CLAIM
+ * about the client payload, not a guarantee: the registry hands build() the
+ * request's `ctx` unvalidated, so build() must treat every field as an
+ * untrusted id (resolve it through access control that throws on a bad or
+ * foreign id) before minting anything from it.
+ */
+interface SurfaceKindDefinition<TCtx> {
+    kind: string;
+    build: (ctx: TCtx) => SurfaceOverlay | Promise<SurfaceOverlay>;
+}
+/** The variance-erased form a registry accepts (`build` is contravariant in
+ *  `TCtx`, so every concrete definition is assignable to this). */
+type AnySurfaceKind = SurfaceKindDefinition<never>;
+/**
+ * Declare one surface kind. The `kind` string is the client-visible routing
+ * key (e.g. `'sequences'`); `build` is the server-side factory that turns a
+ * validated ctx into the overlay for one turn.
+ */
+declare function defineSurfaceKind<TCtx>(opts: {
+    kind: string;
+    build: (ctx: TCtx) => SurfaceOverlay | Promise<SurfaceOverlay>;
+}): SurfaceKindDefinition<TCtx>;
+interface SurfaceRegistry {
+    /** Build the overlay for one turn. Throws on an unknown kind — an unknown
+     *  surface is a routing bug (client and server registries drifted), and
+     *  silently returning an empty overlay would strip the surface's tools from
+     *  the turn with no signal anywhere. Build errors propagate unwrapped. */
+    resolve(kind: string, ctx: unknown): Promise<SurfaceOverlay>;
+}
+/**
+ * Assemble the product's surface registry from its registered kinds. Duplicate
+ * kinds throw at construction: two builders behind one routing key would make
+ * the mounted toolset depend on registration order.
+ */
+declare function createSurfaceRegistry(kinds: readonly AnySurfaceKind[]): SurfaceRegistry;
+/** Base-profile slice the merge reads/writes. Real callers pass their full
+ *  profile object; every field outside this slice passes through untouched. */
+interface SurfaceMergeBase {
+    mcp?: Record<string, unknown>;
+    systemPromptAddendum?: string;
+    permissions?: Record<string, SurfacePermissionValue>;
+}
+/**
+ * Merge one surface overlay into a base profile, returning a new object
+ * (the base is never mutated; untouched nested records are shared by
+ * reference).
+ *
+ * - `mcp`: overlay servers are added under their own names. A name already
+ *   present on the base THROWS — a collision is two servers claiming one
+ *   routing name, and renaming either silently would corrupt tool routing for
+ *   whichever caller expected the original binding.
+ * - `systemPromptAddendum`: the overlay's `promptAddendum` appends after a
+ *   blank-line separator (no separator when the base has no addendum).
+ * - `permissions`: per key the STRICTER value wins (deny > ask > allow). A
+ *   surface can tighten the base posture for its turns; a base 'deny' survives
+ *   any overlay.
+ */
+declare function mergeSurfaceOverlay<TBase extends SurfaceMergeBase>(base: TBase, overlay: SurfaceOverlay): TBase & SurfaceMergeBase;
+
 interface LoopToolCall {
     toolCallId?: string;
     toolName: string;
@@ -346,4 +453,4 @@ interface StreamAppToolLoopOptions<Raw> {
  */
 declare function streamAppToolLoop<Raw>(opts: StreamAppToolLoopOptions<Raw>): AsyncGenerator<StreamLoopYield<Raw>, void, unknown>;
 
-export { type AgentRuntime, type AgentRuntimeModelConfig, type AgentTurnOptions, type AppToolLoopOptions, type CreateAgentRuntimeOptions, type LoopAssistantToolCall, type LoopEvent, type LoopMessage, type LoopToolCall, type OpenAICompatStreamTurnOptions, type OpenAIStreamChunk, type StreamAppToolLoopOptions, type StreamLoopYield, type ToolLoopResult, type ToolLoopStopReason, createAgentRuntime, createOpenAICompatStreamTurn, runAppToolLoop, streamAppToolLoop, toLoopEvents };
+export { type AgentRuntime, type AgentRuntimeModelConfig, type AgentTurnOptions, type AnySurfaceKind, type AppToolLoopOptions, type CreateAgentRuntimeOptions, type LoopAssistantToolCall, type LoopEvent, type LoopMessage, type LoopToolCall, type OpenAICompatStreamTurnOptions, type OpenAIStreamChunk, type StreamAppToolLoopOptions, type StreamLoopYield, type SurfaceKindDefinition, type SurfaceMcpServer, type SurfaceMergeBase, type SurfaceOverlay, type SurfacePermissionValue, type SurfaceRegistry, type ToolLoopResult, type ToolLoopStopReason, createAgentRuntime, createOpenAICompatStreamTurn, createSurfaceRegistry, defineSurfaceKind, mergeSurfaceOverlay, runAppToolLoop, streamAppToolLoop, toLoopEvents };

package/dist/runtime/index.js

@@ -3,12 +3,15 @@ import {
   buildCatalog,
   createAgentRuntime,
   createOpenAICompatStreamTurn,
+  createSurfaceRegistry,
+  defineSurfaceKind,
   fetchModelCatalog,
+  mergeSurfaceOverlay,
   normalizeModelId,
   runAppToolLoop,
   streamAppToolLoop,
   toLoopEvents
-} from "../chunk-4YTWB5MG.js";
+} from "../chunk-ETX4O4BB.js";
 import {
   DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR,
   DEFAULT_TANGLE_ROUTER_BASE_URL,
@@ -31,10 +34,13 @@ export {
   buildCatalog,
   createAgentRuntime,
   createOpenAICompatStreamTurn,
+  createSurfaceRegistry,
   createTangleRouterModelConfig,
+  defineSurfaceKind,
   fetchModelCatalog,
   isTangleBillingEnforcementDisabled,
   isTangleExecutionKeyError,
+  mergeSurfaceOverlay,
   normalizeModelId,
   resolveTangleExecutionEnvironment,
   resolveTangleModelConfig,