From 45199d8af5abdf7a5ea4f7e552ca955aa058e4d3 Mon Sep 17 00:00:00 2001 From: Drew Stone Date: Fri, 24 Jul 2026 10:13:41 -0600 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20draft=20JSDoc=20for=20978=20undocum?= =?UTF-8?q?ented=20exports=20(47%=E2=86=9295%)=20via=20agent-docs=20sugges?= =?UTF-8?q?t?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fills the public-API JSDoc gap so the generated agent-readable docs (llms.txt, API pages) carry real summaries. Drafted by @tangle-network/agent-docs suggest — a cheap model (gpt-4.1-mini via the Tangle router) writes a one-line summary from each undocumented export's signature + source, inserted above the declaration. Then the deterministic doc pass (scripts/gen-codemap.mjs) picks them up, so the committed docs stay type-derived. - 978 JSDoc comments across 168 source files; documented coverage 47%→95% (3146/3318 exports). - Additive comments only — `pnpm typecheck` stays green; behavior unchanged. - docs/ regenerated so the codemap staleness gate passes. These are model-drafted summaries for human review — accurate on spot-check (e.g. AuthorizeResult → "Resolve authorization status and context for a chat turn…"), and improvable in place; NO raw model text enters the gated output. --- docs/api/app-auth.md | 10 +- docs/api/assets.md | 82 +- docs/api/assistant.md | 40 +- docs/api/billing.md | 16 +- docs/api/brand-extraction.md | 6 +- docs/api/brand.md | 4 +- docs/api/catalog.md | 4 +- docs/api/chat-routes.md | 110 +- docs/api/chat-store.md | 54 +- docs/api/config.md | 2 +- docs/api/design-canvas-drizzle.md | 16 +- docs/api/design-canvas-react-engine.md | 98 +- docs/api/design-canvas-react-lazy.md | 2 +- docs/api/design-canvas-react.md | 108 +- docs/api/design-canvas.md | 150 +-- docs/api/durable-chat.md | 90 +- docs/api/harness.md | 10 +- docs/api/index.md | 1066 ++++++++--------- docs/api/intakes-api.md | 2 +- docs/api/intakes-drizzle.md | 16 +- docs/api/intakes-react-lazy.md | 4 +- docs/api/intakes-react.md | 2 +- docs/api/intakes.md | 2 +- docs/api/integrations.md | 8 +- docs/api/interactions.md | 56 +- docs/api/knowledge-loop.md | 6 +- docs/api/knowledge.md | 4 +- docs/api/missions.md | 50 +- docs/api/model-resolution.md | 20 +- docs/api/plans.md | 12 +- docs/api/platform.md | 70 +- docs/api/preflight.md | 6 +- docs/api/preset-cloudflare.md | 6 +- docs/api/redact.md | 10 +- docs/api/run.md | 6 +- docs/api/runtime.md | 56 +- docs/api/sandbox.md | 186 +-- docs/api/sequences-drizzle.md | 20 +- docs/api/sequences-react.md | 60 +- docs/api/sequences.md | 150 +-- docs/api/store.md | 10 +- docs/api/stream.md | 56 +- docs/api/studio-react.md | 6 +- docs/api/studio.md | 74 +- docs/api/tangle.md | 6 +- docs/api/teams-drizzle.md | 46 +- docs/api/teams-invitations-api.md | 12 +- docs/api/teams-members-api.md | 4 +- docs/api/teams-react-lazy.md | 12 +- docs/api/teams-react.md | 10 +- docs/api/teams-resend.md | 2 +- docs/api/teams.md | 48 +- docs/api/theme-contract.md | 6 +- docs/api/theme-tailwind-preset.md | 2 +- docs/api/theme.md | 4 +- docs/api/tools.md | 50 +- docs/api/trace.md | 12 +- docs/api/turn-stream.md | 52 +- docs/api/vault-lazy.md | 4 +- docs/api/vault.md | 2 +- docs/api/web-react-terminal.md | 10 +- docs/api/web-react.md | 156 +-- docs/api/web.md | 8 +- src/app-auth/index.ts | 5 + src/assets/schema.ts | 7 + src/assets/types.ts | 34 + src/assistant/client.ts | 4 + src/assistant/types.ts | 10 + src/assistant/useAssistantChat.ts | 3 + src/assistant/useAssistantModels.ts | 1 + src/assistant/useAssistantThreads.ts | 2 + src/billing/index.ts | 8 + src/brand-extraction/map.ts | 2 + src/brand-extraction/types.ts | 1 + src/brand/index.tsx | 2 + src/chat-routes/attachment-upload.ts | 2 + src/chat-routes/attachment-validation.ts | 1 + src/chat-routes/detached-turn.ts | 2 + src/chat-routes/dispatch-parts.ts | 4 + src/chat-routes/durable-projection.ts | 2 + src/chat-routes/file-index.ts | 5 + src/chat-routes/promote-file-part.ts | 4 + src/chat-routes/resolve-attachments.ts | 2 + src/chat-routes/sandbox-producer.ts | 2 + src/chat-routes/stale-turn-lock.ts | 2 + src/chat-routes/turn-routes.ts | 9 + src/chat-routes/upload.ts | 4 + src/chat-routes/wire.ts | 15 + src/chat-store/parts.ts | 13 + src/chat-store/schema.ts | 6 + src/chat-store/store.ts | 8 + .../components/layer-tree.ts | 1 + .../components/ruler-math.ts | 2 + .../components/transform-math.ts | 1 + src/design-canvas-react/contracts.ts | 11 + .../engine/command-stack.ts | 1 + src/design-canvas-react/engine/commands.ts | 30 + src/design-canvas-react/engine/selection.ts | 2 + src/design-canvas-react/engine/snap.ts | 1 + src/design-canvas-react/engine/zoom-pan.ts | 2 + src/design-canvas-react/export-math.ts | 1 + src/design-canvas-react/export.ts | 1 + src/design-canvas/apply.ts | 3 + src/design-canvas/drizzle-store.ts | 2 + src/design-canvas/export-presets.ts | 9 + src/design-canvas/mcp-entry.ts | 2 + src/design-canvas/mcp-handler.ts | 3 + src/design-canvas/mcp-tools.ts | 5 + src/design-canvas/model.ts | 24 + src/design-canvas/operations.ts | 18 + src/design-canvas/schema.ts | 6 + src/design-canvas/store.ts | 6 + src/design-canvas/templates.ts | 3 + src/design-canvas/validate.ts | 2 + src/durable-chat/adapters.ts | 4 + src/durable-chat/errors.ts | 4 + src/durable-chat/interactions.ts | 4 + src/durable-chat/memory.ts | 1 + src/durable-chat/plan-routes.ts | 5 + src/durable-chat/types.ts | 27 + src/harness/index.ts | 5 + src/intakes-react/contracts.ts | 1 + src/intakes-react/lazy.tsx | 1 + src/intakes/api.ts | 1 + src/intakes/drizzle/schema.ts | 5 + src/intakes/drizzle/store.ts | 3 + src/intakes/model.ts | 1 + src/integrations/index.ts | 4 + src/interactions/contract.ts | 17 + src/interactions/route.ts | 9 + src/interactions/sidecar.ts | 2 + src/knowledge-loop/index.ts | 3 + src/knowledge/index.ts | 2 + src/missions/engine.ts | 9 + src/missions/events.ts | 3 + src/missions/plan-parse.ts | 3 + src/missions/service.ts | 10 + src/model-resolution/index.ts | 10 + src/plans/index.ts | 6 + src/platform/billing.ts | 13 + src/platform/guards.ts | 7 + src/platform/hub.ts | 9 + src/platform/sso.ts | 6 + src/preflight/index.ts | 3 + src/preset-cloudflare/index.ts | 3 + src/redact/index.ts | 5 + src/run/index.ts | 3 + src/runtime/agent.ts | 3 + src/runtime/certified-delivery.ts | 2 + src/runtime/model-catalog.ts | 2 + src/runtime/model.ts | 19 + src/runtime/openai-stream.ts | 1 + src/runtime/surface-profile.ts | 1 + src/sandbox/binary-read.ts | 3 + src/sandbox/index.ts | 60 + src/sandbox/outcome.ts | 1 + src/sandbox/terminal-proxy-token.ts | 3 + src/sandbox/workspace-terminal.ts | 26 + src/sequences-react/contracts.ts | 6 + src/sequences-react/engine/command-stack.ts | 1 + src/sequences-react/engine/commands.ts | 10 + src/sequences-react/engine/playback.ts | 2 + src/sequences-react/engine/snap.ts | 1 + src/sequences-react/engine/zoom.ts | 2 + src/sequences-react/media/frame-provider.ts | 5 + src/sequences-react/media/transcription.ts | 3 + src/sequences/apply.ts | 1 + src/sequences/captions.ts | 2 + src/sequences/drizzle-store.ts | 2 + src/sequences/exports.ts | 12 + src/sequences/mcp-entry.ts | 2 + src/sequences/mcp-handler.ts | 3 + src/sequences/mcp-tools.ts | 6 + src/sequences/model.ts | 16 + src/sequences/operations.ts | 14 + src/sequences/schema.ts | 8 + src/sequences/store.ts | 5 + src/sequences/validate.ts | 14 + src/store/index.ts | 5 + src/stream/stream-normalizer.ts | 16 + src/stream/turn-buffer.ts | 6 + src/stream/turn-identity.ts | 6 + src/studio-react/type-config.ts | 3 + src/studio/generation.ts | 37 + src/tangle/index.ts | 3 + src/teams-react/contracts.ts | 5 + src/teams-react/lazy.tsx | 3 + src/teams/drizzle/access.ts | 9 + src/teams/drizzle/invitations-schema.ts | 4 + src/teams/drizzle/personal-organization.ts | 4 + src/teams/drizzle/schema.ts | 6 + src/teams/invitations-api.ts | 6 + src/teams/invitations.ts | 10 + src/teams/invite.ts | 2 + src/teams/members-api.ts | 2 + src/teams/resend.ts | 1 + src/teams/roles.ts | 12 + src/theme-contract/index.ts | 3 + src/theme/tailwind-preset.ts | 1 + src/theme/theme.ts | 2 + src/tools/auth.ts | 3 + src/tools/capability.ts | 2 + src/tools/dispatch.ts | 1 + src/tools/gating.ts | 2 + src/tools/http.ts | 1 + src/tools/mcp-rpc.ts | 3 + src/tools/mcp.ts | 2 + src/tools/openai.ts | 2 + src/tools/runtime.ts | 1 + src/tools/types.ts | 8 + src/trace/flow-types.ts | 1 + src/trace/index.ts | 3 + src/trace/mission-flow.ts | 1 + src/trace/mission-trace.ts | 1 + src/turn-stream/adapters.ts | 9 + src/turn-stream/core.ts | 13 + src/turn-stream/do.ts | 2 + src/turn-stream/memory.ts | 2 + src/vault/contracts.ts | 1 + src/vault/lazy.tsx | 1 + src/web-react/chat-stream.ts | 5 + src/web-react/durable-interaction-submit.ts | 5 + src/web-react/durable-plan-flow.ts | 9 + src/web-react/index.tsx | 7 + src/web-react/interaction-card-support.ts | 6 + src/web-react/sandbox-terminal.ts | 5 + src/web-react/smooth-text.ts | 1 + src/web-react/use-chat-interactions.ts | 5 + src/web-react/use-composer-attachments.ts | 2 + src/web-react/use-file-mentions.ts | 3 + src/web/index.ts | 4 + 231 files changed, 2584 insertions(+), 1606 deletions(-) diff --git a/docs/api/app-auth.md b/docs/api/app-auth.md index 619360a..649110a 100644 --- a/docs/api/app-auth.md +++ b/docs/api/app-auth.md @@ -8,7 +8,7 @@ Source: `src/app-auth/index.ts` ### `AppAuth` -`interface` +`interface` — Define authentication guard with session retrieval and optional SSO handlers for app requests ```ts interface AppAuth @@ -16,7 +16,7 @@ interface AppAuth ### `AppAuthConfig` -`interface` +`interface` — Define configuration settings for app authentication including app name, base URL, secrets, and trusted origins ```ts interface AppAuthConfig @@ -32,7 +32,7 @@ interface AppAuthEmailClient ### `AppAuthEmailConfig` -`interface` +`interface` — Define email configuration for app authentication including client, sender, verification, and warning options ```ts interface AppAuthEmailConfig @@ -48,7 +48,7 @@ type AppAuthInstance ### `AppAuthSchema` -`interface` +`interface` — Define the structure for application authentication data including users, sessions, accounts, and verifications ```ts interface AppAuthSchema @@ -64,7 +64,7 @@ interface AppAuthSession ### `AppAuthSocialConfig` -`interface` +`interface` — Define social authentication configuration options for GitHub and Google providers ```ts interface AppAuthSocialConfig diff --git a/docs/api/assets.md b/docs/api/assets.md index 1d59f11..df96a14 100644 --- a/docs/api/assets.md +++ b/docs/api/assets.md @@ -8,7 +8,7 @@ Source: `src/assets/index.ts` ### `ApprovalEvent` -`interface` +`interface` — Describe an approval event with action details, user info, and optional edited fields ```ts interface ApprovalEvent @@ -16,7 +16,7 @@ interface ApprovalEvent ### `ApprovalEventSchema` -`const` +`const` — Validate approval event data including asset, action, user, timestamp, and optional fields ```ts ZodObject<{ assetId: ZodString; variantId: ZodOptional; action: ZodEnum<{ scheduled: "scheduled"; approved:… @@ -24,7 +24,7 @@ ZodObject<{ assetId: ZodString; variantId: ZodOptional; action: ZodEn ### `AssetContentMap` -`type` +`type` — Map asset keys to their corresponding content types for various media and copy formats ```ts type AssetContentMap @@ -32,7 +32,7 @@ type AssetContentMap ### `AssetFormat` -`type` +`type` — Define valid asset format strings for various media and copy types ```ts type AssetFormat @@ -40,7 +40,7 @@ type AssetFormat ### `AssetSpec` -`interface` +`interface` — Define the structure and metadata for an asset including its format, brand, content, and status ```ts interface AssetSpec @@ -48,7 +48,7 @@ interface AssetSpec ### `AssetStatus` -`type` +`type` — Define possible states representing the lifecycle status of an asset ```ts type AssetStatus @@ -56,7 +56,7 @@ type AssetStatus ### `AssetVariant` -`interface` +`interface` — Describe an asset variant with identification, approval status, and edit history details ```ts interface AssetVariant @@ -64,7 +64,7 @@ interface AssetVariant ### `BrandTokens` -`interface` +`interface` — Define brand identity tokens including colors, font, logo, business name, and voice ```ts interface BrandTokens @@ -72,7 +72,7 @@ interface BrandTokens ### `BrandTokensSchema` -`const` +`const` — Validate brand token properties including colors, font, logo URL, business name, and voice ```ts ZodObject<{ primaryColor: ZodString; accentColor: ZodString; textColor: ZodString; fontFamily: ZodString; logoUrl: ZodO… @@ -80,7 +80,7 @@ ZodObject<{ primaryColor: ZodString; accentColor: ZodString; textColor: ZodStrin ### `ConversionMetrics` -`interface` +`interface` — Define metrics for tracking impressions, clicks, conversions, and related rates ```ts interface ConversionMetrics @@ -88,7 +88,7 @@ interface ConversionMetrics ### `ConversionMetricsSchema` -`const` +`const` — Validate conversion metrics with nonnegative impressions, clicks, conversions, CTR, and CVR fields ```ts ZodObject<{ impressions: ZodNumber; clicks: ZodNumber; conversions: ZodNumber; ctr: ZodNumber; cvr: ZodNumber; }, $stri… @@ -96,7 +96,7 @@ ZodObject<{ impressions: ZodNumber; clicks: ZodNumber; conversions: ZodNumber; c ### `CopyContent` -`interface` +`interface` — Define the structure for content with headline, body, platform, and optional hashtags and character count ```ts interface CopyContent @@ -104,7 +104,7 @@ interface CopyContent ### `CopyContentSchema` -`const` +`const` — Validate and parse copy content with headline, body, optional hashtags, platform, and character count ```ts ZodObject<{ headline: ZodString; body: ZodString; hashtags: ZodOptional>; platform: ZodEnum<{ x: "x… @@ -112,7 +112,7 @@ ZodObject<{ headline: ZodString; body: ZodString; hashtags: ZodOptional; sections: ZodArray; sections: Zod ### `EmailCtaSection` -`interface` +`interface` — Define a call-to-action section with label, URL, and optional subtext for email content ```ts interface EmailCtaSection @@ -152,7 +152,7 @@ interface EmailCtaSection ### `EmailDividerSection` -`interface` +`interface` — Define a section representing a divider in an email layout ```ts interface EmailDividerSection @@ -160,7 +160,7 @@ interface EmailDividerSection ### `EmailFeatureSection` -`interface` +`interface` — Define a feature section with headline, description, and optional image for email content ```ts interface EmailFeatureSection @@ -168,7 +168,7 @@ interface EmailFeatureSection ### `EmailHeroSection` -`interface` +`interface` — Define the structure for a hero section in an email with headline, image, and call-to-action fields ```ts interface EmailHeroSection @@ -176,7 +176,7 @@ interface EmailHeroSection ### `EmailSection` -`type` +`type` — Define a union type representing different sections of an email template ```ts type EmailSection @@ -184,7 +184,7 @@ type EmailSection ### `EmailTestimonialSection` -`interface` +`interface` — Define the structure for an email testimonial section with quote, author, and optional details ```ts interface EmailTestimonialSection @@ -192,7 +192,7 @@ interface EmailTestimonialSection ### `ImageBackground` -`type` +`type` — Define image background styles as color, gradient, or image with optional overlay settings ```ts type ImageBackground @@ -200,7 +200,7 @@ type ImageBackground ### `ImageContent` -`interface` +`interface` — Define the structure for image content containing an array of image slides ```ts interface ImageContent @@ -208,7 +208,7 @@ interface ImageContent ### `ImageContentSchema` -`const` +`const` — Validate image content with an array of one or more slides containing background details ```ts ZodObject<{ slides: ZodArray; valu… @@ -216,7 +216,7 @@ ZodObject<{ slides: ZodArray AssistantChat @@ -432,7 +432,7 @@ interface UseAssistantChatOptions ### `useAssistantModels` -`function` +`function` — Resolve and return the current assistant models from the per-client cache with immediate client swap updates ```ts () => AssistantModels @@ -440,7 +440,7 @@ interface UseAssistantChatOptions ### `useAssistantThreads` -`function` +`function` — Resolve and manage assistant threads state for a given user including pending deletions and refresh logic ```ts (userId: string | null) => AssistantThreads diff --git a/docs/api/billing.md b/docs/api/billing.md index 929b3ab..9c9b6c9 100644 --- a/docs/api/billing.md +++ b/docs/api/billing.md @@ -8,7 +8,7 @@ Source: `src/billing/index.ts` ### `createPlatformBalanceManager` -`function` +`function` — Create a platform balance manager to handle user plan limits and state based on provided options ```ts (opts: PlatformBalanceManagerOptions) => PlatformBalanceManager @@ -24,7 +24,7 @@ Source: `src/billing/index.ts` ### `createWorkspaceKeyManager` -`function` +`function` — Create a workspace key manager that handles key provisioning and budget tracking ```ts (opts: WorkspaceKeyManagerOptions) => WorkspaceKeyManager @@ -64,7 +64,7 @@ interface PlatformBalanceInfo ### `PlatformBalanceManager` -`interface` +`interface` — Manage user plans and balances including state retrieval, billing authorization, deduction, and usage tracking ```ts interface PlatformBalanceManager @@ -72,7 +72,7 @@ interface PlatformBalanceManager ### `PlatformBalanceManagerOptions` -`interface` +`interface` — Define configuration options for managing platform balance based on billing plans ```ts interface PlatformBalanceManagerOptions @@ -104,7 +104,7 @@ interface PlatformProductUsage ### `SharedBillingState` -`interface` +`interface` — Define shared billing state including user ID, plan, balances, concurrency, and overage permission ```ts interface SharedBillingState @@ -120,7 +120,7 @@ interface TcloudKeyClient ### `WorkspaceKeyManager` -`interface` +`interface` — Manage workspace keys by ensuring, rotating, and tracking usage of active child-key secrets ```ts interface WorkspaceKeyManager @@ -128,7 +128,7 @@ interface WorkspaceKeyManager ### `WorkspaceKeyManagerOptions` -`interface` +`interface` — Define configuration options for managing workspace keys including provisioning, storage, and cryptography ```ts interface WorkspaceKeyManagerOptions @@ -152,7 +152,7 @@ interface WorkspaceKeyStore ### `WorkspaceModelKeyUsage` -`interface` +`interface` — Describe usage and budget details for a workspace model key including expiration and exhaustion status ```ts interface WorkspaceModelKeyUsage diff --git a/docs/api/brand-extraction.md b/docs/api/brand-extraction.md index 634316c..7f131aa 100644 --- a/docs/api/brand-extraction.md +++ b/docs/api/brand-extraction.md @@ -72,7 +72,7 @@ interface DecidedBrandKit ### `DecidedFonts` -`interface` +`interface` — Define font selections for display and body text with optional BrandFont properties ```ts interface DecidedFonts @@ -80,7 +80,7 @@ interface DecidedFonts ### `DecidedPalette` -`interface` +`interface` — Define a color palette with background, surface, text, and accent colors for UI elements ```ts interface DecidedPalette @@ -112,7 +112,7 @@ interface DecidedPalette ### `ExtractBrandKitOptions` -`interface` +`interface` — Define options for extracting brand kit data including HTML input, fetch method, timeout, and list limits ```ts interface ExtractBrandKitOptions diff --git a/docs/api/brand.md b/docs/api/brand.md index 2ad3e57..5766c01 100644 --- a/docs/api/brand.md +++ b/docs/api/brand.md @@ -16,7 +16,7 @@ Source: `src/brand/index.tsx` ### `BrandHeaderProps` -`interface` +`interface` — Define properties for a brand header including optional title, children, and CSS class name ```ts interface BrandHeaderProps @@ -32,7 +32,7 @@ interface BrandHeaderProps ### `LogoProps` -`interface` +`interface` — Define properties to customize the logo variant, size, style, and icon display options ```ts interface LogoProps diff --git a/docs/api/catalog.md b/docs/api/catalog.md index 71ad5d4..04719ec 100644 --- a/docs/api/catalog.md +++ b/docs/api/catalog.md @@ -16,7 +16,7 @@ Source: `src/catalog/index.ts` ### `CatalogModel` -`interface` +`interface` — Define the structure and capabilities of a catalog item with optional pricing and feature flags ```ts interface CatalogModel @@ -32,7 +32,7 @@ interface CatalogModel ### `ModelCatalog` -`interface` +`interface` — Define a catalog containing models with a default ID and fetch timestamp ```ts interface ModelCatalog diff --git a/docs/api/chat-routes.md b/docs/api/chat-routes.md index 92db9ce..d7b4ccd 100644 --- a/docs/api/chat-routes.md +++ b/docs/api/chat-routes.md @@ -80,7 +80,7 @@ type AttachmentReadResult ### `AttachmentTypeCheckResult` -`type` +`type` — Represent the result of checking an attachment's type with success or specific failure details ```ts type AttachmentTypeCheckResult @@ -112,7 +112,7 @@ type AttachmentWriteResult ### `buildDispatchParts` -`function` +`function` — Build dispatch parts from input by resolving mentions, paths, and applying size constraints asynchronously ```ts (input: BuildDispatchPartsInput) => Promise @@ -120,7 +120,7 @@ type AttachmentWriteResult ### `BuildDispatchPartsInput` -`interface` +`interface` — Build input parameters for dispatching chat message parts including text, attachments, mentions, and history ```ts interface BuildDispatchPartsInput @@ -136,7 +136,7 @@ interface BuildDispatchPartsInput ### `bytesToBase64` -`function` +`function` — Convert a Uint8Array of bytes into a base64-encoded string ```ts (bytes: Uint8Array) => string @@ -168,7 +168,7 @@ type ChatMentionKind ### `ChatRouteDurableProjection` -`interface` +`interface` — Resolve chat route events and materialize their durable state records ```ts interface ChatRouteDurableProjection @@ -176,7 +176,7 @@ interface ChatRouteDurableProjection ### `ChatRouteDurableProjectionLogger` -`type` +`type` — Log chat route projection messages with optional metadata for durable processing ```ts type ChatRouteDurableProjectionLogger @@ -184,7 +184,7 @@ type ChatRouteDurableProjectionLogger ### `ChatTurnAuthorization` -`type` +`type` — Resolve authorization status and context for a chat turn including tenant and user identification ```ts type ChatTurnAuthorization @@ -192,7 +192,7 @@ type ChatTurnAuthorization ### `ChatTurnAuthorizeArgs` -`interface` +`interface` — Define arguments required to authorize a chat turn based on intent and request details ```ts interface ChatTurnAuthorizeArgs @@ -224,7 +224,7 @@ interface ChatTurnHeartbeat ### `ChatTurnInputError` -`class` +`class` — Represent errors for invalid chat turn inputs with status and code properties ```ts class ChatTurnInputError @@ -248,7 +248,7 @@ interface ChatTurnLifecycle ### `ChatTurnLifecycleComplete` -`interface` +`interface` — Define the structure representing the completion state of a chat turn lifecycle with usage data ```ts interface ChatTurnLifecycleComplete @@ -256,7 +256,7 @@ interface ChatTurnLifecycleComplete ### `ChatTurnLifecycleError` -`interface` +`interface` — Represent an error occurring during a chat turn lifecycle with context and duration information ```ts interface ChatTurnLifecycleError @@ -264,7 +264,7 @@ interface ChatTurnLifecycleError ### `ChatTurnLifecycleStart` -`interface` +`interface` — Define lifecycle start event with context and timestamp for a chat turn ```ts interface ChatTurnLifecycleStart @@ -296,7 +296,7 @@ interface ChatTurnMessageStore ### `ChatTurnPartInput` -`type` +`type` — Resolve input as either a text part or a file part of a chat turn ```ts type ChatTurnPartInput @@ -304,7 +304,7 @@ type ChatTurnPartInput ### `ChatTurnProduceArgs` -`interface` +`interface` — Define the arguments required to produce a chat turn with context and messaging details ```ts interface ChatTurnProduceArgs @@ -336,7 +336,7 @@ interface ChatTurnRouteProducer ### `ChatTurnRoutes` -`interface` +`interface` — Define routes to run, replay, and list running chat turns with streaming and reconnect support ```ts interface ChatTurnRoutes @@ -368,7 +368,7 @@ interface ChatTurnUsage ### `createAttachmentUploadRoute` -`function` +`function` — Resolve an attachment upload route handler with customizable limits and validation options ```ts (options: CreateAttachmentUploadRouteOptions) => (request: Request) => Promise @@ -376,7 +376,7 @@ interface ChatTurnUsage ### `CreateAttachmentUploadRouteOptions` -`interface` +`interface` — Define options to authorize, write, and limit attachment uploads in a route ```ts interface CreateAttachmentUploadRouteOptions @@ -384,7 +384,7 @@ interface CreateAttachmentUploadRouteOptions ### `createChatTurnRoutes` -`function` +`function` — Build chat turn routes to handle and validate incoming chat requests with optional logging ```ts (options: CreateChatTurnRoutesOptions) => ChatTurnRoutes @@ -392,7 +392,7 @@ interface CreateAttachmentUploadRouteOptions ### `CreateChatTurnRoutesOptions` -`interface` +`interface` — Define options to configure chat turn routes including authorization, storage, and event buffering ```ts interface CreateChatTurnRoutesOptions @@ -400,7 +400,7 @@ interface CreateChatTurnRoutesOptions ### `createSandboxChatProducer` -`function` +`function` — Create a sandbox chat producer that manages chat turn routing with logging and interaction rendering options ```ts (options: SandboxChatProducerOptions) => ChatTurnRouteProducer @@ -408,7 +408,7 @@ interface CreateChatTurnRoutesOptions ### `createSandboxFileIndexRoute` -`function` +`function` — Resolve a sandbox file index route with authorization, caching, and configurable depth and entries limits ```ts (options: CreateSandboxFileIndexRouteOptions) => (request: Request) => Promise @@ -416,7 +416,7 @@ interface CreateChatTurnRoutesOptions ### `CreateSandboxFileIndexRouteOptions` -`interface` +`interface` — Define options to authorize and configure sandbox file index route behavior ```ts interface CreateSandboxFileIndexRouteOptions @@ -424,7 +424,7 @@ interface CreateSandboxFileIndexRouteOptions ### `createUploadRoute` -`function` +`function` — Create an upload route handler that authorizes requests and processes file uploads with size limits ```ts (options: CreateUploadRouteOptions) => (request: Request) => Promise @@ -432,7 +432,7 @@ interface CreateSandboxFileIndexRouteOptions ### `CreateUploadRouteOptions` -`interface` +`interface` — Define options to authorize uploads and configure file size limits and upload directory ```ts interface CreateUploadRouteOptions @@ -472,7 +472,7 @@ interface DetachedTurnFinal ### `DetachedTurnOptions` -`interface` +`interface` — Define options for managing and projecting a detached turn event stream in a session ```ts interface DetachedTurnOptions @@ -488,7 +488,7 @@ type DetachedTurnParts ### `DetachedTurnResult` -`interface` +`interface` — Describe the result of a detached turn including state, text, parts, usage, and optional error or cache flag ```ts interface DetachedTurnResult @@ -528,7 +528,7 @@ number ### `DispatchPartsOutcome` -`type` +`type` — Resolve the outcome of dispatching parts with success status and corresponding value or error message ```ts type DispatchPartsOutcome @@ -536,7 +536,7 @@ type DispatchPartsOutcome ### `FileIndexAuthorization` -`type` +`type` — Define authorization details and parameters for indexing a file workspace with optional caching and ignore rules ```ts type FileIndexAuthorization @@ -552,7 +552,7 @@ interface FileIndexCache ### `FileIndexReadyResponse` -`interface` +`interface` — Describe a ready file index response with workspace-relative entries and truncation status ```ts interface FileIndexReadyResponse @@ -560,7 +560,7 @@ interface FileIndexReadyResponse ### `FileIndexResponse` -`type` +`type` — Resolve a response indicating the file index is either ready or warming up ```ts type FileIndexResponse @@ -592,7 +592,7 @@ interface FileMention ### `FileMentionsToPartsOptions` -`interface` +`interface` — Define options to resolve mention paths when converting file mentions to parts ```ts interface FileMentionsToPartsOptions @@ -616,7 +616,7 @@ type FilePartPromotionOutcome ### `INLINE_PARTS_MAX_BYTES` -`const` +`const` — Define the maximum byte size allowed for inline parts in data processing ```ts 950000 @@ -688,7 +688,7 @@ number ### `ProducerErrorEvent` -`interface` +`interface` — Represent an error event emitted by a producer containing message, code, and optional details ```ts interface ProducerErrorEvent @@ -696,7 +696,7 @@ interface ProducerErrorEvent ### `ProducerNoticeEvent` -`interface` +`interface` — Define the structure for a producer notice event with type, id, kind, and text fields ```ts interface ProducerNoticeEvent @@ -704,7 +704,7 @@ interface ProducerNoticeEvent ### `ProducerPassthroughEvent` -`interface` +`interface` — Define an event carrying passthrough data with flexible properties for producer communication ```ts interface ProducerPassthroughEvent @@ -720,7 +720,7 @@ type ProducerPassthroughEventType ### `ProducerReasoningEvent` -`interface` +`interface` — Define an event representing reasoning output with a fixed type and associated text ```ts interface ProducerReasoningEvent @@ -728,7 +728,7 @@ interface ProducerReasoningEvent ### `ProducerTextEvent` -`interface` +`interface` — Represent a text event produced by a source with a fixed type and associated text content ```ts interface ProducerTextEvent @@ -736,7 +736,7 @@ interface ProducerTextEvent ### `ProducerToolCallEvent` -`interface` +`interface` — Represent an event triggered by a producer tool call with its identifier, name, and arguments ```ts interface ProducerToolCallEvent @@ -744,7 +744,7 @@ interface ProducerToolCallEvent ### `ProducerToolResultEvent` -`interface` +`interface` — Describe the structure of an event representing the result of a producer tool call ```ts interface ProducerToolResultEvent @@ -752,7 +752,7 @@ interface ProducerToolResultEvent ### `ProducerUsageEvent` -`interface` +`interface` — Describe usage event with prompt and completion token counts for a producer ```ts interface ProducerUsageEvent @@ -760,7 +760,7 @@ interface ProducerUsageEvent ### `ProducerWireEvent` -`type` +`type` — Represent events emitted by a producer during its operation for processing and handling ```ts type ProducerWireEvent @@ -776,7 +776,7 @@ number ### `promoteAgentFilePart` -`function` +`function` — Promote a part of an agent file with optional byte limits and MIME type detection ```ts (options: PromoteAgentFilePartOptions) => Promise @@ -784,7 +784,7 @@ number ### `PromoteAgentFilePartOptions` -`interface` +`interface` — Define options for promoting a part of an agent file within a specific session and scope ```ts interface PromoteAgentFilePartOptions @@ -792,7 +792,7 @@ interface PromoteAgentFilePartOptions ### `PromoteFilePartResult` -`type` +`type` — Resolve the result of promoting a file part with success status and relevant data or error details ```ts type PromoteFilePartResult @@ -800,7 +800,7 @@ type PromoteFilePartResult ### `PromptInputPart` -`type` +`type` — Extract a single element type from the array parameter of SandboxInstance's streamPrompt method ```ts type PromptInputPart @@ -808,7 +808,7 @@ type PromptInputPart ### `promptPartsByteSize` -`function` +`function` — Calculate the total byte size of an array of chat turn parts ```ts (parts: ChatTurnPartInput[]) => number @@ -816,7 +816,7 @@ type PromptInputPart ### `RawAgentFilePart` -`interface` +`interface` — Define the structure for a raw file part with optional metadata and media type information ```ts interface RawAgentFilePart @@ -832,7 +832,7 @@ type ReadAttachmentFn ### `ReadSandboxMentionFn` -`type` +`type` — Resolve sandbox mention details by reading from a specified path with optional byte reading ```ts type ReadSandboxMentionFn @@ -848,7 +848,7 @@ type ReadSandboxMentionFn ### `ReconcileStaleTurnLockOptions` -`interface` +`interface` — Resolve options for probing and releasing stale TURN locks based on lock start time and sandbox state ```ts interface ReconcileStaleTurnLockOptions @@ -856,7 +856,7 @@ interface ReconcileStaleTurnLockOptions ### `ReconcileStaleTurnLockResult` -`interface` +`interface` — Describe the outcome of reconciling a stale turn lock including release status and diagnostics ```ts interface ReconcileStaleTurnLockResult @@ -872,7 +872,7 @@ interface ReconcileStaleTurnLockResult ### `ResolveChatAttachmentsOptions` -`interface` +`interface` — Define options to resolve and validate chat attachments with size, count, and path constraints ```ts interface ResolveChatAttachmentsOptions @@ -880,7 +880,7 @@ interface ResolveChatAttachmentsOptions ### `ResolveChatAttachmentsResult` -`type` +`type` — Resolve the result of chat attachment processing with success status and corresponding data or error ```ts type ResolveChatAttachmentsResult @@ -896,7 +896,7 @@ type ResolveChatAttachmentsResult ### `SandboxChatProducerOptions` -`interface` +`interface` — Define options for producing sandbox chat events with rendering and interaction controls ```ts interface SandboxChatProducerOptions @@ -912,7 +912,7 @@ interface SandboxFileTreeSource ### `SandboxMentionPathCheck` -`type` +`type` — Represent the result of a sandbox mention path check indicating success or failure with an error message ```ts type SandboxMentionPathCheck @@ -1016,7 +1016,7 @@ number ### `UploadAuthorization` -`type` +`type` — Resolve upload authorization status and provide upload destination or error response ```ts type UploadAuthorization diff --git a/docs/api/chat-store.md b/docs/api/chat-store.md index 79cdb9e..6e5abc1 100644 --- a/docs/api/chat-store.md +++ b/docs/api/chat-store.md @@ -8,7 +8,7 @@ Source: `src/chat-store/index.ts` ### `AppendMessageInput` -`interface` +`interface` — Define input parameters for appending a message to a chat thread with optional metadata ```ts interface AppendMessageInput @@ -64,7 +64,7 @@ interface AppendMessageInput ### `BulkDeleteThreadsInput` -`interface` +`interface` — Define input for bulk deleting threads with access checks per workspace ```ts interface BulkDeleteThreadsInput @@ -104,7 +104,7 @@ interface ChatFilePart ### `ChatImagePart` -`interface` +`interface` — Define properties for an image part within a chat message including optional metadata fields ```ts interface ChatImagePart @@ -136,7 +136,7 @@ interface ChatMentionPart ### `ChatMessagePart` -`type` +`type` — Represent parts of a chat message including text, reasoning, tools, files, images, subtasks, steps, interactions, notices, plans, and mentions ```ts type ChatMessagePart @@ -144,7 +144,7 @@ type ChatMessagePart ### `ChatMessageRow` -`type` +`type` — Resolve the selected structure of a chat message row from the messages table ```ts type ChatMessageRow @@ -176,7 +176,7 @@ interface ChatPartTime ### `ChatPlanPart` -`type` +`type` — Resolve a chat plan part by aliasing it to the persisted chat plan part type ```ts type ChatPlanPart @@ -184,7 +184,7 @@ type ChatPlanPart ### `ChatReasoningPart` -`interface` +`interface` — Define a reasoning part of a chat with text content and optional metadata fields ```ts interface ChatReasoningPart @@ -192,7 +192,7 @@ interface ChatReasoningPart ### `ChatStepFinishPart` -`interface` +`interface` — Define a chat step finish part indicating completion with optional reason, tokens, and cost ```ts interface ChatStepFinishPart @@ -208,7 +208,7 @@ interface ChatStepStartPart ### `ChatStore` -`interface` +`interface` — Manage chat threads and messages with operations for listing, creating, updating, and deleting data ```ts interface ChatStore @@ -224,7 +224,7 @@ class ChatStoreInputError ### `ChatSubtaskPart` -`interface` +`interface` — Define a subtask part of a chat with prompt, description, agent, and optional identifier ```ts interface ChatSubtaskPart @@ -248,7 +248,7 @@ interface ChatTextPart ### `ChatThreadRow` -`type` +`type` — Resolve the selected fields of a chat thread row from the chat threads table ```ts type ChatThreadRow @@ -256,7 +256,7 @@ type ChatThreadRow ### `ChatToolPart` -`interface` +`interface` — Define a chat component representing a tool with its state and optional call identifier ```ts interface ChatToolPart @@ -264,7 +264,7 @@ interface ChatToolPart ### `ChatToolState` -`interface` +`interface` — Describe the current state and data of a chat tool including status, input, output, and metadata ```ts interface ChatToolState @@ -288,7 +288,7 @@ interface ChatUsageTokens ### `createChatStore` -`function` +`function` — Create a chat store managing threads and messages based on the provided database and tables ```ts (db: ChatDatabase, tables: TTables) => ChatStore = {}, TMessageExtras extends Record part is ChatInteractionPart @@ -360,7 +360,7 @@ interface CreateThreadInput ### `isChatPlanPart` -`function` +`function` — Resolve whether a chat message part is a persisted chat plan part ```ts (part: ChatMessagePart) => part is ChatPlanPersistedPart @@ -368,7 +368,7 @@ interface CreateThreadInput ### `isChatStepFinishPart` -`function` +`function` — Determine if a chat message part represents the completion of a chat step ```ts (part: ChatMessagePart) => part is ChatStepFinishPart @@ -376,7 +376,7 @@ interface CreateThreadInput ### `isChatTextPart` -`function` +`function` — Resolve whether a chat message part is a text part based on its type property ```ts (part: ChatMessagePart) => part is ChatTextPart @@ -384,7 +384,7 @@ interface CreateThreadInput ### `isChatToolPart` -`function` +`function` — Resolve whether a ChatMessagePart is specifically a ChatToolPart based on its type property ```ts (part: ChatMessagePart) => part is ChatToolPart @@ -392,7 +392,7 @@ interface CreateThreadInput ### `ListMessagesOptions` -`interface` +`interface` — Define options to configure message listing with optional limit and offset parameters ```ts interface ListMessagesOptions @@ -400,7 +400,7 @@ interface ListMessagesOptions ### `ListThreadsInput` -`interface` +`interface` — Define input parameters for listing threads within a workspace with pagination options ```ts interface ListThreadsInput @@ -408,7 +408,7 @@ interface ListThreadsInput ### `ListThreadsResult` -`interface` +`interface` — Represent a paginated collection of chat threads with total count and pagination details ```ts interface ListThreadsResult @@ -432,7 +432,7 @@ interface ListThreadsResult ### `NewChatMessageRow` -`type` +`type` — Resolve the type for inserting a new chat message row into the messages table ```ts type NewChatMessageRow @@ -440,7 +440,7 @@ type NewChatMessageRow ### `NewChatThreadRow` -`type` +`type` — Resolve the type for inserting a new chat thread row into the threads table ```ts type NewChatThreadRow diff --git a/docs/api/config.md b/docs/api/config.md index ee5634d..a67d00e 100644 --- a/docs/api/config.md +++ b/docs/api/config.md @@ -80,7 +80,7 @@ interface KnowledgeLoopConfig ### `KnowledgeRequirementSpec` -`interface` +`interface` — Define the criteria and conditions required to satisfy a specific knowledge requirement ```ts interface KnowledgeRequirementSpec diff --git a/docs/api/design-canvas-drizzle.md b/docs/api/design-canvas-drizzle.md index b0b83ab..0831b51 100644 --- a/docs/api/design-canvas-drizzle.md +++ b/docs/api/design-canvas-drizzle.md @@ -8,7 +8,7 @@ Source: `src/design-canvas/drizzle.ts` ### `createDesignCanvasTables` -`function` +`function` — Build SQLite tables for design documents with workspace and user references ```ts (opts: CreateDesignCanvasTablesOptions) => { designDocuments: SQLiteTableWithColumns<{ name: "design_document"; schema:… @@ -16,7 +16,7 @@ Source: `src/design-canvas/drizzle.ts` ### `CreateDesignCanvasTablesOptions` -`interface` +`interface` — Define options for creating design canvas tables including workspace and user table configurations ```ts interface CreateDesignCanvasTablesOptions @@ -24,7 +24,7 @@ interface CreateDesignCanvasTablesOptions ### `createDrizzleSceneStore` -`function` +`function` — Create a scene store configured with database tables and scoped to a specific document and workspace ```ts (options: CreateDrizzleSceneStoreOptions) => SceneStore @@ -32,7 +32,7 @@ interface CreateDesignCanvasTablesOptions ### `CreateDrizzleSceneStoreOptions` -`interface` +`interface` — Define options for creating a Drizzle scene store including database, tables, and scope ```ts interface CreateDrizzleSceneStoreOptions @@ -56,7 +56,7 @@ type DesignCanvasParentTable ### `DesignCanvasTables` -`type` +`type` — Resolve the structure and data of design canvas tables for rendering and manipulation ```ts type DesignCanvasTables @@ -64,7 +64,7 @@ type DesignCanvasTables ### `DesignDecisionRow` -`type` +`type` — Resolve a design decision row from the design decisions table selection ```ts type DesignDecisionRow @@ -72,7 +72,7 @@ type DesignDecisionRow ### `DesignDocumentRow` -`type` +`type` — Resolve the selected structure of a design document row from design canvas tables ```ts type DesignDocumentRow @@ -80,7 +80,7 @@ type DesignDocumentRow ### `DesignExportRow` -`type` +`type` — Resolve the selected fields of designExports from DesignCanvasTables ```ts type DesignExportRow diff --git a/docs/api/design-canvas-react-engine.md b/docs/api/design-canvas-react-engine.md index 27efb6d..3b46a70 100644 --- a/docs/api/design-canvas-react-engine.md +++ b/docs/api/design-canvas-react-engine.md @@ -8,7 +8,7 @@ Source: `src/design-canvas-react/engine.ts` ### `addElementCommand` -`function` +`function` — Create a command to add an element to a scene with optional positioning and grouping ```ts (input: AddElementInput) => SceneCommand @@ -16,7 +16,7 @@ Source: `src/design-canvas-react/engine.ts` ### `AddElementInput` -`interface` +`interface` — Define input parameters for adding a scene element with optional index and parent group ID ```ts interface AddElementInput @@ -24,7 +24,7 @@ interface AddElementInput ### `addPageCommand` -`function` +`function` — Create a command to add a page with optional settings and index in the scene ```ts (input: AddPageInput) => SceneCommand @@ -32,7 +32,7 @@ interface AddElementInput ### `AddPageInput` -`interface` +`interface` — Define input parameters for adding a new page with optional settings and position index ```ts interface AddPageInput @@ -40,7 +40,7 @@ interface AddPageInput ### `ApplySceneResult` -`interface` +`interface` — Resolve the result of applying a scene update including revision and optional normalized document ```ts interface ApplySceneResult @@ -48,7 +48,7 @@ interface ApplySceneResult ### `bindSlotCommand` -`function` +`function` — Bind a slot to an element within a page and generate the corresponding scene command ```ts (input: BindSlotInput) => SceneCommand @@ -56,7 +56,7 @@ interface ApplySceneResult ### `BindSlotInput` -`interface` +`interface` — Define input parameters for binding a slot within a scene document element ```ts interface BindSlotInput @@ -96,7 +96,7 @@ interface BindSlotInput ### `createSceneCommandStack` -`function` +`function` — Create a command stack for scene editing with reapply capabilities based on the given document and page ID ```ts (document: SceneDocument, activePageId: string) => SceneCommandStackWithReapply @@ -104,7 +104,7 @@ interface BindSlotInput ### `createSnapEngine` -`function` +`function` — Build a SnapEngine instance to manage snapping targets and behavior within an editor scene ```ts () => SnapEngine @@ -112,7 +112,7 @@ interface BindSlotInput ### `createZoomPanMath` -`function` +`function` — Create zoom and pan math utilities enforcing valid zoom range constraints ```ts (config: ZoomPanConfig) => ZoomPanMath @@ -128,7 +128,7 @@ readonly InsertTemplate[] ### `deleteElementCommand` -`function` +`function` — Resolve a command to delete an element from a specified page in the document ```ts (input: DeleteElementInput) => SceneCommand @@ -136,7 +136,7 @@ readonly InsertTemplate[] ### `DeleteElementInput` -`interface` +`interface` — Define input parameters required to delete an element from a specific page in a document ```ts interface DeleteElementInput @@ -144,7 +144,7 @@ interface DeleteElementInput ### `deletePageCommand` -`function` +`function` — Delete a page from a document ensuring it is not the last remaining page ```ts (input: DeletePageInput) => SceneCommand @@ -152,7 +152,7 @@ interface DeleteElementInput ### `DeletePageInput` -`interface` +`interface` — Define input parameters required to delete a page from a scene document ```ts interface DeletePageInput @@ -168,7 +168,7 @@ type DesignCanvasMode ### `DesignCanvasProps` -`interface` +`interface` — Define properties and callbacks for configuring and controlling the design canvas editor ```ts interface DesignCanvasProps @@ -192,7 +192,7 @@ NudgeDelta ### `duplicatePageCommand` -`function` +`function` — Create a command to duplicate a page and prepare its deletion operation in the scene ```ts (input: DuplicatePageInput) => SceneCommand @@ -200,7 +200,7 @@ NudgeDelta ### `DuplicatePageInput` -`interface` +`interface` — Define input parameters required to duplicate a page within a scene document ```ts interface DuplicatePageInput @@ -208,7 +208,7 @@ interface DuplicatePageInput ### `EditorSceneState` -`interface` +`interface` — Define the state of the editor scene including document, view settings, and selection details ```ts interface EditorSceneState @@ -216,7 +216,7 @@ interface EditorSceneState ### `ExportCropRect` -`interface` +`interface` — Define crop rectangle coordinates and dimensions for exporting content within page bounds ```ts interface ExportCropRect @@ -256,7 +256,7 @@ interface ExportViewSnapshot ### `groupElementsCommand` -`function` +`function` — Create a command to group multiple elements into a single group within a scene ```ts (input: GroupElementsInput) => SceneCommand @@ -264,7 +264,7 @@ interface ExportViewSnapshot ### `GroupElementsInput` -`interface` +`interface` — Define input parameters for grouping elements within a scene document on a specific page ```ts interface GroupElementsInput @@ -328,7 +328,7 @@ interface InsertTemplate ### `MarqueeSelectOptions` -`interface` +`interface` — Define options to configure marquee selection behavior including containment requirements ```ts interface MarqueeSelectOptions @@ -352,7 +352,7 @@ interface MarqueeSelectOptions ### `multiSetAttrsCommand` -`function` +`function` — Build a scene command to set multiple attributes on elements across pages ```ts (entries: MultiSetAttrsEntry[]) => SceneCommand @@ -360,7 +360,7 @@ interface MarqueeSelectOptions ### `MultiSetAttrsEntry` -`interface` +`interface` — Define an entry linking page and element IDs with current and prior scene attribute patches ```ts interface MultiSetAttrsEntry @@ -376,7 +376,7 @@ interface MultiSetAttrsEntry ### `NudgeDelta` -`interface` +`interface` — Represent horizontal and vertical displacement values for nudging elements ```ts interface NudgeDelta @@ -384,7 +384,7 @@ interface NudgeDelta ### `reorderElementCommand` -`function` +`function` — Resolve a command to reorder an element within a scene by moving it to a specified index ```ts (input: ReorderElementInput) => SceneCommand @@ -392,7 +392,7 @@ interface NudgeDelta ### `ReorderElementInput` -`interface` +`interface` — Define input parameters to reorder an element within a page ```ts interface ReorderElementInput @@ -400,7 +400,7 @@ interface ReorderElementInput ### `reorderPageCommand` -`function` +`function` — Create a command to reorder a page to a specified index within a scene ```ts (input: ReorderPageInput) => SceneCommand @@ -408,7 +408,7 @@ interface ReorderElementInput ### `ReorderPageInput` -`interface` +`interface` — Define input parameters to reorder a page by specifying its ID and target index ```ts interface ReorderPageInput @@ -416,7 +416,7 @@ interface ReorderPageInput ### `ResolvedExportParams` -`interface` +`interface` — Define parameters required to resolve export settings including crop, pixel ratio, type, and quality ```ts interface ResolvedExportParams @@ -448,7 +448,7 @@ interface ResolvedExportParams ### `SceneCommand` -`interface` +`interface` — Define a command with execution, undo, and operation methods for scene editing and persistence ```ts interface SceneCommand @@ -456,7 +456,7 @@ interface SceneCommand ### `SceneCommandStack` -`interface` +`interface` — Manage and track scene commands with undo, redo, and state subscription capabilities ```ts interface SceneCommandStack @@ -472,7 +472,7 @@ interface SceneCommandStackWithReapply ### `setAttrsCommand` -`function` +`function` — Create a command to set attributes on a scene element with undo capability ```ts (input: SetAttrsInput) => SceneCommand @@ -480,7 +480,7 @@ interface SceneCommandStackWithReapply ### `SetAttrsInput` -`interface` +`interface` — Define input parameters for setting element attributes within a specific page context ```ts interface SetAttrsInput @@ -488,7 +488,7 @@ interface SetAttrsInput ### `setDocumentTitleCommand` -`function` +`function` — Resolve a command to rename a document title with undo and redo operations ```ts (input: SetDocumentTitleInput) => SceneCommand @@ -496,7 +496,7 @@ interface SetAttrsInput ### `SetDocumentTitleInput` -`interface` +`interface` — Define input parameters for setting the title of a scene document ```ts interface SetDocumentTitleInput @@ -504,7 +504,7 @@ interface SetDocumentTitleInput ### `setPageGuidesCommand` -`function` +`function` — Create a command to update page guides with undo support ```ts (input: SetPageGuidesInput) => SceneCommand @@ -512,7 +512,7 @@ interface SetDocumentTitleInput ### `SetPageGuidesInput` -`interface` +`interface` — Define input parameters for setting guides on a specific page within a document ```ts interface SetPageGuidesInput @@ -520,7 +520,7 @@ interface SetPageGuidesInput ### `setPagePropsCommand` -`function` +`function` — Build a command to update page properties based on the provided input ```ts (input: SetPagePropsInput) => SceneCommand @@ -528,7 +528,7 @@ interface SetPageGuidesInput ### `SetPagePropsInput` -`interface` +`interface` — Define input parameters for setting properties on a specific page within a scene document ```ts interface SetPagePropsInput @@ -536,7 +536,7 @@ interface SetPagePropsInput ### `SnapEngine` -`interface` +`interface` — Resolve snapping targets and apply snapping logic to moving elements within the editor scene ```ts interface SnapEngine @@ -544,7 +544,7 @@ interface SnapEngine ### `SnapResult` -`interface` +`interface` — Define the result of a snap operation including coordinates and active snap lines ```ts interface SnapResult @@ -552,7 +552,7 @@ interface SnapResult ### `SnapTarget` -`interface` +`interface` — Define a target position and kind for snapping elements on a page ```ts interface SnapTarget @@ -560,7 +560,7 @@ interface SnapTarget ### `SnapTargetKind` -`type` +`type` — Define snap target categories for aligning elements within a layout system ```ts type SnapTargetKind @@ -568,7 +568,7 @@ type SnapTargetKind ### `SnapTargets` -`interface` +`interface` — Define vertical and horizontal collections of snap targets for alignment purposes ```ts interface SnapTargets @@ -576,7 +576,7 @@ interface SnapTargets ### `ungroupElementCommand` -`function` +`function` — Resolve a command to ungroup a group element into its child elements within a scene ```ts (input: UngroupElementInput) => SceneCommand @@ -584,7 +584,7 @@ interface SnapTargets ### `UngroupElementInput` -`interface` +`interface` — Define input parameters required to ungroup elements within a specific page and group ```ts interface UngroupElementInput @@ -592,7 +592,7 @@ interface UngroupElementInput ### `ZoomPanConfig` -`interface` +`interface` — Define configuration options for minimum and maximum zoom levels in a zoom-pan interface ```ts interface ZoomPanConfig @@ -600,7 +600,7 @@ interface ZoomPanConfig ### `ZoomPanMath` -`interface` +`interface` — Define methods and properties to calculate zoom and pan transformations between document and screen coordinates ```ts interface ZoomPanMath diff --git a/docs/api/design-canvas-react-lazy.md b/docs/api/design-canvas-react-lazy.md index 0afbefd..94d90ec 100644 --- a/docs/api/design-canvas-react-lazy.md +++ b/docs/api/design-canvas-react-lazy.md @@ -32,7 +32,7 @@ LazyExoticComponent<(props: DesignCanvasProps) => Element> ### `DesignCanvasProps` -`interface` +`interface` — Define properties and callbacks for configuring and controlling the design canvas editor ```ts interface DesignCanvasProps diff --git a/docs/api/design-canvas-react.md b/docs/api/design-canvas-react.md index 3e47d11..4fb759c 100644 --- a/docs/api/design-canvas-react.md +++ b/docs/api/design-canvas-react.md @@ -8,7 +8,7 @@ Source: `src/design-canvas-react/index.ts` ### `addElementCommand` -`function` +`function` — Create a command to add an element to a scene with optional positioning and grouping ```ts (input: AddElementInput) => SceneCommand @@ -16,7 +16,7 @@ Source: `src/design-canvas-react/index.ts` ### `AddElementInput` -`interface` +`interface` — Define input parameters for adding a scene element with optional index and parent group ID ```ts interface AddElementInput @@ -24,7 +24,7 @@ interface AddElementInput ### `addPageCommand` -`function` +`function` — Create a command to add a page with optional settings and index in the scene ```ts (input: AddPageInput) => SceneCommand @@ -32,7 +32,7 @@ interface AddElementInput ### `AddPageInput` -`interface` +`interface` — Define input parameters for adding a new page with optional settings and position index ```ts interface AddPageInput @@ -40,7 +40,7 @@ interface AddPageInput ### `ApplySceneResult` -`interface` +`interface` — Resolve the result of applying a scene update including revision and optional normalized document ```ts interface ApplySceneResult @@ -48,7 +48,7 @@ interface ApplySceneResult ### `BakedNodeAttrs` -`interface` +`interface` — Define baked node attributes including position, size, and rotation with collapsed scale ```ts interface BakedNodeAttrs @@ -80,7 +80,7 @@ interface BakedNodeAttrs ### `bindSlotCommand` -`function` +`function` — Bind a slot to an element within a page and generate the corresponding scene command ```ts (input: BindSlotInput) => SceneCommand @@ -88,7 +88,7 @@ interface BakedNodeAttrs ### `BindSlotInput` -`interface` +`interface` — Define input parameters for binding a slot within a scene document element ```ts interface BindSlotInput @@ -200,7 +200,7 @@ interface CanvasInsertPanelProps ### `createSceneCommandStack` -`function` +`function` — Create a command stack for scene editing with reapply capabilities based on the given document and page ID ```ts (document: SceneDocument, activePageId: string) => SceneCommandStackWithReapply @@ -208,7 +208,7 @@ interface CanvasInsertPanelProps ### `createSnapEngine` -`function` +`function` — Build a SnapEngine instance to manage snapping targets and behavior within an editor scene ```ts () => SnapEngine @@ -216,7 +216,7 @@ interface CanvasInsertPanelProps ### `createZoomPanMath` -`function` +`function` — Create zoom and pan math utilities enforcing valid zoom range constraints ```ts (config: ZoomPanConfig) => ZoomPanMath @@ -232,7 +232,7 @@ readonly InsertTemplate[] ### `deleteElementCommand` -`function` +`function` — Resolve a command to delete an element from a specified page in the document ```ts (input: DeleteElementInput) => SceneCommand @@ -240,7 +240,7 @@ readonly InsertTemplate[] ### `DeleteElementInput` -`interface` +`interface` — Define input parameters required to delete an element from a specific page in a document ```ts interface DeleteElementInput @@ -248,7 +248,7 @@ interface DeleteElementInput ### `deletePageCommand` -`function` +`function` — Delete a page from a document ensuring it is not the last remaining page ```ts (input: DeletePageInput) => SceneCommand @@ -256,7 +256,7 @@ interface DeleteElementInput ### `DeletePageInput` -`interface` +`interface` — Define input parameters required to delete a page from a scene document ```ts interface DeletePageInput @@ -312,7 +312,7 @@ type DesignCanvasMode ### `DesignCanvasProps` -`interface` +`interface` — Define properties and callbacks for configuring and controlling the design canvas editor ```ts interface DesignCanvasProps @@ -344,7 +344,7 @@ NudgeDelta ### `duplicatePageCommand` -`function` +`function` — Create a command to duplicate a page and prepare its deletion operation in the scene ```ts (input: DuplicatePageInput) => SceneCommand @@ -352,7 +352,7 @@ NudgeDelta ### `DuplicatePageInput` -`interface` +`interface` — Define input parameters required to duplicate a page within a scene document ```ts interface DuplicatePageInput @@ -360,7 +360,7 @@ interface DuplicatePageInput ### `EditorSceneState` -`interface` +`interface` — Define the state of the editor scene including document, view settings, and selection details ```ts interface EditorSceneState @@ -400,7 +400,7 @@ interface ExportControlProps ### `ExportCropRect` -`interface` +`interface` — Define crop rectangle coordinates and dimensions for exporting content within page bounds ```ts interface ExportCropRect @@ -424,7 +424,7 @@ interface ExportCropRect ### `ExportPageDataUrlOptions` -`interface` +`interface` — Define options to export a page as a data URL with format, pixel ratio, bleed, and preset settings ```ts interface ExportPageDataUrlOptions @@ -496,7 +496,7 @@ interface GridLayerProps ### `groupElementsCommand` -`function` +`function` — Create a command to group multiple elements into a single group within a scene ```ts (input: GroupElementsInput) => SceneCommand @@ -504,7 +504,7 @@ interface GridLayerProps ### `GroupElementsInput` -`interface` +`interface` — Define input parameters for grouping elements within a scene document on a specific page ```ts interface GroupElementsInput @@ -584,7 +584,7 @@ interface InsertTemplate ### `LayerRow` -`interface` +`interface` — Describe a layer row with its element, depth, grouping, ownership, and parent group details ```ts interface LayerRow @@ -624,7 +624,7 @@ interface LayersPanelProps ### `MarqueeSelectOptions` -`interface` +`interface` — Define options to configure marquee selection behavior including containment requirements ```ts interface MarqueeSelectOptions @@ -648,7 +648,7 @@ interface MarqueeSelectOptions ### `multiSetAttrsCommand` -`function` +`function` — Build a scene command to set multiple attributes on elements across pages ```ts (entries: MultiSetAttrsEntry[]) => SceneCommand @@ -656,7 +656,7 @@ interface MarqueeSelectOptions ### `MultiSetAttrsEntry` -`interface` +`interface` — Define an entry linking page and element IDs with current and prior scene attribute patches ```ts interface MultiSetAttrsEntry @@ -672,7 +672,7 @@ interface MultiSetAttrsEntry ### `NudgeDelta` -`interface` +`interface` — Represent horizontal and vertical displacement values for nudging elements ```ts interface NudgeDelta @@ -696,7 +696,7 @@ interface PagesStripProps ### `reorderElementCommand` -`function` +`function` — Resolve a command to reorder an element within a scene by moving it to a specified index ```ts (input: ReorderElementInput) => SceneCommand @@ -704,7 +704,7 @@ interface PagesStripProps ### `ReorderElementInput` -`interface` +`interface` — Define input parameters to reorder an element within a page ```ts interface ReorderElementInput @@ -712,7 +712,7 @@ interface ReorderElementInput ### `reorderPageCommand` -`function` +`function` — Create a command to reorder a page to a specified index within a scene ```ts (input: ReorderPageInput) => SceneCommand @@ -720,7 +720,7 @@ interface ReorderElementInput ### `ReorderPageInput` -`interface` +`interface` — Define input parameters to reorder a page by specifying its ID and target index ```ts interface ReorderPageInput @@ -728,7 +728,7 @@ interface ReorderPageInput ### `ResolvedExportParams` -`interface` +`interface` — Define parameters required to resolve export settings including crop, pixel ratio, type, and quality ```ts interface ResolvedExportParams @@ -760,7 +760,7 @@ interface RulersProps ### `RulerTick` -`interface` +`interface` — Define a ruler tick with a position and optional label for measurement markings ```ts interface RulerTick @@ -784,7 +784,7 @@ interface RulerTick ### `SceneCommand` -`interface` +`interface` — Define a command with execution, undo, and operation methods for scene editing and persistence ```ts interface SceneCommand @@ -792,7 +792,7 @@ interface SceneCommand ### `SceneCommandStack` -`interface` +`interface` — Manage and track scene commands with undo, redo, and state subscription capabilities ```ts interface SceneCommandStack @@ -832,7 +832,7 @@ interface SelectionLayerProps ### `setAttrsCommand` -`function` +`function` — Create a command to set attributes on a scene element with undo capability ```ts (input: SetAttrsInput) => SceneCommand @@ -840,7 +840,7 @@ interface SelectionLayerProps ### `SetAttrsInput` -`interface` +`interface` — Define input parameters for setting element attributes within a specific page context ```ts interface SetAttrsInput @@ -848,7 +848,7 @@ interface SetAttrsInput ### `setDocumentTitleCommand` -`function` +`function` — Resolve a command to rename a document title with undo and redo operations ```ts (input: SetDocumentTitleInput) => SceneCommand @@ -856,7 +856,7 @@ interface SetAttrsInput ### `SetDocumentTitleInput` -`interface` +`interface` — Define input parameters for setting the title of a scene document ```ts interface SetDocumentTitleInput @@ -864,7 +864,7 @@ interface SetDocumentTitleInput ### `setPageGuidesCommand` -`function` +`function` — Create a command to update page guides with undo support ```ts (input: SetPageGuidesInput) => SceneCommand @@ -872,7 +872,7 @@ interface SetDocumentTitleInput ### `SetPageGuidesInput` -`interface` +`interface` — Define input parameters for setting guides on a specific page within a document ```ts interface SetPageGuidesInput @@ -880,7 +880,7 @@ interface SetPageGuidesInput ### `setPagePropsCommand` -`function` +`function` — Build a command to update page properties based on the provided input ```ts (input: SetPagePropsInput) => SceneCommand @@ -888,7 +888,7 @@ interface SetPageGuidesInput ### `SetPagePropsInput` -`interface` +`interface` — Define input parameters for setting properties on a specific page within a scene document ```ts interface SetPagePropsInput @@ -896,7 +896,7 @@ interface SetPagePropsInput ### `SnapEngine` -`interface` +`interface` — Resolve snapping targets and apply snapping logic to moving elements within the editor scene ```ts interface SnapEngine @@ -904,7 +904,7 @@ interface SnapEngine ### `SnapResult` -`interface` +`interface` — Define the result of a snap operation including coordinates and active snap lines ```ts interface SnapResult @@ -912,7 +912,7 @@ interface SnapResult ### `SnapTarget` -`interface` +`interface` — Define a target position and kind for snapping elements on a page ```ts interface SnapTarget @@ -920,7 +920,7 @@ interface SnapTarget ### `SnapTargetKind` -`type` +`type` — Define snap target categories for aligning elements within a layout system ```ts type SnapTargetKind @@ -928,7 +928,7 @@ type SnapTargetKind ### `SnapTargets` -`interface` +`interface` — Define vertical and horizontal collections of snap targets for alignment purposes ```ts interface SnapTargets @@ -936,7 +936,7 @@ interface SnapTargets ### `TickStep` -`interface` +`interface` — Define spacing and visibility rules for major and minor ticks in a coordinate system ```ts interface TickStep @@ -968,7 +968,7 @@ interface TransformerNode ### `ungroupElementCommand` -`function` +`function` — Resolve a command to ungroup a group element into its child elements within a scene ```ts (input: UngroupElementInput) => SceneCommand @@ -976,7 +976,7 @@ interface TransformerNode ### `UngroupElementInput` -`interface` +`interface` — Define input parameters required to ungroup elements within a specific page and group ```ts interface UngroupElementInput @@ -1024,7 +1024,7 @@ interface ZoomControlsProps ### `ZoomPanConfig` -`interface` +`interface` — Define configuration options for minimum and maximum zoom levels in a zoom-pan interface ```ts interface ZoomPanConfig @@ -1032,7 +1032,7 @@ interface ZoomPanConfig ### `ZoomPanMath` -`interface` +`interface` — Define methods and properties to calculate zoom and pan transformations between document and screen coordinates ```ts interface ZoomPanMath diff --git a/docs/api/design-canvas.md b/docs/api/design-canvas.md index ba6e097..22f2531 100644 --- a/docs/api/design-canvas.md +++ b/docs/api/design-canvas.md @@ -8,7 +8,7 @@ Source: `src/design-canvas/index.ts` ### `AddElementOperation` -`interface` +`interface` — Define an operation to add a scene element to a page with optional index and parent group ```ts interface AddElementOperation @@ -16,7 +16,7 @@ interface AddElementOperation ### `AddPageOperation` -`interface` +`interface` — Define an operation to add a new page with an optional position and caller-minted page ID ```ts interface AddPageOperation @@ -56,7 +56,7 @@ interface ApplyDataOperation ### `ApplySceneOptions` -`interface` +`interface` — Resolve element ID conflicts by providing fresh unique identifiers during scene application ```ts interface ApplySceneOptions @@ -64,7 +64,7 @@ interface ApplySceneOptions ### `assertColor` -`function` +`function` — Validate that a string is a hex, rgb(a), or 'transparent' color and throw an error if not ```ts (value: string, label: string) => void @@ -72,7 +72,7 @@ interface ApplySceneOptions ### `assertFinite` -`function` +`function` — Assert that a value is a finite number and throw an error with a label if not ```ts (value: number, label: string) => void @@ -80,7 +80,7 @@ interface ApplySceneOptions ### `assertPositiveFinite` -`function` +`function` — Assert that a value is a positive finite number and throw an error with a label if not ```ts (value: number, label: string) => void @@ -96,7 +96,7 @@ interface ApplySceneOptions ### `BindSlotOperation` -`interface` +`interface` — Define an operation to bind or unbind a unique slot to an element on a specific page ```ts interface BindSlotOperation @@ -120,7 +120,7 @@ interface BindSlotOperation ### `Bounds` -`interface` +`interface` — Define rectangular boundaries with position and size properties ```ts interface Bounds @@ -128,7 +128,7 @@ interface Bounds ### `boundsIntersect` -`function` +`function` — Determine if two rectangular bounds overlap or intersect each other ```ts (a: Bounds, b: Bounds) => boolean @@ -144,7 +144,7 @@ interface Bounds ### `BuildDesignCanvasMcpServerEntryOptions` -`type` +`type` — Build scoped MCP server entry options for the design canvas environment ```ts type BuildDesignCanvasMcpServerEntryOptions @@ -152,7 +152,7 @@ type BuildDesignCanvasMcpServerEntryOptions ### `CANVAS_ELEMENT_KINDS` -`const` +`const` — Provide a readonly array of string identifiers representing canvas element kinds ```ts readonly string[] @@ -160,7 +160,7 @@ readonly string[] ### `CANVAS_MCP_TOOL_NAMES` -`const` +`const` — Extract names of all tools from the CANVAS_MCP_TOOLS array ```ts string[] @@ -168,7 +168,7 @@ string[] ### `CANVAS_MCP_TOOLS` -`const` +`const` — Provide a collection of MCP tool definitions for manipulating and querying the design canvas environment ```ts McpToolDefinition[] @@ -184,7 +184,7 @@ readonly ChannelPreset[] ### `ChannelPreset` -`interface` +`interface` — Define a preset configuration for a channel including its id, label, width, and height ```ts interface ChannelPreset @@ -192,7 +192,7 @@ interface ChannelPreset ### `ChannelPresetId` -`type` +`type` — Resolve a valid channel preset identifier from the predefined channel presets array ```ts type ChannelPresetId @@ -200,7 +200,7 @@ type ChannelPresetId ### `ChannelScaleResult` -`interface` +`interface` — Define the pixel ratio and horizontal offset for scaling a Konva stage to a channel preset size ```ts interface ChannelScaleResult @@ -216,7 +216,7 @@ interface ChannelScaleResult ### `createDesignCanvasMcpHandler` -`function` +`function` — Create a request handler for the design canvas MCP tool with specified options ```ts (opts: CreateDesignCanvasMcpHandlerOptions) => (request: Request) => Promise @@ -224,7 +224,7 @@ interface ChannelScaleResult ### `CreateDesignCanvasMcpHandlerOptions` -`interface` +`interface` — Define options for creating a design canvas MCP handler including store, ID minting, and optional server info ```ts interface CreateDesignCanvasMcpHandlerOptions @@ -232,7 +232,7 @@ interface CreateDesignCanvasMcpHandlerOptions ### `createEmptyDocument` -`function` +`function` — Create a new empty SceneDocument with a title and optional initial page settings ```ts (title: string, page?: NewPageOptions | undefined) => SceneDocument @@ -240,7 +240,7 @@ interface CreateDesignCanvasMcpHandlerOptions ### `createPage` -`function` +`function` — Create a new ScenePage with specified options and a unique identifier ```ts (options: NewPageOptions, id: string) => ScenePage @@ -248,7 +248,7 @@ interface CreateDesignCanvasMcpHandlerOptions ### `DEFAULT_DESIGN_CANVAS_MCP_DESCRIPTION` -`const` +`const` — Describe the live visual asset editor capabilities for the current design document using CSS pixel coordinates ```ts "Live visual asset editor for the current design document: read scene state, add/move/resize/delete elements, manage pa… @@ -256,7 +256,7 @@ interface CreateDesignCanvasMcpHandlerOptions ### `DeleteElementOperation` -`interface` +`interface` — Resolve deletion of a specific element from a page by its identifiers ```ts interface DeleteElementOperation @@ -264,7 +264,7 @@ interface DeleteElementOperation ### `DeletePageOperation` -`interface` +`interface` — Represent a delete page operation with a specified page identifier ```ts interface DeletePageOperation @@ -272,7 +272,7 @@ interface DeletePageOperation ### `DesignCanvasMcpServerInfo` -`interface` +`interface` — Describe design canvas MCP server information including name and version ```ts interface DesignCanvasMcpServerInfo @@ -280,7 +280,7 @@ interface DesignCanvasMcpServerInfo ### `DesignCanvasMcpToolEnv` -`interface` +`interface` — Define the environment for MCP tool with a scene store and ID minting function ```ts interface DesignCanvasMcpToolEnv @@ -288,7 +288,7 @@ interface DesignCanvasMcpToolEnv ### `DuplicatePageOperation` -`interface` +`interface` — Define an operation to duplicate a page with a new caller-specified page ID ```ts interface DuplicatePageOperation @@ -312,7 +312,7 @@ interface DuplicatePageOperation ### `EllipseElement` -`interface` +`interface` — Define properties for an ellipse element including dimensions, fill, and optional stroke details ```ts interface EllipseElement @@ -320,7 +320,7 @@ interface EllipseElement ### `estimateTextHeight` -`function` +`function` — Estimate the height of multiline text based on font size and line height ```ts (element: Pick) => number @@ -328,7 +328,7 @@ interface EllipseElement ### `EXPORT_PRESETS` -`const` +`const` — Provide predefined export configurations for various social media and image formats ```ts Record @@ -336,7 +336,7 @@ Record ### `ExportCropRect` -`interface` +`interface` — Define crop rectangle coordinates and dimensions for exporting content within page bounds ```ts interface ExportCropRect @@ -344,7 +344,7 @@ interface ExportCropRect ### `ExportFormat` -`type` +`type` — Define supported image export formats as PNG or JPEG ```ts type ExportFormat @@ -360,7 +360,7 @@ interface ExportPreset ### `findCanvasMcpTool` -`function` +`function` — Find the canvas MCP tool definition matching the given name or return undefined ```ts (name: string) => McpToolDefinition | undefined @@ -376,7 +376,7 @@ interface ExportPreset ### `findPreset` -`function` +`function` — Resolve a size preset by its identifier or return null if not found ```ts (id: string) => SizePreset | null @@ -384,7 +384,7 @@ interface ExportPreset ### `GroupElement` -`interface` +`interface` — Define a group element that contains multiple child scene elements ```ts interface GroupElement @@ -392,7 +392,7 @@ interface GroupElement ### `GroupElementsOperation` -`interface` +`interface` — Group elements by grouping two or more sibling elements in their current z-order under a new group ID ```ts interface GroupElementsOperation @@ -400,7 +400,7 @@ interface GroupElementsOperation ### `ImageElement` -`interface` +`interface` — Define properties for an image element including source, dimensions, and fit mode ```ts interface ImageElement @@ -408,7 +408,7 @@ interface ImageElement ### `InstantiateOptions` -`interface` +`interface` — Define options for instantiating a document with title, optional bindings, and custom id minting ```ts interface InstantiateOptions @@ -424,7 +424,7 @@ interface InstantiateOptions ### `LineElement` -`interface` +`interface` — Define a line element with points, stroke, stroke width, and optional dash pattern ```ts interface LineElement @@ -448,7 +448,7 @@ interface LineElement ### `NewPageOptions` -`interface` +`interface` — Define options to configure a new page including name, dimensions, and background color ```ts interface NewPageOptions @@ -456,7 +456,7 @@ interface NewPageOptions ### `NewSceneDecision` -`interface` +`interface` — Define the structure for decisions related to creating a new scene with instructions and optional details ```ts interface NewSceneDecision @@ -480,7 +480,7 @@ interface PageGuides ### `RectElement` -`interface` +`interface` — Define a rectangular scene element with size, fill, optional stroke, and corner radius properties ```ts interface RectElement @@ -488,7 +488,7 @@ interface RectElement ### `ReorderElementOperation` -`interface` +`interface` — Resolve an operation to reorder an element within its current owner by specifying the target index ```ts interface ReorderElementOperation @@ -496,7 +496,7 @@ interface ReorderElementOperation ### `ReorderPageOperation` -`interface` +`interface` — Represent an operation to reorder a page by moving it to a specified index ```ts interface ReorderPageOperation @@ -512,7 +512,7 @@ interface ReorderPageOperation ### `requireElement` -`function` +`function` — Resolve and return the element, its owner array, and index from the page by element ID ```ts (page: ScenePage, elementId: string) => { element: SceneElement; owner: SceneElement[]; index: number; } @@ -520,7 +520,7 @@ interface ReorderPageOperation ### `requirePage` -`function` +`function` — Resolve and return a page by ID from a document or throw an error if not found ```ts (document: SceneDocument, pageId: string) => ScenePage @@ -544,7 +544,7 @@ interface ReorderPageOperation ### `SCENE_ELEMENT_KINDS` -`const` +`const` — Define all valid kinds of scene elements used in the application ```ts readonly ("text" | "image" | "rect" | "video" | "ellipse" | "line" | "group")[] @@ -552,7 +552,7 @@ readonly ("text" | "image" | "rect" | "video" | "ellipse" | "line" | "group")[] ### `SCENE_OPERATION_TYPES` -`const` +`const` — Define all valid operation types for scene manipulation in the application ```ts readonly ("add_element" | "set_attrs" | "reorder_element" | "delete_element" | "group_elements" | "ungroup_element" | "… @@ -560,7 +560,7 @@ readonly ("add_element" | "set_attrs" | "reorder_element" | "delete_element" | " ### `SCENE_SCHEMA_VERSION` -`const` +`const` — Define the current version number of the scene schema ```ts 1 @@ -568,7 +568,7 @@ readonly ("add_element" | "set_attrs" | "reorder_element" | "delete_element" | " ### `SceneApplyResult` -`type` +`type` — Represent the result of applying changes to a scene as an element, page, or entire document ```ts type SceneApplyResult @@ -584,7 +584,7 @@ type SceneAttrsPatch ### `SceneDecision` -`interface` +`interface` — Define the structure for decisions made within a scene including type, instructions, and metadata ```ts interface SceneDecision @@ -592,7 +592,7 @@ interface SceneDecision ### `SceneDocument` -`interface` +`interface` — Define the structure and properties of a scene document including version, title, pages, settings, and metadata ```ts interface SceneDocument @@ -600,7 +600,7 @@ interface SceneDocument ### `SceneDocumentRecord` -`interface` +`interface` — Represent a scene document with its current revision number for version tracking ```ts interface SceneDocumentRecord @@ -608,7 +608,7 @@ interface SceneDocumentRecord ### `SceneElement` -`type` +`type` — Represent a graphical element in a scene including shapes, text, media, or groups ```ts type SceneElement @@ -624,7 +624,7 @@ interface SceneElementBase ### `SceneElementKind` -`type` +`type` — Extract the kind property from a SceneElement to identify its element type ```ts type SceneElementKind @@ -632,7 +632,7 @@ type SceneElementKind ### `SceneExportFormat` -`type` +`type` — Define supported formats for exporting a scene including image and JSON options ```ts type SceneExportFormat @@ -640,7 +640,7 @@ type SceneExportFormat ### `SceneExportRecord` -`interface` +`interface` — Describe a scene export with its status, format, metadata, and result information ```ts interface SceneExportRecord @@ -648,7 +648,7 @@ interface SceneExportRecord ### `SceneOperation` -`type` +`type` — Represent operations that modify scenes by adding, updating, reordering, grouping, or deleting elements and pages ```ts type SceneOperation @@ -656,7 +656,7 @@ type SceneOperation ### `SceneOperationType` -`type` +`type` — Extract the type property from a SceneOperation to represent its operation type ```ts type SceneOperationType @@ -664,7 +664,7 @@ type SceneOperationType ### `ScenePage` -`interface` +`interface` — Define the structure and properties of a scene page including layout, background, and elements ```ts interface ScenePage @@ -672,7 +672,7 @@ interface ScenePage ### `ScenePlan` -`interface` +`interface` — Define a plan summarizing a scene with its description and associated operations ```ts interface ScenePlan @@ -680,7 +680,7 @@ interface ScenePlan ### `SceneSettings` -`interface` +`interface` — Define settings for scene export including print conversion factor for unit calculations ```ts interface SceneSettings @@ -688,7 +688,7 @@ interface SceneSettings ### `SceneStore` -`interface` +`interface` — Manage scene documents, decisions, and exports with atomic save and revision control ```ts interface SceneStore @@ -704,7 +704,7 @@ interface SceneStoreScope ### `SetAttrsOperation` -`interface` +`interface` — Define an operation to update attributes of a specific element on a page ```ts interface SetAttrsOperation @@ -712,7 +712,7 @@ interface SetAttrsOperation ### `SetDocumentTitleOperation` -`interface` +`interface` — Define an operation to set the document title to a specified string ```ts interface SetDocumentTitleOperation @@ -720,7 +720,7 @@ interface SetDocumentTitleOperation ### `SetPageGuidesOperation` -`interface` +`interface` — Resolve an operation to set guides on a specific page by its identifier ```ts interface SetPageGuidesOperation @@ -728,7 +728,7 @@ interface SetPageGuidesOperation ### `SetPagePropsOperation` -`interface` +`interface` — Define an operation to set or update properties of a page including size, background, and bleed ```ts interface SetPagePropsOperation @@ -736,7 +736,7 @@ interface SetPagePropsOperation ### `SIZE_PRESETS` -`const` +`const` — Provide predefined size presets for social, presentation, and print categories ```ts readonly SizePreset[] @@ -744,7 +744,7 @@ readonly SizePreset[] ### `SizePreset` -`interface` +`interface` — Define size presets with identifiers, labels, categories, and dimensions for various media types ```ts interface SizePreset @@ -752,7 +752,7 @@ interface SizePreset ### `SlotFillKind` -`type` +`type` — Define allowed string literals representing different slot fill kinds ```ts type SlotFillKind @@ -760,7 +760,7 @@ type SlotFillKind ### `storeApplyScenePlan` -`function` +`function` — Resolve and apply a scene plan to the store with specified actor context and generate results ```ts (store: SceneStore, plan: ScenePlan, opts: { actorKind: "human_edit" | "agent_edit" | "agent_proposal" | "export" | "no… @@ -768,7 +768,7 @@ type SlotFillKind ### `TemplateSlot` -`interface` +`interface` — Define a slot template specifying its name, page, element, and fill characteristics ```ts interface TemplateSlot @@ -776,7 +776,7 @@ interface TemplateSlot ### `TextElement` -`interface` +`interface` — Define properties for a text element including content, style, alignment, and layout parameters ```ts interface TextElement @@ -784,7 +784,7 @@ interface TextElement ### `UngroupElementOperation` -`interface` +`interface` — Resolve an operation to ungroup elements within a specified page and group context ```ts interface UngroupElementOperation @@ -800,7 +800,7 @@ interface UngroupElementOperation ### `validateSceneOperation` -`function` +`function` — Validate a scene operation against the document to ensure it meets required constraints ```ts (document: SceneDocument, operation: SceneOperation) => void @@ -808,7 +808,7 @@ interface UngroupElementOperation ### `validateSceneOperations` -`function` +`function` — Validate each scene operation against the document and throw detailed errors for invalid operations ```ts (document: SceneDocument, operations: SceneOperation[]) => void diff --git a/docs/api/durable-chat.md b/docs/api/durable-chat.md index c4b1e6f..add0129 100644 --- a/docs/api/durable-chat.md +++ b/docs/api/durable-chat.md @@ -8,7 +8,7 @@ Source: `src/durable-chat/index.ts` ### `applyDurableInteractionAnswer` -`function` +`function` — Resolve and record the outcome and answers of a durable interaction within the given store and scope ```ts (store: DurablePlanStore, scope: DurableChatScope, interactionId: string, outcome: "declined" | "accepted", answers?: R… @@ -16,7 +16,7 @@ Source: `src/durable-chat/index.ts` ### `applyDurableInteractionAsk` -`function` +`function` — Resolve and upsert a durable interaction ask in the store with optional event and timing parameters ```ts (store: DurablePlanStore, scope: DurableChatScope, request: InteractionRequestWire, options?: { eventId?: string | unde… @@ -24,7 +24,7 @@ Source: `src/durable-chat/index.ts` ### `applyDurableInteractionCancel` -`function` +`function` — Resolve cancellation of a durable interaction with optional reason and event details ```ts (store: DurablePlanStore, scope: DurableChatScope, interactionId: string, reason?: string | undefined, options?: { even… @@ -40,7 +40,7 @@ Source: `src/durable-chat/index.ts` ### `createDurableChatScope` -`function` +`function` — Create a durable chat scope from a non-empty string value ```ts (value: string) => DurableChatScope @@ -64,7 +64,7 @@ Source: `src/durable-chat/index.ts` ### `CreateDurableInteractionRoutePersistenceOptions` -`type` +`type` — Define options for durable interaction route persistence with reconciliation guarantees and authority functions ```ts type CreateDurableInteractionRoutePersistenceOptions @@ -80,7 +80,7 @@ type CreateDurableInteractionRoutePersistenceOptions ### `createDurablePlanRoutes` -`function` +`function` — Build durable plan routes with authorization and effect handling based on provided options ```ts (options: DurablePlanRouteOptions) => DurablePlanRoutes @@ -88,7 +88,7 @@ type CreateDurableInteractionRoutePersistenceOptions ### `createInMemoryDurableChatStateStore` -`function` +`function` — Create an in-memory durable chat state store for managing chat session data efficiently ```ts () => InMemoryDurableChatStateStore @@ -96,7 +96,7 @@ type CreateDurableInteractionRoutePersistenceOptions ### `DurableAnswerIntentJournal` -`type` +`type` — Provide durable methods to manage the lifecycle of answer intents in a plan store ```ts type DurableAnswerIntentJournal @@ -104,7 +104,7 @@ type DurableAnswerIntentJournal ### `DurableAnswerIntentRecord` -`interface` +`interface` — Define the structure for recording durable answer intent details and their states ```ts interface DurableAnswerIntentRecord @@ -112,7 +112,7 @@ interface DurableAnswerIntentRecord ### `DurableAnswerIntentState` -`type` +`type` — Define possible states for a durable answer intent lifecycle ```ts type DurableAnswerIntentState @@ -120,7 +120,7 @@ type DurableAnswerIntentState ### `DurableChatConflictError` -`class` +`class` — Represent conflict errors occurring in durable chat state management ```ts class DurableChatConflictError @@ -136,7 +136,7 @@ class DurableChatError ### `DurableChatErrorCode` -`type` +`type` — Define error codes representing possible Durable Chat failure scenarios ```ts type DurableChatErrorCode @@ -144,7 +144,7 @@ type DurableChatErrorCode ### `DurableChatEventProjection` -`interface` +`interface` — Resolve chat events and materialize their state into durable records ```ts interface DurableChatEventProjection @@ -152,7 +152,7 @@ interface DurableChatEventProjection ### `DurableChatGoneError` -`class` +`class` — Represent durable chat errors indicating the chat plan is no longer available ```ts class DurableChatGoneError @@ -168,7 +168,7 @@ type DurableChatScope ### `durableChatScopeKey` -`function` +`function` — Resolve a valid durable chat scope key from the given scope input ```ts (scope: DurableChatScope) => string @@ -184,7 +184,7 @@ type DurableChatStateStore ### `DurableChatUnavailableError` -`class` +`class` — Represent unavailable durable chat authority errors with status code 503 ```ts class DurableChatUnavailableError @@ -192,7 +192,7 @@ class DurableChatUnavailableError ### `DurableFollowUpReceipt` -`interface` +`interface` — Define a durable receipt capturing stable identifiers and state for follow-up decisions ```ts interface DurableFollowUpReceipt @@ -200,7 +200,7 @@ interface DurableFollowUpReceipt ### `DurableInteractionAcknowledgement` -`interface` +`interface` — Represent durable acknowledgement of an interaction with optional authority, status, and timestamp fields ```ts interface DurableInteractionAcknowledgement @@ -208,7 +208,7 @@ interface DurableInteractionAcknowledgement ### `DurableInteractionGuarantee` -`type` +`type` — Define interaction durability levels to specify reconciliation or best-effort guarantees ```ts type DurableInteractionGuarantee @@ -224,7 +224,7 @@ type DurableInteractionGuarantee ### `DurableInteractionProjection` -`interface` +`interface` — Define a durable chat interaction projection with idempotent event tracking and optional tombstone flag ```ts interface DurableInteractionProjection @@ -232,7 +232,7 @@ interface DurableInteractionProjection ### `DurableInteractionProjectionAdapter` -`interface` +`interface` — Define methods to manage durable interaction projections including upsert, cancel, and materialize operations ```ts interface DurableInteractionProjectionAdapter @@ -240,7 +240,7 @@ interface DurableInteractionProjectionAdapter ### `DurableInteractionSettlement` -`interface` +`interface` — Manage durable interaction lifecycles by preparing, acknowledging, finalizing, aborting, and reconciling intents ```ts interface DurableInteractionSettlement @@ -248,7 +248,7 @@ interface DurableInteractionSettlement ### `DurableInteractionSettlementFactoryOptions` -`interface` +`interface` — Define options for creating durable interaction settlement factories including store and optional reconcile authority ```ts interface DurableInteractionSettlementFactoryOptions @@ -256,7 +256,7 @@ interface DurableInteractionSettlementFactoryOptions ### `DurableInteractionSettlementOptions` -`interface` +`interface` — Define options for durable interaction settlement including attempt key, guarantee, and timestamp provider ```ts interface DurableInteractionSettlementOptions @@ -272,7 +272,7 @@ interface DurablePlanAuthority ### `DurablePlanAuthorityCurrentResult` -`interface` +`interface` — Represent the current authoritative state and optional receipt of a durable plan authority ```ts interface DurablePlanAuthorityCurrentResult @@ -280,7 +280,7 @@ interface DurablePlanAuthorityCurrentResult ### `DurablePlanAuthorityDecision` -`type` +`type` — Resolve durable plan authority decisions including approval, rejection, or predefined durable decisions ```ts type DurablePlanAuthorityDecision @@ -288,7 +288,7 @@ type DurablePlanAuthorityDecision ### `DurablePlanAuthorityResult` -`interface` +`interface` — Describe the outcome of an authority's durable plan decision including follow-up and metadata ```ts interface DurablePlanAuthorityResult @@ -296,7 +296,7 @@ interface DurablePlanAuthorityResult ### `DurablePlanAuthorization` -`type` +`type` — Resolve authorization status for durable plans using scopes, responses, or nullish values ```ts type DurablePlanAuthorization @@ -304,7 +304,7 @@ type DurablePlanAuthorization ### `DurablePlanCommandJournal` -`type` +`type` — Pick essential methods to manage and record durable plan command operations ```ts type DurablePlanCommandJournal @@ -312,7 +312,7 @@ type DurablePlanCommandJournal ### `DurablePlanCommandKey` -`type` +`type` — Represent a unique identifier key for durable plan commands ```ts type DurablePlanCommandKey @@ -320,7 +320,7 @@ type DurablePlanCommandKey ### `DurablePlanCommandRecord` -`interface` +`interface` — Define the structure for recording durable plan commands with associated metadata and state information ```ts interface DurablePlanCommandRecord @@ -328,7 +328,7 @@ interface DurablePlanCommandRecord ### `DurablePlanCommandState` -`type` +`type` — Define possible states for a durable plan command in its lifecycle ```ts type DurablePlanCommandState @@ -336,7 +336,7 @@ type DurablePlanCommandState ### `DurablePlanDecision` -`type` +`type` — Represent durable plan outcomes as either approved or rejected ```ts type DurablePlanDecision @@ -344,7 +344,7 @@ type DurablePlanDecision ### `DurablePlanEffectRecord` -`interface` +`interface` — Define the structure for recording the state and metadata of a durable plan effect ```ts interface DurablePlanEffectRecord @@ -360,7 +360,7 @@ type DurablePlanProjection ### `DurablePlanRouteAuthorizeArgs` -`interface` +`interface` — Define arguments for authorizing durable plan route requests with operation and optional plan ID ```ts interface DurablePlanRouteAuthorizeArgs @@ -368,7 +368,7 @@ interface DurablePlanRouteAuthorizeArgs ### `DurablePlanRouteOptions` -`interface` +`interface` — Define options for durable plan routing including store, authority, authorization, and idempotent side effect handling ```ts interface DurablePlanRouteOptions @@ -376,7 +376,7 @@ interface DurablePlanRouteOptions ### `DurablePlanRoutes` -`interface` +`interface` — Define routes handling durable plan requests with current and decide methods ```ts interface DurablePlanRoutes @@ -384,7 +384,7 @@ interface DurablePlanRoutes ### `DurablePlanStateStore` -`type` +`type` — Represent durable storage for plan state management with persistence and reliability guarantees ```ts type DurablePlanStateStore @@ -392,7 +392,7 @@ type DurablePlanStateStore ### `DurablePlanStore` -`interface` +`interface` — Manage durable storage and retrieval of plan projections, commands, and effects within a scoped context ```ts interface DurablePlanStore @@ -416,7 +416,7 @@ typeof InMemoryDurableChatStateStore ### `normalizePlanDecision` -`function` +`function` — Normalize input value to a standardized DurablePlanDecision or return null for invalid inputs ```ts (value: unknown) => DurablePlanDecision | null @@ -424,7 +424,7 @@ typeof InMemoryDurableChatStateStore ### `planAuthorityIdempotencyKey` -`function` +`function` — Generate a unique idempotency key for a plan authority based on scope, plan, revision, and decision ```ts (scope: DurableChatScope, planId: string, revision: number, decision: DurablePlanDecision) => string @@ -432,7 +432,7 @@ typeof InMemoryDurableChatStateStore ### `planCommandKey` -`function` +`function` — Generate a unique key string for a plan command using plan ID, revision, and decision ```ts (planId: string, revision: number, decision: DurablePlanDecision) => string @@ -440,7 +440,7 @@ typeof InMemoryDurableChatStateStore ### `planEffectKey` -`function` +`function` — Generate a unique string key representing the effect of a plan decision within a given scope and revision ```ts (scope: DurableChatScope, planId: string, revision: number, decision: DurablePlanDecision) => string @@ -448,7 +448,7 @@ typeof InMemoryDurableChatStateStore ### `PreparedDurableInteractionAnswer` -`interface` +`interface` — Define a structured response containing scope, settlement, and intent for durable interactions ```ts interface PreparedDurableInteractionAnswer @@ -472,7 +472,7 @@ interface PreparedDurableInteractionAnswer ### `stablePlanReceipt` -`function` +`function` — Resolve a durable follow-up receipt ensuring idempotency for a given plan decision and revision ```ts (scope: DurableChatScope, planId: string, revision: number, decision: DurablePlanDecision, result: Pick value is "opencode" | "claude-code" | "nanoclaw" | "kimi-code" | "codex" | "amp" | "factory-droids"… @@ -72,7 +72,7 @@ readonly ["opencode", "claude-code", "nanoclaw", "kimi-code", "codex", "amp", "f ### `ResolvedSessionHarness` -`interface` +`interface` — Represent resolved session state including harness, lock status, and swap attempt flag ```ts interface ResolvedSessionHarness @@ -88,7 +88,7 @@ interface ResolvedSessionHarness ### `ResolveSessionHarnessInput` -`interface` +`interface` — Resolve input options to determine the appropriate session harness to use ```ts interface ResolveSessionHarnessInput diff --git a/docs/api/index.md b/docs/api/index.md index 85e16d5..c0e10dc 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -8,7 +8,7 @@ Source: `src/index.ts` ### `AddCaptionOperation` -`interface` +`interface` — Add a caption with optional language, timing, and track placement details ```ts interface AddCaptionOperation @@ -16,7 +16,7 @@ interface AddCaptionOperation ### `AddCitationArgs` -`interface` +`interface` — Define arguments required to add a citation including path, quote, and optional label ```ts interface AddCitationArgs @@ -24,7 +24,7 @@ interface AddCitationArgs ### `AddCitationResult` -`interface` +`interface` — Represent the result of adding a citation including its identifier and location path ```ts interface AddCitationResult @@ -32,7 +32,7 @@ interface AddCitationResult ### `AddElementOperation` -`interface` +`interface` — Define an operation to add a scene element to a page with optional index and parent group ```ts interface AddElementOperation @@ -40,7 +40,7 @@ interface AddElementOperation ### `AddPageOperation` -`interface` +`interface` — Define an operation to add a new page with an optional position and caller-minted page ID ```ts interface AddPageOperation @@ -104,7 +104,7 @@ interface AgentKnowledgeConfig ### `AgentRuntime` -`interface` +`interface` — Resolve and stream tool execution loops with final results and intermediate events for agent runtime ```ts interface AgentRuntime @@ -128,7 +128,7 @@ interface AgentTaxonomyConfig ### `AgentTurnOptions` -`interface` +`interface` — Define options for configuring a single agent turn including context, prior messages, prompts, and event handlers ```ts interface AgentTurnOptions @@ -176,7 +176,7 @@ interface ApplyDataOperation ### `applyDurableInteractionAnswer` -`function` +`function` — Resolve and record the outcome and answers of a durable interaction within the given store and scope ```ts (store: DurablePlanStore, scope: DurableChatScope, interactionId: string, outcome: "declined" | "accepted", answers?: R… @@ -184,7 +184,7 @@ interface ApplyDataOperation ### `applyDurableInteractionAsk` -`function` +`function` — Resolve and upsert a durable interaction ask in the store with optional event and timing parameters ```ts (store: DurablePlanStore, scope: DurableChatScope, request: InteractionRequestWire, options?: { eventId?: string | unde… @@ -192,7 +192,7 @@ interface ApplyDataOperation ### `applyDurableInteractionCancel` -`function` +`function` — Resolve cancellation of a durable interaction with optional reason and event details ```ts (store: DurablePlanStore, scope: DurableChatScope, interactionId: string, reason?: string | undefined, options?: { even… @@ -224,7 +224,7 @@ interface ApplyDataOperation ### `ApplySceneOptions` -`interface` +`interface` — Resolve element ID conflicts by providing fresh unique identifiers during scene application ```ts interface ApplySceneOptions @@ -232,7 +232,7 @@ interface ApplySceneOptions ### `applySequenceOperation` -`function` +`function` — Apply a sequence operation to update the store and timeline asynchronously ```ts (store: SequenceStore, timeline: SequenceTimeline, op: SequenceOperation, ctx: SequenceOperationContext) => Promise<...> @@ -248,7 +248,7 @@ interface ApplySceneOptions ### `ApprovalEvent` -`interface` +`interface` — Describe an approval event with action details, user info, and optional edited fields ```ts interface ApprovalEvent @@ -256,7 +256,7 @@ interface ApprovalEvent ### `ApprovalEventSchema` -`const` +`const` — Validate approval event data including asset, action, user, timestamp, and optional fields ```ts ZodObject<{ assetId: ZodString; variantId: ZodOptional; action: ZodEnum<{ scheduled: "scheduled"; approved:… @@ -280,7 +280,7 @@ interface AppToolDefinition ### `AppToolDescriptor` -`interface` +`interface` — Describe an application tool with its name, unique key, and description ```ts interface AppToolDescriptor @@ -312,7 +312,7 @@ interface AppToolMcpServer ### `AppToolName` -`type` +`type` — Resolve a valid application tool name from the predefined list of tool names ```ts type AppToolName @@ -360,7 +360,7 @@ interface AppToolTaxonomy ### `asRecord` -`function` +`function` — Resolve an unknown value to a JsonRecord if it is a non-array object or return undefined ```ts (value: unknown) => JsonRecord | undefined @@ -368,7 +368,7 @@ interface AppToolTaxonomy ### `assertClipFitsSequence` -`function` +`function` — Validate that a clip's start and duration fit within the sequence duration without overflow ```ts (input: { startFrame: number; durationFrames: number; sequenceDurationFrames: number; label: string; }) => void @@ -376,7 +376,7 @@ interface AppToolTaxonomy ### `assertColor` -`function` +`function` — Validate that a string is a hex, rgb(a), or 'transparent' color and throw an error if not ```ts (value: string, label: string) => void @@ -392,7 +392,7 @@ interface AppToolTaxonomy ### `assertFinite` -`function` +`function` — Assert that a value is a finite number and throw an error with a label if not ```ts (value: number, label: string) => void @@ -416,7 +416,7 @@ interface AppToolTaxonomy ### `assertPositiveFinite` -`function` +`function` — Assert that a value is a positive finite number and throw an error with a label if not ```ts (value: number, label: string) => void @@ -456,7 +456,7 @@ interface AppToolTaxonomy ### `AssetContentMap` -`type` +`type` — Map asset keys to their corresponding content types for various media and copy formats ```ts type AssetContentMap @@ -464,7 +464,7 @@ type AssetContentMap ### `AssetFormat` -`type` +`type` — Define valid asset format strings for various media and copy types ```ts type AssetFormat @@ -472,7 +472,7 @@ type AssetFormat ### `AssetSpec` -`interface` +`interface` — Define the structure and metadata for an asset including its format, brand, content, and status ```ts interface AssetSpec @@ -480,7 +480,7 @@ interface AssetSpec ### `AssetStatus` -`type` +`type` — Define possible states representing the lifecycle status of an asset ```ts type AssetStatus @@ -488,7 +488,7 @@ type AssetStatus ### `AssetVariant` -`interface` +`interface` — Describe an asset variant with identification, approval status, and edit history details ```ts interface AssetVariant @@ -496,7 +496,7 @@ interface AssetVariant ### `asString` -`function` +`function` — Resolve a non-empty string from a value or return undefined ```ts (value: unknown) => string | undefined @@ -536,7 +536,7 @@ interface AssetVariant ### `attachReasoningEffort` -`function` +`function` — Attach a specified reasoning effort level to an agent profile for a given harness ```ts (profile: AgentProfile, harness: "opencode" | "claude-code" | "nanoclaw" | "kimi-code" | "codex" | "amp" | "factory-dro… @@ -544,7 +544,7 @@ interface AssetVariant ### `AuthenticatedSandboxUser` -`interface` +`interface` — Represent an authenticated user within a sandbox environment with a unique identifier ```ts interface AuthenticatedSandboxUser @@ -552,7 +552,7 @@ interface AuthenticatedSandboxUser ### `AuthenticateOptions` -`interface` +`interface` — Define options to verify bearer tokens and customize authentication header names ```ts interface AuthenticateOptions @@ -568,7 +568,7 @@ interface AuthenticateOptions ### `bearerSubprotocolToken` -`function` +`function` — Resolve and decode a bearer token from a comma-separated subprotocol string or return null ```ts (value: string | null) => string | null @@ -576,7 +576,7 @@ interface AuthenticateOptions ### `bearerToken` -`function` +`function` — Extract the token from a bearer authorization string or return null if invalid or missing ```ts (value: string | null) => string | null @@ -584,7 +584,7 @@ interface AuthenticateOptions ### `BeforeInteractionAnswerArgs` -`interface` +`interface` — Describe the arguments provided before processing an interaction answer including request, body, and connection details ```ts interface BeforeInteractionAnswerArgs @@ -592,7 +592,7 @@ interface BeforeInteractionAnswerArgs ### `BindSlotOperation` -`interface` +`interface` — Define an operation to bind or unbind a unique slot to an element on a specific page ```ts interface BindSlotOperation @@ -616,7 +616,7 @@ interface BindSlotOperation ### `Bounds` -`interface` +`interface` — Define rectangular boundaries with position and size properties ```ts interface Bounds @@ -624,7 +624,7 @@ interface Bounds ### `boundsIntersect` -`function` +`function` — Determine if two rectangular bounds overlap or intersect each other ```ts (a: Bounds, b: Bounds) => boolean @@ -632,7 +632,7 @@ interface Bounds ### `BrandTokens` -`interface` +`interface` — Define brand identity tokens including colors, font, logo, business name, and voice ```ts interface BrandTokens @@ -640,7 +640,7 @@ interface BrandTokens ### `BrandTokensSchema` -`const` +`const` — Validate brand token properties including colors, font, logo URL, business name, and voice ```ts ZodObject<{ primaryColor: ZodString; accentColor: ZodString; textColor: ZodString; fontFamily: ZodString; logoUrl: ZodO… @@ -664,7 +664,7 @@ interface BrokerTokenMinter ### `BrokerTokenProvider` -`interface` +`interface` — Provide and refresh broker bearer tokens, allowing forced token invalidation ```ts interface BrokerTokenProvider @@ -672,7 +672,7 @@ interface BrokerTokenProvider ### `BrokerTokenProviderOptions` -`interface` +`interface` — Define options for configuring a broker token provider including client credentials and token management settings ```ts interface BrokerTokenProviderOptions @@ -688,7 +688,7 @@ interface BrokerTokenProviderOptions ### `BufferedTurnEvent` -`interface` +`interface` — Represent a buffered turn event with a sequence number and serialized event data ```ts interface BufferedTurnEvent @@ -696,7 +696,7 @@ interface BufferedTurnEvent ### `BufferedTurnOptions` -`interface` +`interface` — Define options for buffering and flushing turn events with optional live client delivery and event coalescing ```ts interface BufferedTurnOptions @@ -728,7 +728,7 @@ interface BufferedTurnTap ### `buildAppToolMcpServers` -`function` +`function` — Build a mapping of MCP server profiles keyed by tool identifiers from provided options ```ts (options: BuildAppToolMcpServersOptions) => Record @@ -736,7 +736,7 @@ interface BufferedTurnTap ### `BuildAppToolMcpServersOptions` -`interface` +`interface` — Define options for building MCP server configurations in the app tool environment ```ts interface BuildAppToolMcpServersOptions @@ -776,7 +776,7 @@ interface BuildAppToolsOptions ### `BuildCaptionChunksOptions` -`interface` +`interface` — Define options to configure caption chunk size, duration, and frame rate constraints ```ts interface BuildCaptionChunksOptions @@ -816,7 +816,7 @@ interface BuildCaptionChunksOptions ### `BuildDesignCanvasMcpServerEntryOptions` -`type` +`type` — Build scoped MCP server entry options for the design canvas environment ```ts type BuildDesignCanvasMcpServerEntryOptions @@ -848,7 +848,7 @@ type BuildDesignCanvasMcpServerEntryOptions ### `BuildHttpMcpServerOptions` -`interface` +`interface` — Define configuration options for building an HTTP MCP server including path, baseUrl, token, context, and description ```ts interface BuildHttpMcpServerOptions @@ -864,7 +864,7 @@ interface BuildHttpMcpServerOptions ### `BuildMcpServerOptions` -`interface` +`interface` — Define configuration options required to build an MCP server including tool, baseUrl, token, and context ```ts interface BuildMcpServerOptions @@ -888,7 +888,7 @@ interface BuildMcpServerOptions ### `BuildRedactedDocumentOptions` -`interface` +`interface` — Define options to encrypt text and specify patterns for redacting sensitive document content ```ts interface BuildRedactedDocumentOptions @@ -896,7 +896,7 @@ interface BuildRedactedDocumentOptions ### `buildSandboxRuntimeProxyHeaders` -`function` +`function` — Build proxy headers for sandbox runtime including authorization and forwarded headers ```ts (source: Headers, sandboxApiKey: string, forwardHeaders?: string[]) => Headers @@ -904,7 +904,7 @@ interface BuildRedactedDocumentOptions ### `buildSandboxToolFileMounts` -`function` +`function` — Build file mounts for sandbox tools based on provided options and tool configurations ```ts (options: BuildSandboxToolFileMountsOptions) => AgentProfileFileMount[] @@ -912,7 +912,7 @@ interface BuildRedactedDocumentOptions ### `BuildSandboxToolFileMountsOptions` -`interface` +`interface` — Define options for building sandbox tool file mounts including tool specifications and paths ```ts interface BuildSandboxToolFileMountsOptions @@ -920,7 +920,7 @@ interface BuildSandboxToolFileMountsOptions ### `buildSandboxToolPathSetupScript` -`function` +`function` — Build a shell script that sets up and exports the sandbox tool binary directory in user profiles ```ts (options: SandboxToolPathOptions) => string @@ -944,7 +944,7 @@ interface BuildSandboxToolFileMountsOptions ### `BuildSequencesMcpServerEntryOptions` -`type` +`type` — Extend ScopedMcpServerEntryOptions to configure MCP server entry options for sequence building ```ts type BuildSequencesMcpServerEntryOptions @@ -960,7 +960,7 @@ type BuildSequencesMcpServerEntryOptions ### `buildUserTextParts` -`function` +`function` — Build an array of text parts with optional turn ID for user input ```ts (text: string, turnId: string | undefined) => JsonRecord[] @@ -1008,7 +1008,7 @@ type BuildSequencesMcpServerEntryOptions ### `CANVAS_ELEMENT_KINDS` -`const` +`const` — Provide a readonly array of string identifiers representing canvas element kinds ```ts readonly string[] @@ -1016,7 +1016,7 @@ readonly string[] ### `CANVAS_MCP_TOOL_NAMES` -`const` +`const` — Extract names of all tools from the CANVAS_MCP_TOOLS array ```ts string[] @@ -1024,7 +1024,7 @@ string[] ### `CANVAS_MCP_TOOLS` -`const` +`const` — Provide a collection of MCP tool definitions for manipulating and querying the design canvas environment ```ts McpToolDefinition[] @@ -1040,7 +1040,7 @@ interface CanvasRenderPalette ### `CapabilityTokenOptions` -`interface` +`interface` — Define options for creating and verifying capability tokens including secret and prefix ```ts interface CapabilityTokenOptions @@ -1072,7 +1072,7 @@ interface CaptionCoverageEntry ### `CaptionExportOptions` -`interface` +`interface` — Define options to export captions filtered by an optional BCP-47 language tag ```ts interface CaptionExportOptions @@ -1080,7 +1080,7 @@ interface CaptionExportOptions ### `CaptionTargetResolution` -`type` +`type` — Resolve caption target by specifying an existing track or creating a new one with language and name ```ts type CaptionTargetResolution @@ -1096,7 +1096,7 @@ type CaptionTargetResolution ### `CatalogModel` -`interface` +`interface` — Define the structure and capabilities of a catalog item with optional pricing and feature flags ```ts interface CatalogModel @@ -1104,7 +1104,7 @@ interface CatalogModel ### `CertifiedDelivery` -`interface` +`interface` — Resolve and manage certified profiles with refresh and composition capabilities ```ts interface CertifiedDelivery @@ -1112,7 +1112,7 @@ interface CertifiedDelivery ### `CertifiedDeliveryConfig` -`interface` +`interface` — Define configuration options for delivering certified artifacts to a specified tenant target ```ts interface CertifiedDeliveryConfig @@ -1128,7 +1128,7 @@ readonly ChannelPreset[] ### `ChannelPreset` -`interface` +`interface` — Define a preset configuration for a channel including its id, label, width, and height ```ts interface ChannelPreset @@ -1136,7 +1136,7 @@ interface ChannelPreset ### `ChannelPresetId` -`type` +`type` — Resolve a valid channel preset identifier from the predefined channel presets array ```ts type ChannelPresetId @@ -1144,7 +1144,7 @@ type ChannelPresetId ### `ChannelScaleResult` -`interface` +`interface` — Define the pixel ratio and horizontal offset for scaling a Konva stage to a channel preset size ```ts interface ChannelScaleResult @@ -1176,7 +1176,7 @@ interface ChatFilePart ### `ChatImagePart` -`interface` +`interface` — Define properties for an image part within a chat message including optional metadata fields ```ts interface ChatImagePart @@ -1192,7 +1192,7 @@ interface ChatInteraction ### `ChatInteractionField` -`type` +`type` — Resolve a chat interaction field excluding select types or including chat select fields ```ts type ChatInteractionField @@ -1208,7 +1208,7 @@ interface ChatInteractionPart ### `ChatInteractionStatus` -`type` +`type` — Define possible statuses representing the state of a chat interaction ```ts type ChatInteractionStatus @@ -1232,7 +1232,7 @@ interface ChatMentionPart ### `ChatMessagePart` -`type` +`type` — Represent parts of a chat message including text, reasoning, tools, files, images, subtasks, steps, interactions, notices, plans, and mentions ```ts type ChatMessagePart @@ -1264,7 +1264,7 @@ type ChatPlan ### `ChatPlanPart` -`type` +`type` — Resolve a chat plan part by aliasing it to the persisted chat plan part type ```ts type ChatPlanPart @@ -1288,7 +1288,7 @@ type ChatPlanStatus ### `ChatReasoningPart` -`interface` +`interface` — Define a reasoning part of a chat with text content and optional metadata fields ```ts interface ChatReasoningPart @@ -1296,7 +1296,7 @@ interface ChatReasoningPart ### `ChatSelectField` -`type` +`type` — Extract select-type interaction fields and optionally allow custom values ```ts type ChatSelectField @@ -1304,7 +1304,7 @@ type ChatSelectField ### `ChatStepFinishPart` -`interface` +`interface` — Define a chat step finish part indicating completion with optional reason, tokens, and cost ```ts interface ChatStepFinishPart @@ -1328,7 +1328,7 @@ class ChatStoreInputError ### `ChatSubtaskPart` -`interface` +`interface` — Define a subtask part of a chat with prompt, description, agent, and optional identifier ```ts interface ChatSubtaskPart @@ -1344,7 +1344,7 @@ interface ChatTextPart ### `ChatToolPart` -`interface` +`interface` — Define a chat component representing a tool with its state and optional call identifier ```ts interface ChatToolPart @@ -1352,7 +1352,7 @@ interface ChatToolPart ### `ChatToolState` -`interface` +`interface` — Describe the current state and data of a chat tool including status, input, output, and metadata ```ts interface ChatToolState @@ -1408,7 +1408,7 @@ interface ChatUsageTokens ### `clampClipDuration` -`function` +`function` — Clamp clip duration to fit within sequence bounds and minimum length constraints ```ts (input: { startFrame: number; durationFrames: number; sequenceDurationFrames: number; }) => number @@ -1416,7 +1416,7 @@ interface ChatUsageTokens ### `clampClipStart` -`function` +`function` — Clamp the clip start frame within the valid range of the sequence duration and clip length ```ts (input: { startFrame: number; durationFrames: number; sequenceDurationFrames: number; }) => number @@ -1424,7 +1424,7 @@ interface ChatUsageTokens ### `classifySeveredStream` -`function` +`function` — Resolve the severed stream event to a corresponding sandbox step transition or null ```ts (event: unknown) => SandboxStepTransition | null @@ -1480,7 +1480,7 @@ interface ChatUsageTokens ### `CompleteMissionInput` -`interface` +`interface` — Define input parameters to complete a mission with status and optional summary ```ts interface CompleteMissionInput @@ -1528,7 +1528,7 @@ interface CompletionVerdict ### `ComposerAnswerDelivery` -`interface` +`interface` — Define the structure for delivering answers linked to a specific chat interaction and field ```ts interface ComposerAnswerDelivery @@ -1536,7 +1536,7 @@ interface ComposerAnswerDelivery ### `ConsentUrlInput` -`interface` +`interface` — Define input parameters required to generate a consent URL for OAuth authorization ```ts interface ConsentUrlInput @@ -1544,7 +1544,7 @@ interface ConsentUrlInput ### `ContactSheetEntry` -`interface` +`interface` — Describe a single entry in a contact sheet with timing and media source details ```ts interface ContactSheetEntry @@ -1552,7 +1552,7 @@ interface ContactSheetEntry ### `ContactSheetManifest` -`interface` +`interface` — Define the structure for a contact sheet manifest including metadata and entries ```ts interface ContactSheetManifest @@ -1560,7 +1560,7 @@ interface ContactSheetManifest ### `ConversionMetrics` -`interface` +`interface` — Define metrics for tracking impressions, clicks, conversions, and related rates ```ts interface ConversionMetrics @@ -1568,7 +1568,7 @@ interface ConversionMetrics ### `ConversionMetricsSchema` -`const` +`const` — Validate conversion metrics with nonnegative impressions, clicks, conversions, CTR, and CVR fields ```ts ZodObject<{ impressions: ZodNumber; clicks: ZodNumber; conversions: ZodNumber; ctr: ZodNumber; cvr: ZodNumber; }, $stri… @@ -1576,7 +1576,7 @@ ZodObject<{ impressions: ZodNumber; clicks: ZodNumber; conversions: ZodNumber; c ### `CookieOptions` -`interface` +`interface` — Define options for configuring cookie attributes and behavior ```ts interface CookieOptions @@ -1584,7 +1584,7 @@ interface CookieOptions ### `CopyContent` -`interface` +`interface` — Define the structure for content with headline, body, platform, and optional hashtags and character count ```ts interface CopyContent @@ -1592,7 +1592,7 @@ interface CopyContent ### `CopyContentSchema` -`const` +`const` — Validate and parse copy content with headline, body, optional hashtags, platform, and character count ```ts ZodObject<{ headline: ZodString; body: ZodString; hashtags: ZodOptional>; platform: ZodEnum<{ x: "x… @@ -1600,7 +1600,7 @@ ZodObject<{ headline: ZodString; body: ZodString; hashtags: ZodOptional TurnEventStore @@ -1688,7 +1688,7 @@ interface CreateAgentRuntimeOptions ### `createDesignCanvasMcpHandler` -`function` +`function` — Create a request handler for the design canvas MCP tool with specified options ```ts (opts: CreateDesignCanvasMcpHandlerOptions) => (request: Request) => Promise @@ -1696,7 +1696,7 @@ interface CreateAgentRuntimeOptions ### `CreateDesignCanvasMcpHandlerOptions` -`interface` +`interface` — Define options for creating a design canvas MCP handler including store, ID minting, and optional server info ```ts interface CreateDesignCanvasMcpHandlerOptions @@ -1712,7 +1712,7 @@ interface CreateDesignCanvasMcpHandlerOptions ### `createDurableChatScope` -`function` +`function` — Create a durable chat scope from a non-empty string value ```ts (value: string) => DurableChatScope @@ -1736,7 +1736,7 @@ interface CreateDesignCanvasMcpHandlerOptions ### `CreateDurableInteractionRoutePersistenceOptions` -`type` +`type` — Define options for durable interaction route persistence with reconciliation guarantees and authority functions ```ts type CreateDurableInteractionRoutePersistenceOptions @@ -1752,7 +1752,7 @@ type CreateDurableInteractionRoutePersistenceOptions ### `createDurablePlanRoutes` -`function` +`function` — Build durable plan routes with authorization and effect handling based on provided options ```ts (options: DurablePlanRouteOptions) => DurablePlanRoutes @@ -1760,7 +1760,7 @@ type CreateDurableInteractionRoutePersistenceOptions ### `createEmptyDocument` -`function` +`function` — Create a new empty SceneDocument with a title and optional initial page settings ```ts (title: string, page?: NewPageOptions | undefined) => SceneDocument @@ -1784,7 +1784,7 @@ type CreateDurableInteractionRoutePersistenceOptions ### `createInMemoryDurableChatStateStore` -`function` +`function` — Create an in-memory durable chat state store for managing chat session data efficiently ```ts () => InMemoryDurableChatStateStore @@ -1800,7 +1800,7 @@ type CreateDurableInteractionRoutePersistenceOptions ### `createInteractionAnswerRoute` -`function` +`function` — Create an interaction answer route that handles listing and resolving interaction requests ```ts (options: InteractionAnswerRouteOptions) => InteractionAnswerRoute @@ -1816,7 +1816,7 @@ type CreateDurableInteractionRoutePersistenceOptions ### `CreateKnowledgeLoopDeps` -`interface` +`interface` — Define dependencies required to create and run a knowledge processing loop ```ts interface CreateKnowledgeLoopDeps @@ -1840,7 +1840,7 @@ interface CreateKnowledgeLoopDeps ### `CreateMcpToolHandlerOptions` -`interface` +`interface` — Define options for creating a handler that manages MCP tools with environment support ```ts interface CreateMcpToolHandlerOptions @@ -1856,7 +1856,7 @@ interface CreateMcpToolHandlerOptions ### `createMissionEngine` -`function` +`function` — Create a mission engine configured with options to manage mission execution and error handling ```ts (options: MissionEngineOptions) => MissionEngine @@ -1864,7 +1864,7 @@ interface CreateMcpToolHandlerOptions ### `CreateMissionInput` -`interface` +`interface` — Define input parameters for creating a mission including optional deterministic id and unique plan steps ```ts interface CreateMissionInput @@ -1872,7 +1872,7 @@ interface CreateMissionInput ### `createMissionService` -`function` +`function` — Create a mission service that manages mission records and audit events with customizable options ```ts (options: MissionServiceOptions) => MissionService @@ -1896,7 +1896,7 @@ interface CreateMissionInput ### `createPage` -`function` +`function` — Create a new ScenePage with specified options and a unique identifier ```ts (options: NewPageOptions, id: string) => ScenePage @@ -1904,7 +1904,7 @@ interface CreateMissionInput ### `createPlatformBalanceManager` -`function` +`function` — Create a platform balance manager to handle user plan limits and state based on provided options ```ts (opts: PlatformBalanceManagerOptions) => PlatformBalanceManager @@ -1976,7 +1976,7 @@ interface CreateMissionInput ### `createSandboxTerminalToken` -`function` +`function` — Generate a sandbox terminal token for a given subject with specified options ```ts (subject: TerminalProxyIdentity, opts: SandboxTerminalTokenOptions) => Promise @@ -1984,7 +1984,7 @@ interface CreateMissionInput ### `createSequencesMcpHandler` -`function` +`function` — Create a handler to process MCP sequence requests with optional playhead frame and server info ```ts (opts: CreateSequencesMcpHandlerOptions) => (request: Request) => Promise @@ -1992,7 +1992,7 @@ interface CreateMissionInput ### `CreateSequencesMcpHandlerOptions` -`interface` +`interface` — Define options for creating sequences MCP handler including store, playhead frame, and server info ```ts interface CreateSequencesMcpHandlerOptions @@ -2016,7 +2016,7 @@ interface CreateSequencesMcpHandlerOptions ### `CreateTangleRouterModelConfigOptions` -`interface` +`interface` — Define configuration options for creating a Tangle router model including API key and model details ```ts interface CreateTangleRouterModelConfigOptions @@ -2040,7 +2040,7 @@ interface CreateTangleRouterModelConfigOptions ### `CreateTrackOperation` -`interface` +`interface` — Define an operation to create a new sequence track with a specified kind and name ```ts interface CreateTrackOperation @@ -2048,7 +2048,7 @@ interface CreateTrackOperation ### `createWorkspaceKeyManager` -`function` +`function` — Create a workspace key manager that handles key provisioning and budget tracking ```ts (opts: WorkspaceKeyManagerOptions) => WorkspaceKeyManager @@ -2056,7 +2056,7 @@ interface CreateTrackOperation ### `createWorkspaceSandboxConnectionHandler` -`function` +`function` — Create a handler to resolve workspace sandbox connections with user and access validation ```ts (opts: WorkspaceSandboxConnectionHandlerOptions) => ({ request, params… @@ -2064,7 +2064,7 @@ interface CreateTrackOperation ### `createWorkspaceSandboxManager` -`function` +`function` — Create a manager to handle workspace sandbox instances with client and options configuration ```ts (opts: WorkspaceSandboxManagerOptions ({ request, params }: WorkspaceSandboxRuntimeProxyArgs) => Promis… @@ -2120,7 +2120,7 @@ interface D1PreparedLike ### `darkTheme` -`const` +`const` — Define a dark color scheme for the Agent app interface with specific background and foreground hues ```ts AgentAppTheme @@ -2160,7 +2160,7 @@ AgentAppTheme ### `dedupeQuestionInteractionsByContent` -`function` +`function` — Remove duplicate question interactions based on their content signature to ensure uniqueness ```ts (interactions: ChatInteraction[]) => ChatInteraction[] @@ -2184,7 +2184,7 @@ Record<"submit_proposal" | "schedule_followup" | "render_ui" | "add_citation", s ### `DEFAULT_DESIGN_CANVAS_MCP_DESCRIPTION` -`const` +`const` — Describe the live visual asset editor capabilities for the current design document using CSS pixel coordinates ```ts "Live visual asset editor for the current design document: read scene state, add/move/resize/delete elements, manage pa… @@ -2192,7 +2192,7 @@ Record<"submit_proposal" | "schedule_followup" | "render_ui" | "add_citation", s ### `DEFAULT_HARNESS` -`const` +`const` — Define the default harness to use for code execution and testing environments ```ts "opencode" | "claude-code" | "nanoclaw" | "kimi-code" | "codex" | "amp" | "factory-droids" | "pi" | "hermes" | "forge"… @@ -2200,7 +2200,7 @@ Record<"submit_proposal" | "schedule_followup" | "render_ui" | "add_citation", s ### `DEFAULT_HEADER_NAMES` -`const` +`const` — Provide default HTTP header names for user, workspace, and thread identification ```ts ToolHeaderNames @@ -2224,7 +2224,7 @@ readonly RedactionPattern[] ### `DEFAULT_SANDBOX_RESOURCES` -`const` +`const` — Define default resource limits and settings for sandbox environments ```ts SandboxResourceConfig @@ -2232,7 +2232,7 @@ SandboxResourceConfig ### `DEFAULT_SEQUENCES_MCP_DESCRIPTION` -`const` +`const` — Describe live timeline editor features for current video sequence including clip and caption management ```ts "Live timeline editor for the current video sequence: read timeline state, place/move/trim/split clips, add captions, m… @@ -2240,7 +2240,7 @@ SandboxResourceConfig ### `DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR` -`const` +`const` — Define the default environment variable name for Tangle billing enforcement ```ts "TANGLE_BILLING_ENFORCEMENT" @@ -2248,7 +2248,7 @@ SandboxResourceConfig ### `DEFAULT_TANGLE_ROUTER_BASE_URL` -`const` +`const` — Provide the default base URL for the Tangle router API endpoint ```ts "https://router.tangle.tools/v1" @@ -2296,7 +2296,7 @@ SandboxResourceConfig ### `DeleteClipOperation` -`interface` +`interface` — Represent a delete clip operation with a specified clip identifier ```ts interface DeleteClipOperation @@ -2304,7 +2304,7 @@ interface DeleteClipOperation ### `DeleteElementOperation` -`interface` +`interface` — Resolve deletion of a specific element from a page by its identifiers ```ts interface DeleteElementOperation @@ -2312,7 +2312,7 @@ interface DeleteElementOperation ### `DeletePageOperation` -`interface` +`interface` — Represent a delete page operation with a specified page identifier ```ts interface DeletePageOperation @@ -2320,7 +2320,7 @@ interface DeletePageOperation ### `deleteSecret` -`function` +`function` — Delete a secret by name from the given secret store and return the operation outcome ```ts (store: SecretStore, name: string) => Promise> @@ -2352,7 +2352,7 @@ interface DeriveKeyOptions ### `DesignCanvasMcpServerInfo` -`interface` +`interface` — Describe design canvas MCP server information including name and version ```ts interface DesignCanvasMcpServerInfo @@ -2360,7 +2360,7 @@ interface DesignCanvasMcpServerInfo ### `DesignCanvasMcpToolEnv` -`interface` +`interface` — Define the environment for MCP tool with a scene store and ID minting function ```ts interface DesignCanvasMcpToolEnv @@ -2368,7 +2368,7 @@ interface DesignCanvasMcpToolEnv ### `detectInteractiveQuestion` -`function` +`function` — Resolve the interactive question text from a structured event or return null if none found ```ts (event: unknown) => string | null @@ -2392,7 +2392,7 @@ interface DesignCanvasMcpToolEnv ### `DispatchOptions` -`interface` +`interface` — Define options for dispatching tools including handlers, taxonomy, custom tools, and approval policies ```ts interface DispatchOptions @@ -2400,7 +2400,7 @@ interface DispatchOptions ### `DistributionSummary` -`interface` +`interface` — Summarize key statistics of a numerical distribution including count, min, percentiles, and max ```ts interface DistributionSummary @@ -2408,7 +2408,7 @@ interface DistributionSummary ### `driveSandboxTurn` -`function` +`function` — Resolve a sandbox turn by processing a message with given configuration and options ```ts (shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options: DriveSandboxTurnOptio… @@ -2416,7 +2416,7 @@ interface DistributionSummary ### `DriveSandboxTurnOptions` -`interface` +`interface` — Define options to manage deterministic session resumption and turn idempotency in sandboxed drive turns ```ts interface DriveSandboxTurnOptions @@ -2440,7 +2440,7 @@ interface DrizzleSqliteCoreLike ### `DuplicatePageOperation` -`interface` +`interface` — Define an operation to duplicate a page with a new caller-specified page ID ```ts interface DuplicatePageOperation @@ -2448,7 +2448,7 @@ interface DuplicatePageOperation ### `DurableAnswerIntentJournal` -`type` +`type` — Provide durable methods to manage the lifecycle of answer intents in a plan store ```ts type DurableAnswerIntentJournal @@ -2456,7 +2456,7 @@ type DurableAnswerIntentJournal ### `DurableAnswerIntentRecord` -`interface` +`interface` — Define the structure for recording durable answer intent details and their states ```ts interface DurableAnswerIntentRecord @@ -2464,7 +2464,7 @@ interface DurableAnswerIntentRecord ### `DurableAnswerIntentState` -`type` +`type` — Define possible states for a durable answer intent lifecycle ```ts type DurableAnswerIntentState @@ -2472,7 +2472,7 @@ type DurableAnswerIntentState ### `DurableChatConflictError` -`class` +`class` — Represent conflict errors occurring in durable chat state management ```ts class DurableChatConflictError @@ -2488,7 +2488,7 @@ class DurableChatError ### `DurableChatErrorCode` -`type` +`type` — Define error codes representing possible Durable Chat failure scenarios ```ts type DurableChatErrorCode @@ -2496,7 +2496,7 @@ type DurableChatErrorCode ### `DurableChatEventProjection` -`interface` +`interface` — Resolve chat events and materialize their state into durable records ```ts interface DurableChatEventProjection @@ -2504,7 +2504,7 @@ interface DurableChatEventProjection ### `DurableChatGoneError` -`class` +`class` — Represent durable chat errors indicating the chat plan is no longer available ```ts class DurableChatGoneError @@ -2520,7 +2520,7 @@ type DurableChatScope ### `durableChatScopeKey` -`function` +`function` — Resolve a valid durable chat scope key from the given scope input ```ts (scope: DurableChatScope) => string @@ -2536,7 +2536,7 @@ type DurableChatStateStore ### `DurableChatUnavailableError` -`class` +`class` — Represent unavailable durable chat authority errors with status code 503 ```ts class DurableChatUnavailableError @@ -2544,7 +2544,7 @@ class DurableChatUnavailableError ### `DurableFollowUpReceipt` -`interface` +`interface` — Define a durable receipt capturing stable identifiers and state for follow-up decisions ```ts interface DurableFollowUpReceipt @@ -2552,7 +2552,7 @@ interface DurableFollowUpReceipt ### `DurableInteractionAcknowledgement` -`interface` +`interface` — Represent durable acknowledgement of an interaction with optional authority, status, and timestamp fields ```ts interface DurableInteractionAcknowledgement @@ -2560,7 +2560,7 @@ interface DurableInteractionAcknowledgement ### `DurableInteractionGuarantee` -`type` +`type` — Define interaction durability levels to specify reconciliation or best-effort guarantees ```ts type DurableInteractionGuarantee @@ -2576,7 +2576,7 @@ type DurableInteractionGuarantee ### `DurableInteractionProjection` -`interface` +`interface` — Define a durable chat interaction projection with idempotent event tracking and optional tombstone flag ```ts interface DurableInteractionProjection @@ -2584,7 +2584,7 @@ interface DurableInteractionProjection ### `DurableInteractionProjectionAdapter` -`interface` +`interface` — Define methods to manage durable interaction projections including upsert, cancel, and materialize operations ```ts interface DurableInteractionProjectionAdapter @@ -2592,7 +2592,7 @@ interface DurableInteractionProjectionAdapter ### `DurableInteractionRouteArgs` -`interface` +`interface` — Define arguments for durable interaction routes including a stable caller-created attempt key ```ts interface DurableInteractionRouteArgs @@ -2608,7 +2608,7 @@ interface DurableInteractionRoutePersistence ### `DurableInteractionSettlement` -`interface` +`interface` — Manage durable interaction lifecycles by preparing, acknowledging, finalizing, aborting, and reconciling intents ```ts interface DurableInteractionSettlement @@ -2616,7 +2616,7 @@ interface DurableInteractionSettlement ### `DurableInteractionSettlementFactoryOptions` -`interface` +`interface` — Define options for creating durable interaction settlement factories including store and optional reconcile authority ```ts interface DurableInteractionSettlementFactoryOptions @@ -2624,7 +2624,7 @@ interface DurableInteractionSettlementFactoryOptions ### `DurableInteractionSettlementOptions` -`interface` +`interface` — Define options for durable interaction settlement including attempt key, guarantee, and timestamp provider ```ts interface DurableInteractionSettlementOptions @@ -2640,7 +2640,7 @@ interface DurablePlanAuthority ### `DurablePlanAuthorityCurrentResult` -`interface` +`interface` — Represent the current authoritative state and optional receipt of a durable plan authority ```ts interface DurablePlanAuthorityCurrentResult @@ -2648,7 +2648,7 @@ interface DurablePlanAuthorityCurrentResult ### `DurablePlanAuthorityDecision` -`type` +`type` — Resolve durable plan authority decisions including approval, rejection, or predefined durable decisions ```ts type DurablePlanAuthorityDecision @@ -2656,7 +2656,7 @@ type DurablePlanAuthorityDecision ### `DurablePlanAuthorityResult` -`interface` +`interface` — Describe the outcome of an authority's durable plan decision including follow-up and metadata ```ts interface DurablePlanAuthorityResult @@ -2664,7 +2664,7 @@ interface DurablePlanAuthorityResult ### `DurablePlanAuthorization` -`type` +`type` — Resolve authorization status for durable plans using scopes, responses, or nullish values ```ts type DurablePlanAuthorization @@ -2672,7 +2672,7 @@ type DurablePlanAuthorization ### `DurablePlanCommandJournal` -`type` +`type` — Pick essential methods to manage and record durable plan command operations ```ts type DurablePlanCommandJournal @@ -2680,7 +2680,7 @@ type DurablePlanCommandJournal ### `DurablePlanCommandKey` -`type` +`type` — Represent a unique identifier key for durable plan commands ```ts type DurablePlanCommandKey @@ -2688,7 +2688,7 @@ type DurablePlanCommandKey ### `DurablePlanCommandRecord` -`interface` +`interface` — Define the structure for recording durable plan commands with associated metadata and state information ```ts interface DurablePlanCommandRecord @@ -2696,7 +2696,7 @@ interface DurablePlanCommandRecord ### `DurablePlanCommandState` -`type` +`type` — Define possible states for a durable plan command in its lifecycle ```ts type DurablePlanCommandState @@ -2704,7 +2704,7 @@ type DurablePlanCommandState ### `DurablePlanDecision` -`type` +`type` — Represent durable plan outcomes as either approved or rejected ```ts type DurablePlanDecision @@ -2712,7 +2712,7 @@ type DurablePlanDecision ### `DurablePlanEffectRecord` -`interface` +`interface` — Define the structure for recording the state and metadata of a durable plan effect ```ts interface DurablePlanEffectRecord @@ -2728,7 +2728,7 @@ type DurablePlanProjection ### `DurablePlanRouteAuthorizeArgs` -`interface` +`interface` — Define arguments for authorizing durable plan route requests with operation and optional plan ID ```ts interface DurablePlanRouteAuthorizeArgs @@ -2736,7 +2736,7 @@ interface DurablePlanRouteAuthorizeArgs ### `DurablePlanRouteOptions` -`interface` +`interface` — Define options for durable plan routing including store, authority, authorization, and idempotent side effect handling ```ts interface DurablePlanRouteOptions @@ -2744,7 +2744,7 @@ interface DurablePlanRouteOptions ### `DurablePlanRoutes` -`interface` +`interface` — Define routes handling durable plan requests with current and decide methods ```ts interface DurablePlanRoutes @@ -2752,7 +2752,7 @@ interface DurablePlanRoutes ### `DurablePlanStateStore` -`type` +`type` — Represent durable storage for plan state management with persistence and reliability guarantees ```ts type DurablePlanStateStore @@ -2760,7 +2760,7 @@ type DurablePlanStateStore ### `DurablePlanStore` -`interface` +`interface` — Manage durable storage and retrieval of plan projections, commands, and effects within a scoped context ```ts interface DurablePlanStore @@ -2784,7 +2784,7 @@ interface DurablePlanStore ### `EllipseElement` -`interface` +`interface` — Define properties for an ellipse element including dimensions, fill, and optional stroke details ```ts interface EllipseElement @@ -2792,7 +2792,7 @@ interface EllipseElement ### `EmailBodySection` -`interface` +`interface` — Define the structure for the body section of an email containing plain text content ```ts interface EmailBodySection @@ -2800,7 +2800,7 @@ interface EmailBodySection ### `EmailContent` -`interface` +`interface` — Define the structure for email content including subject, optional preheader, and sections ```ts interface EmailContent @@ -2808,7 +2808,7 @@ interface EmailContent ### `EmailContentSchema` -`const` +`const` — Validate and parse email content objects with subject, optional preheader, and sections ```ts ZodObject<{ subject: ZodString; preheader: ZodOptional; sections: ZodArray; sections: Zod ### `EmailCtaSection` -`interface` +`interface` — Define a call-to-action section with label, URL, and optional subtext for email content ```ts interface EmailCtaSection @@ -2824,7 +2824,7 @@ interface EmailCtaSection ### `EmailDividerSection` -`interface` +`interface` — Define a section representing a divider in an email layout ```ts interface EmailDividerSection @@ -2832,7 +2832,7 @@ interface EmailDividerSection ### `EmailFeatureSection` -`interface` +`interface` — Define a feature section with headline, description, and optional image for email content ```ts interface EmailFeatureSection @@ -2840,7 +2840,7 @@ interface EmailFeatureSection ### `EmailHeroSection` -`interface` +`interface` — Define the structure for a hero section in an email with headline, image, and call-to-action fields ```ts interface EmailHeroSection @@ -2848,7 +2848,7 @@ interface EmailHeroSection ### `EmailSection` -`type` +`type` — Define a union type representing different sections of an email template ```ts type EmailSection @@ -2856,7 +2856,7 @@ type EmailSection ### `EmailTestimonialSection` -`interface` +`interface` — Define the structure for an email testimonial section with quote, author, and optional details ```ts interface EmailTestimonialSection @@ -2864,7 +2864,7 @@ interface EmailTestimonialSection ### `encodeEvent` -`function` +`function` — Encode a StreamEvent object into a Uint8Array using the provided TextEncoder ```ts (encoder: TextEncoder, event: StreamEvent) => Uint8Array @@ -2872,7 +2872,7 @@ interface EmailTestimonialSection ### `encodeSandboxRuntimePath` -`function` +`function` — Encode a runtime path by URI-encoding each valid segment and returning null for invalid segments ```ts (runtimePath: string) => string | null @@ -2904,7 +2904,7 @@ interface EmailTestimonialSection ### `ensureWorkspaceSandbox` -`function` +`function` — Resolve or create a workspace sandbox instance with optional reuse and progress tracking ```ts (shell: SandboxRuntimeConfig, options: EnsureWorkspaceSandboxOptions) => Promise @@ -2912,7 +2912,7 @@ interface EmailTestimonialSection ### `EnsureWorkspaceSandboxOptions` -`interface` +`interface` — Define options for ensuring a workspace sandbox with provisioning and progress handling ```ts interface EnsureWorkspaceSandboxOptions @@ -2936,7 +2936,7 @@ interface EnsureWorkspaceSandboxOptions ### `estimateTextHeight` -`function` +`function` — Estimate the height of multiline text based on font size and line height ```ts (element: Pick) => number @@ -2944,7 +2944,7 @@ interface EnsureWorkspaceSandboxOptions ### `ExpiringCapabilityTokenOptions` -`interface` +`interface` — Define options for capability tokens that expire after a specified lifetime in milliseconds ```ts interface ExpiringCapabilityTokenOptions @@ -2952,7 +2952,7 @@ interface ExpiringCapabilityTokenOptions ### `EXPORT_PRESETS` -`const` +`const` — Provide predefined export configurations for various social media and image formats ```ts Record @@ -2960,7 +2960,7 @@ Record ### `ExportCropRect` -`interface` +`interface` — Define crop rectangle coordinates and dimensions for exporting content within page bounds ```ts interface ExportCropRect @@ -2968,7 +2968,7 @@ interface ExportCropRect ### `ExportFormat` -`type` +`type` — Define supported image export formats as PNG or JPEG ```ts type ExportFormat @@ -2984,7 +2984,7 @@ interface ExportPreset ### `ExtendSequenceOperation` -`interface` +`interface` — Define an operation to extend a sequence by a specified number of frames ```ts interface ExtendSequenceOperation @@ -3016,7 +3016,7 @@ interface ExtendSequenceOperation ### `fieldAcceptsFreeText` -`function` +`function` — Determine if a chat interaction field allows free text input ```ts (field: ChatInteractionField) => boolean @@ -3024,7 +3024,7 @@ interface ExtendSequenceOperation ### `finalizeAssistantParts` -`function` +`function` — Resolve and clean up assistant parts by terminalizing and collapsing redundant segments ```ts (partOrder: string[], partMap: Map, finalText: string) => JsonRecord[] @@ -3040,7 +3040,7 @@ interface ExtendSequenceOperation ### `findCanvasMcpTool` -`function` +`function` — Find the canvas MCP tool definition matching the given name or return undefined ```ts (name: string) => McpToolDefinition | undefined @@ -3064,7 +3064,7 @@ interface ExtendSequenceOperation ### `findPreset` -`function` +`function` — Resolve a size preset by its identifier or return null if not found ```ts (id: string) => SizePreset | null @@ -3072,7 +3072,7 @@ interface ExtendSequenceOperation ### `findSequenceMcpTool` -`function` +`function` — Resolve the SequenceMcpToolDefinition matching the given name or return undefined ```ts (name: string) => SequenceMcpToolDefinition | undefined @@ -3080,7 +3080,7 @@ interface ExtendSequenceOperation ### `flattenHistory` -`function` +`function` — Build a single string combining conversation history and the current user message ```ts (message: string, history?: { role: "user" | "assistant"; content: string; }[] | undefined) => string @@ -3096,7 +3096,7 @@ interface FlowSpan ### `FlowTrace` -`interface` +`interface` — Describe the structure of a flow trace including spans, timing, tokens, cost, and tool calls ```ts interface FlowTrace @@ -3112,7 +3112,7 @@ interface FlowTrace ### `formatSeconds` -`function` +`function` — Format a number of seconds into a string with integer or two-decimal precision suffix s ```ts (seconds: number) => string @@ -3128,7 +3128,7 @@ interface FlowTrace ### `framesToSeconds` -`function` +`function` — Convert a frame count to seconds based on the given frames per second rate ```ts (frames: number, fps: number) => number @@ -3136,7 +3136,7 @@ interface FlowTrace ### `getClient` -`function` +`function` — Resolve a synchronous sandbox client from provided runtime configuration credentials ```ts (shell: SandboxRuntimeConfig) => SandboxClient @@ -3144,7 +3144,7 @@ interface FlowTrace ### `getPartKey` -`function` +`function` — Resolve a unique key string for a part based on its type and identifying properties ```ts (part: JsonRecord) => string @@ -3152,7 +3152,7 @@ interface FlowTrace ### `GroupElement` -`interface` +`interface` — Define a group element that contains multiple child scene elements ```ts interface GroupElement @@ -3160,7 +3160,7 @@ interface GroupElement ### `GroupElementsOperation` -`interface` +`interface` — Group elements by grouping two or more sibling elements in their current z-order under a new group ID ```ts interface GroupElementsOperation @@ -3176,7 +3176,7 @@ interface GroupElementsOperation ### `HandleToolRequestOptions` -`interface` +`interface` — Define options for handling tool requests including tool identification and token verification ```ts interface HandleToolRequestOptions @@ -3184,7 +3184,7 @@ interface HandleToolRequestOptions ### `Harness` -`type` +`type` — Resolve a valid harness identifier from the predefined KNOWN_HARNESSES array ```ts type Harness @@ -3208,7 +3208,7 @@ type Harness ### `HttpHeadProbeConfig` -`interface` +`interface` — Define configuration options for performing an HTTP HEAD probe to check URL availability ```ts interface HttpHeadProbeConfig @@ -3224,7 +3224,7 @@ class HubExecClient ### `HubExecClientOptions` -`interface` +`interface` — Define configuration options for initializing a Hub execution client ```ts interface HubExecClientOptions @@ -3248,7 +3248,7 @@ type HubExecResult ### `HubInvokeDeps` -`interface` +`interface` — Define dependencies for invoking hub operations including API key resolution and optional configuration ```ts interface HubInvokeDeps @@ -3256,7 +3256,7 @@ interface HubInvokeDeps ### `HubInvokeInput` -`interface` +`interface` — Define input parameters for invoking a hub tool with user ID, tool name, and optional arguments ```ts interface HubInvokeInput @@ -3264,7 +3264,7 @@ interface HubInvokeInput ### `HubInvokeOutcome` -`interface` +`interface` — Describe the outcome of a hub invocation including status and response body ```ts interface HubInvokeOutcome @@ -3272,7 +3272,7 @@ interface HubInvokeOutcome ### `ImageBackground` -`type` +`type` — Define image background styles as color, gradient, or image with optional overlay settings ```ts type ImageBackground @@ -3280,7 +3280,7 @@ type ImageBackground ### `ImageContent` -`interface` +`interface` — Define the structure for image content containing an array of image slides ```ts interface ImageContent @@ -3288,7 +3288,7 @@ interface ImageContent ### `ImageContentSchema` -`const` +`const` — Validate image content with an array of one or more slides containing background details ```ts ZodObject<{ slides: ZodArray; valu… @@ -3296,7 +3296,7 @@ ZodObject<{ slides: ZodArray string @@ -3544,7 +3544,7 @@ type InteractionRequestWire ### `InteractionRouteLogger` -`type` +`type` — Provide logging methods for warnings and errors in interaction routes ```ts type InteractionRouteLogger @@ -3568,7 +3568,7 @@ type InteractionRouteLogger ### `isAppToolName` -`function` +`function` — Determine if a string matches a valid application tool name ```ts (name: string) => name is "submit_proposal" | "schedule_followup" | "render_ui" | "add_citation" @@ -3584,7 +3584,7 @@ type InteractionRouteLogger ### `isChatInteractionPart` -`function` +`function` — Resolve whether a ChatMessagePart is a ChatInteractionPart based on its type property ```ts (part: ChatMessagePart) => part is ChatInteractionPart @@ -3600,7 +3600,7 @@ type InteractionRouteLogger ### `isChatPlanPart` -`function` +`function` — Resolve whether a chat message part is a persisted chat plan part ```ts (part: ChatMessagePart) => part is ChatPlanPersistedPart @@ -3608,7 +3608,7 @@ type InteractionRouteLogger ### `isChatStepFinishPart` -`function` +`function` — Determine if a chat message part represents the completion of a chat step ```ts (part: ChatMessagePart) => part is ChatStepFinishPart @@ -3616,7 +3616,7 @@ type InteractionRouteLogger ### `isChatTextPart` -`function` +`function` — Resolve whether a chat message part is a text part based on its type property ```ts (part: ChatMessagePart) => part is ChatTextPart @@ -3624,7 +3624,7 @@ type InteractionRouteLogger ### `isChatToolPart` -`function` +`function` — Resolve whether a ChatMessagePart is specifically a ChatToolPart based on its type property ```ts (part: ChatMessagePart) => part is ChatToolPart @@ -3632,7 +3632,7 @@ type InteractionRouteLogger ### `isHarness` -`function` +`function` — Determine if a value is a recognized harness string identifier ```ts (value: unknown) => value is "opencode" | "claude-code" | "nanoclaw" | "kimi-code" | "codex" | "amp" | "factory-droids"… @@ -3664,7 +3664,7 @@ type InteractionRouteLogger ### `isRenderableInteractionKind` -`function` +`function` — Resolve if the given interaction kind is renderable within the application context ```ts (kind: string) => boolean @@ -3696,7 +3696,7 @@ type InteractionRouteLogger ### `isTangleExecutionKeyError` -`function` +`function` — Identify whether an error is a TangleExecutionKeyError based on its properties and type ```ts (error: unknown) => error is TangleExecutionKeyError @@ -3704,7 +3704,7 @@ type InteractionRouteLogger ### `isTerminalInteractionStatus` -`function` +`function` — Resolve if the interaction status is a terminal state excluding pending ```ts (status: ChatInteractionStatus) => boolean @@ -3712,7 +3712,7 @@ type InteractionRouteLogger ### `isTerminalPromptEvent` -`function` +`function` — Determine if an event is a terminal prompt event with type 'result' or 'done ```ts (event: unknown) => boolean @@ -3728,7 +3728,7 @@ type JsonObject ### `JsonRecord` -`type` +`type` — Represent a JSON-compatible object with string keys and values of any type ```ts type JsonRecord @@ -3768,7 +3768,7 @@ interface KnowledgeDecider ### `KnowledgeDeciderInput` -`interface` +`interface` — Define the input parameters required to decide knowledge proposals within an agent-knowledge loop ```ts interface KnowledgeDeciderInput @@ -3776,7 +3776,7 @@ interface KnowledgeDeciderInput ### `KnowledgeDecision` -`interface` +`interface` — Define a decision containing a candidate and the gate's verdict on that candidate ```ts interface KnowledgeDecision @@ -3816,7 +3816,7 @@ interface KnowledgeLoopDriver ### `KnowledgeRequirementSpec` -`interface` +`interface` — Define the criteria and conditions required to satisfy a specific knowledge requirement ```ts interface KnowledgeRequirementSpec @@ -3824,7 +3824,7 @@ interface KnowledgeRequirementSpec ### `KnowledgeSignal` -`interface` +`interface` — Define a signal representing knowledge with confidence level and optional supporting evidence ```ts interface KnowledgeSignal @@ -3864,7 +3864,7 @@ interface KvLike ### `LanguageFanoutOptions` -`interface` +`interface` — Define options to specify target languages and an optional source language for fan-out operations ```ts interface LanguageFanoutOptions @@ -3880,7 +3880,7 @@ interface LanguageFanoutOptions ### `lightTheme` -`const` +`const` — Define a light color theme with specific background, foreground, and accent color values ```ts AgentAppTheme @@ -3888,7 +3888,7 @@ AgentAppTheme ### `LineElement` -`interface` +`interface` — Define a line element with points, stroke, stroke width, and optional dash pattern ```ts interface LineElement @@ -3912,7 +3912,7 @@ interface LineElement ### `LivenessProbeConfig` -`interface` +`interface` — Define configuration for liveness probes including sidecar process pattern and optional timeouts ```ts interface LivenessProbeConfig @@ -4016,7 +4016,7 @@ readonly ["2025-06-18", "2025-03-26", "2024-11-05"] ### `McpProtocolVersion` -`type` +`type` — Resolve a valid protocol version from the predefined MCP_PROTOCOL_VERSIONS array ```ts type McpProtocolVersion @@ -4024,7 +4024,7 @@ type McpProtocolVersion ### `McpServerInfo` -`interface` +`interface` — Describe the structure of server information including name and version ```ts interface McpServerInfo @@ -4040,7 +4040,7 @@ interface McpToolDefinition ### `MemberSyncSeam` -`interface` +`interface` — Map workspace roles to corresponding sandbox permission levels ```ts interface MemberSyncSeam @@ -4064,7 +4064,7 @@ interface MemberSyncSeam ### `mergeExtraMcp` -`function` +`function` — Resolve conflicts and merge extra MCP profiles into the app tool MCP without overwriting existing keys ```ts (appToolMcp: Record, baseProfileMcp: Record, extra: Recor… @@ -4088,7 +4088,7 @@ interface MemberSyncSeam ### `mergePersistedPart` -`function` +`function` — Merge incoming JSON with existing persisted data, applying delta for text types when provided ```ts (existing: JsonRecord | undefined, incoming: JsonRecord, delta?: string | undefined) => JsonRecord @@ -4104,7 +4104,7 @@ interface MemberSyncSeam ### `messageHasTurnId` -`function` +`function` — Resolve whether a message contains any part with the specified turn ID ```ts (message: PersistedChatMessageForTurn, turnId: string) => boolean @@ -4128,7 +4128,7 @@ interface MemberSyncSeam ### `mintTerminalProxyToken` -`function` +`function` — Generate a signed token for TerminalProxyIdentity with an expiration based on TTL milliseconds ```ts (secret: string, identity: TerminalProxyIdentity, ttlMs?: number, now?: () => number) => Promise string | undefined @@ -4496,7 +4496,7 @@ MissionEventSink ### `normalizePersistedPart` -`function` +`function` — Normalize a persisted part object by standardizing its structure and fields ```ts (rawPart: JsonRecord) => JsonRecord | null @@ -4504,7 +4504,7 @@ MissionEventSink ### `normalizePlanDecision` -`function` +`function` — Normalize input value to a standardized DurablePlanDecision or return null for invalid inputs ```ts (value: unknown) => DurablePlanDecision | null @@ -4512,7 +4512,7 @@ MissionEventSink ### `normalizeTime` -`function` +`function` — Resolve time properties from various keys into a normalized record with numeric start and end fields ```ts (value: unknown) => JsonRecord | undefined @@ -4520,7 +4520,7 @@ MissionEventSink ### `normalizeToolEvent` -`function` +`function` — Normalize tool-related events into a standardized message.part.updated format ```ts (event: StreamEvent) => StreamEvent @@ -4528,7 +4528,7 @@ MissionEventSink ### `NoticeKind` -`type` +`type` — Define specific string literals representing different kinds of notices ```ts type NoticeKind @@ -4544,7 +4544,7 @@ type NoticeKind ### `noticePartKey` -`function` +`function` — Generate a unique key string for a notice using the given identifier ```ts (id: string) => string @@ -4552,7 +4552,7 @@ type NoticeKind ### `NoticePersistedPart` -`type` +`type` — Define a persisted notice part with type, id, kind, and text properties ```ts type NoticePersistedPart @@ -4592,7 +4592,7 @@ interface ObjectStore ### `OpenAICompatStreamTurnOptions` -`interface` +`interface` — Define options for configuring an OpenAI-compatible streaming chat turn including API details and tools ```ts interface OpenAICompatStreamTurnOptions @@ -4616,7 +4616,7 @@ interface OpenAIStreamChunk ### `OtioClip` -`interface` +`interface` — Define a clip object with metadata, source range, and media reference according to OTIO schema ```ts interface OtioClip @@ -4624,7 +4624,7 @@ interface OtioClip ### `OtioExternalReference` -`interface` +`interface` — Define the structure for an external media reference with schema, URL, and optional time range ```ts interface OtioExternalReference @@ -4632,7 +4632,7 @@ interface OtioExternalReference ### `OtioGap` -`interface` +`interface` — Define the structure for a gap element with schema, name, and source time range properties ```ts interface OtioGap @@ -4640,7 +4640,7 @@ interface OtioGap ### `OtioMissingReference` -`interface` +`interface` — Represent missing references in OTIO with a fixed schema identifier ```ts interface OtioMissingReference @@ -4648,7 +4648,7 @@ interface OtioMissingReference ### `OtioRationalTime` -`interface` +`interface` — Represent a rational time value with a specific rate and numeric value for OTIO schema ```ts interface OtioRationalTime @@ -4656,7 +4656,7 @@ interface OtioRationalTime ### `OtioStack` -`interface` +`interface` — Represent a stack container holding a named collection of OtioTrack children ```ts interface OtioStack @@ -4664,7 +4664,7 @@ interface OtioStack ### `OtioTimeline` -`interface` +`interface` — Define the structure of a timeline with metadata, tracks, and global start time in OTIO format ```ts interface OtioTimeline @@ -4672,7 +4672,7 @@ interface OtioTimeline ### `OtioTimeRange` -`interface` +`interface` — Define a time range with a start time and duration using OtioRationalTime values ```ts interface OtioTimeRange @@ -4680,7 +4680,7 @@ interface OtioTimeRange ### `OtioTrack` -`interface` +`interface` — Define a track containing video or audio clips with metadata and child elements ```ts interface OtioTrack @@ -4688,7 +4688,7 @@ interface OtioTrack ### `Outcome` -`type` +`type` — Represent success or failure of an operation with corresponding value or error information ```ts type Outcome @@ -4736,7 +4736,7 @@ interface ParsedIntegrationAction ### `ParsedMission` -`interface` +`interface` — Describe a mission with a title and an ordered list of parsed steps ```ts interface ParsedMission @@ -4744,7 +4744,7 @@ interface ParsedMission ### `ParsedMissionStep` -`interface` +`interface` — Define the structure representing a parsed mission step with id, kind, and intent fields ```ts interface ParsedMissionStep @@ -4760,7 +4760,7 @@ interface ParsedMissionStep ### `ParseInteractionAnswersResult` -`type` +`type` — Resolve the result of parsing interaction answers with success status and corresponding data or error message ```ts type ParseInteractionAnswersResult @@ -4768,7 +4768,7 @@ type ParseInteractionAnswersResult ### `parseInteractionCancel` -`function` +`function` — Parse interaction cancel data and return success status with parsed value or error message ```ts (data: Record | undefined) => { succeeded: true; value: InteractionCancelData; } | { succeeded: false;… @@ -4784,7 +4784,7 @@ type ParseInteractionAnswersResult ### `ParseInteractionResult` -`type` +`type` — Resolve interaction parsing outcome as success with value or failure with error message ```ts type ParseInteractionResult @@ -4808,7 +4808,7 @@ type ParseInteractionResult ### `ParseMissionBlocksOptions` -`interface` +`interface` — Define options to specify allowed lowercase step kinds for parsing mission blocks ```ts interface ParseMissionBlocksOptions @@ -4824,7 +4824,7 @@ interface ParseMissionBlocksOptions ### `ParsePlanSubmittedResult` -`type` +`type` — Resolve the result of parsing a plan submission into success with value or failure with error ```ts type ParsePlanSubmittedResult @@ -4864,7 +4864,7 @@ type PeekWorkspaceSandboxOutcome ### `PersistedChatMessageForTurn` -`interface` +`interface` — Define the structure of a chat message stored for a specific conversation turn ```ts interface PersistedChatMessageForTurn @@ -4880,7 +4880,7 @@ interface PersistedChatMessageForTurn ### `persistedPartToPlan` -`function` +`function` — Resolve a persisted part object into a ChatPlan or return null if the type is not 'plan ```ts (part: Record) => ChatPlan | null @@ -4888,7 +4888,7 @@ interface PersistedChatMessageForTurn ### `PlaceClipOperation` -`interface` +`interface` — Define an operation to place a media clip with timing, track, and playback options ```ts interface PlaceClipOperation @@ -4904,7 +4904,7 @@ interface PlaceClipOperation ### `planAuthorityIdempotencyKey` -`function` +`function` — Generate a unique idempotency key for a plan authority based on scope, plan, revision, and decision ```ts (scope: DurableChatScope, planId: string, revision: number, decision: DurablePlanDecision) => string @@ -4912,7 +4912,7 @@ interface PlaceClipOperation ### `planCommandKey` -`function` +`function` — Generate a unique key string for a plan command using plan ID, revision, and decision ```ts (planId: string, revision: number, decision: DurablePlanDecision) => string @@ -4920,7 +4920,7 @@ interface PlaceClipOperation ### `planEffectKey` -`function` +`function` — Generate a unique string key representing the effect of a plan decision within a given scope and revision ```ts (scope: DurableChatScope, planId: string, revision: number, decision: DurablePlanDecision) => string @@ -4928,7 +4928,7 @@ interface PlaceClipOperation ### `planFollowUpTurnId` -`function` +`function` — Generate a unique follow-up turn ID based on the plan ID and its outcome ```ts (planId: string, outcome: "approved" | "rejected") => string @@ -4960,7 +4960,7 @@ type PlanOutcome ### `planPartKey` -`function` +`function` — Generate a unique key string for a given plan identifier ```ts (planId: string) => string @@ -4968,7 +4968,7 @@ type PlanOutcome ### `planRevisionKey` -`function` +`function` — Generate a unique key string for a plan based on its ID and revision number ```ts (planId: string, revision: number) => string @@ -4976,7 +4976,7 @@ type PlanOutcome ### `planToPersistedPart` -`function` +`function` — Resolve a ChatPlan into its persisted part representation for storage or transmission ```ts (plan: ChatPlan) => ChatPlanPersistedPart @@ -4992,7 +4992,7 @@ interface PlatformBalanceInfo ### `PlatformBalanceManager` -`interface` +`interface` — Manage user plans and balances including state retrieval, billing authorization, deduction, and usage tracking ```ts interface PlatformBalanceManager @@ -5000,7 +5000,7 @@ interface PlatformBalanceManager ### `PlatformBalanceManagerOptions` -`interface` +`interface` — Define configuration options for managing platform balance based on billing plans ```ts interface PlatformBalanceManagerOptions @@ -5064,7 +5064,7 @@ interface PreflightReport ### `PreparedDurableInteractionAnswer` -`interface` +`interface` — Define a structured response containing scope, settlement, and intent for durable interactions ```ts interface PreparedDurableInteractionAnswer @@ -5088,7 +5088,7 @@ readonly string[] ### `PresetBillingOptions` -`interface` +`interface` — Define preset billing options including database, provisioner, encryption key, budget, and optional settings ```ts interface PresetBillingOptions @@ -5096,7 +5096,7 @@ interface PresetBillingOptions ### `PresetKnowledgeAccessorOptions` -`interface` +`interface` — Define options for accessing preset knowledge scoped to a specific workspace and configuration ```ts interface PresetKnowledgeAccessorOptions @@ -5104,7 +5104,7 @@ interface PresetKnowledgeAccessorOptions ### `PresetToolHandlerOptions` -`interface` +`interface` — Define configuration options for handling preset tools including database, vault, and optional utilities ```ts interface PresetToolHandlerOptions @@ -5128,7 +5128,7 @@ interface ProducedState ### `ProfileComposeOptions` -`interface` +`interface` — Define options for composing a user profile including prompts, files, servers, and name ```ts interface ProfileComposeOptions @@ -5136,7 +5136,7 @@ interface ProfileComposeOptions ### `PromptInputPart` -`type` +`type` — Extract a single element type from the array parameter of SandboxInstance's streamPrompt method ```ts type PromptInputPart @@ -5144,7 +5144,7 @@ type PromptInputPart ### `ProviderResolutionConfig` -`interface` +`interface` — Define configuration options for resolving a provider and its model with optional API keys and routing details ```ts interface ProviderResolutionConfig @@ -5184,7 +5184,7 @@ interface ProvisionProfileSection ### `PumpBufferedTurnOptions` -`interface` +`interface` — Define options to pump data from an asynchronous iterable source with buffered turn control ```ts interface PumpBufferedTurnOptions @@ -5208,7 +5208,7 @@ interface PutObjectOptions ### `QueueExportOperation` -`interface` +`interface` — Define the structure for a queue export operation with format and optional metadata ```ts interface QueueExportOperation @@ -5240,7 +5240,7 @@ interface R2LikeObjectHead ### `RateLimitResult` -`interface` +`interface` — Describe the outcome of a rate limit check including allowance, remaining count, and reset time ```ts interface RateLimitResult @@ -5264,7 +5264,7 @@ interface RateLimitResult ### `readSecret` -`function` +`function` — Resolve a secret value from the store by its name and return the outcome asynchronously ```ts (store: SecretStore, name: string) => Promise> @@ -5296,7 +5296,7 @@ interface RateLimitResult ### `RectElement` -`interface` +`interface` — Define a rectangular scene element with size, fill, optional stroke, and corner radius properties ```ts interface RectElement @@ -5312,7 +5312,7 @@ type RedactedDocSegment ### `RedactedDocument` -`interface` +`interface` — Define a document composed of multiple redacted content segments ```ts interface RedactedDocument @@ -5328,7 +5328,7 @@ interface RedactedDocument ### `RedactForIngestionOptions` -`interface` +`interface` — Define options to customize sensitive data redaction patterns and key names for ingestion ```ts interface RedactForIngestionOptions @@ -5368,7 +5368,7 @@ interface RedactionSpan ### `RenderUiArgs` -`interface` +`interface` — Define arguments required to render a UI including title and schema ```ts interface RenderUiArgs @@ -5376,7 +5376,7 @@ interface RenderUiArgs ### `RenderUiResult` -`interface` +`interface` — Describe the result of rendering UI including the artifact path and exact persisted content ```ts interface RenderUiResult @@ -5392,7 +5392,7 @@ interface RenderUiResult ### `ReorderElementOperation` -`interface` +`interface` — Resolve an operation to reorder an element within its current owner by specifying the target index ```ts interface ReorderElementOperation @@ -5400,7 +5400,7 @@ interface ReorderElementOperation ### `ReorderPageOperation` -`interface` +`interface` — Represent an operation to reorder a page by moving it to a specified index ```ts interface ReorderPageOperation @@ -5416,7 +5416,7 @@ interface ReorderPageOperation ### `ReplayTurnEventsOptions` -`interface` +`interface` — Define options for replaying turn events with control over sequence, polling, and timeout ```ts interface ReplayTurnEventsOptions @@ -5424,7 +5424,7 @@ interface ReplayTurnEventsOptions ### `RequestContext` -`interface` +`interface` — Define the context of a request including IP address, user agent, timestamp, and request ID ```ts interface RequestContext @@ -5440,7 +5440,7 @@ interface RequestContext ### `requireElement` -`function` +`function` — Resolve and return the element, its owner array, and index from the page by element ID ```ts (page: ScenePage, elementId: string) => { element: SceneElement; owner: SceneElement[]; index: number; } @@ -5448,7 +5448,7 @@ interface RequestContext ### `requirePage` -`function` +`function` — Resolve and return a page by ID from a document or throw an error if not found ```ts (document: SceneDocument, pageId: string) => ScenePage @@ -5464,7 +5464,7 @@ interface RequestContext ### `resetClientCache` -`function` +`function` — Reset the client cache to clear stored data and force fresh retrieval ```ts () => void @@ -5488,7 +5488,7 @@ interface RequestContext ### `resolveChatTurn` -`function` +`function` — Resolve a chat turn by determining message reuse and constructing user message parts ```ts (input: { existingMessages: PersistedChatMessageForTurn[]; userContent: string; turnId?: string | undefined; }) => Reso… @@ -5504,7 +5504,7 @@ interface ResolvedAgentProfile ### `ResolvedChatTurn` -`interface` +`interface` — Represent a chat turn with resolved user message insertion and prior message context ```ts interface ResolvedChatTurn @@ -5512,7 +5512,7 @@ interface ResolvedChatTurn ### `ResolvedModel` -`interface` +`interface` — Represent a fully configured model with optional API key and base URL for sandbox platform integration ```ts interface ResolvedModel @@ -5520,7 +5520,7 @@ interface ResolvedModel ### `ResolvedSessionHarness` -`interface` +`interface` — Represent resolved session state including harness, lock status, and swap attempt flag ```ts interface ResolvedSessionHarness @@ -5528,7 +5528,7 @@ interface ResolvedSessionHarness ### `ResolvedTangleExecutionKey` -`interface` +`interface` — Define a resolved key combining an API key with its Tangle execution source ```ts interface ResolvedTangleExecutionKey @@ -5536,7 +5536,7 @@ interface ResolvedTangleExecutionKey ### `ResolvedToolCapabilities` -`interface` +`interface` — Describe resolved capabilities including proposal types and product tool groups to expose ```ts interface ResolvedToolCapabilities @@ -5552,7 +5552,7 @@ interface ResolvedToolCapabilities ### `ResolveInteractionConnectionArgs` -`interface` +`interface` — Define arguments required to resolve interaction connections based on request and intent ```ts interface ResolveInteractionConnectionArgs @@ -5560,7 +5560,7 @@ interface ResolveInteractionConnectionArgs ### `resolveModel` -`function` +`function` — Resolve and return the appropriate model configuration based on provider settings and optional overrides ```ts (config: ProviderResolutionConfig | undefined, override?: { model?: string | undefined; modelApiKey?: string | undefine… @@ -5568,7 +5568,7 @@ interface ResolveInteractionConnectionArgs ### `ResolveModelOptions` -`interface` +`interface` — Resolve options for model configuration including environment variables and default router base URL ```ts interface ResolveModelOptions @@ -5584,7 +5584,7 @@ interface ResolveModelOptions ### `resolveSandboxClientCredentials` -`function` +`function` — Resolve sandbox client credentials based on environment and provided options asynchronously ```ts (options?: ResolveSandboxClientCredentialsOptions) => Promise @@ -5592,7 +5592,7 @@ interface ResolveModelOptions ### `ResolveSandboxClientCredentialsOptions` -`interface` +`interface` — Resolve options for obtaining sandbox client credentials from environment variables and classification ```ts interface ResolveSandboxClientCredentialsOptions @@ -5608,7 +5608,7 @@ interface ResolveSandboxClientCredentialsOptions ### `ResolveSessionHarnessInput` -`interface` +`interface` — Resolve input options to determine the appropriate session harness to use ```ts interface ResolveSessionHarnessInput @@ -5624,7 +5624,7 @@ interface ResolveSessionHarnessInput ### `ResolveTangleDevOrUserKeyOptions` -`interface` +`interface` — Resolve options for retrieving a Tangle developer or user API key based on environment and context ```ts interface ResolveTangleDevOrUserKeyOptions @@ -5632,7 +5632,7 @@ interface ResolveTangleDevOrUserKeyOptions ### `resolveTangleExecutionEnvironment` -`function` +`function` — Resolve the current Tangle execution environment based on provided or process environment variables ```ts (env?: Record) => TangleExecutionEnvironment @@ -5656,7 +5656,7 @@ interface ResolveTangleDevOrUserKeyOptions ### `ResolveToolCapabilitiesOptions` -`interface` +`interface` — Resolve options for determining tool capabilities based on taxonomy, capabilities, and enabled IDs ```ts interface ResolveToolCapabilitiesOptions @@ -5664,7 +5664,7 @@ interface ResolveToolCapabilitiesOptions ### `resolveToolId` -`function` +`function` — Resolve a unique tool identifier from various possible properties or generate a fallback ID ```ts (part: JsonRecord) => string @@ -5672,7 +5672,7 @@ interface ResolveToolCapabilitiesOptions ### `resolveToolName` -`function` +`function` — Resolve the tool name from a JSON record using tool, name, or a default value ```ts (part: JsonRecord) => string @@ -5688,7 +5688,7 @@ interface ResolveToolCapabilitiesOptions ### `resolveUserTangleExecutionKeyForUser` -`function` +`function` — Resolve the Tangle execution key for a specified user using provided environment and API key options ```ts (opts: ResolveUserTangleExecutionKeyForUserOptions) => Promise @@ -5696,7 +5696,7 @@ interface ResolveToolCapabilitiesOptions ### `ResolveUserTangleExecutionKeyForUserOptions` -`interface` +`interface` — Resolve options for retrieving a user's Tangle execution key with environment and API key access parameters ```ts interface ResolveUserTangleExecutionKeyForUserOptions @@ -5704,7 +5704,7 @@ interface ResolveUserTangleExecutionKeyForUserOptions ### `ResolveUserTangleExecutionKeyOptions` -`interface` +`interface` — Resolve options for retrieving user API keys within a specific Tangle execution environment ```ts interface ResolveUserTangleExecutionKeyOptions @@ -5736,7 +5736,7 @@ class RetryableStepError ### `RevealResult` -`interface` +`interface` — Describe the outcome of a reveal operation including success status, value, and failure reason ```ts interface RevealResult @@ -5752,7 +5752,7 @@ interface RevealResult ### `RevealSpanOptions` -`interface` +`interface` — Define options to decrypt, authorize, and audit the reveal of a span segment ```ts interface RevealSpanOptions @@ -5776,7 +5776,7 @@ interface RevealSpanOptions ### `RouterChatProbeConfig` -`interface` +`interface` — Define configuration options for probing an LLM router with authentication and model details ```ts interface RouterChatProbeConfig @@ -5808,7 +5808,7 @@ interface RouterModel ### `runSandboxPrompt` -`function` +`function` — Resolve a sandbox prompt by streaming and aggregating message parts into a complete string ```ts (shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options?: StreamSandboxPromptO… @@ -5816,7 +5816,7 @@ interface RouterModel ### `runSandboxToolPathSetup` -`function` +`function` — Resolve the sandbox environment PATH setup by executing the configuration script with given options ```ts (box: SandboxInstance, options: SandboxToolPathOptions) => Promise> @@ -5832,7 +5832,7 @@ type RuntimeEventLike ### `RuntimeExecutorOptions` -`interface` +`interface` — Define options for executing runtime tasks with a trusted per-turn context ```ts interface RuntimeExecutorOptions @@ -5848,7 +5848,7 @@ interface RuntimeExecutorOptions ### `SandboxApiCredentials` -`interface` +`interface` — Define credentials required to access the sandbox API environment ```ts interface SandboxApiCredentials @@ -5864,7 +5864,7 @@ interface SandboxApiCredentials ### `SandboxAuthProbeConfig` -`interface` +`interface` — Define configuration options for probing sandbox authentication endpoints ```ts interface SandboxAuthProbeConfig @@ -5872,7 +5872,7 @@ interface SandboxAuthProbeConfig ### `SandboxBuildContext` -`interface` +`interface` — Define the context for building a sandbox including workspace, integrations, and optional user ID ```ts interface SandboxBuildContext @@ -5880,7 +5880,7 @@ interface SandboxBuildContext ### `SandboxClientCredentials` -`interface` +`interface` — Define client credentials for accessing the sandbox environment with API key and base URL ```ts interface SandboxClientCredentials @@ -5904,7 +5904,7 @@ type SandboxDispatch ### `SandboxDispatchDoneResult` -`interface` +`interface` — Define the result of a completed sandbox dispatch including artifact reference and optional cost details ```ts interface SandboxDispatchDoneResult @@ -5920,7 +5920,7 @@ interface SandboxDispatchInProgressResult ### `SandboxDispatchInput` -`interface` +`interface` — Define input parameters for dispatching a mission step in the sandbox environment ```ts interface SandboxDispatchInput @@ -5928,7 +5928,7 @@ interface SandboxDispatchInput ### `SandboxDispatchResult` -`type` +`type` — Resolve the result of a sandbox dispatch as done or in progress ```ts type SandboxDispatchResult @@ -5944,7 +5944,7 @@ interface SandboxExecChannel ### `SandboxExecOptions` -`interface` +`interface` — Define options to execute code within a sandbox environment with optional session control ```ts interface SandboxExecOptions @@ -5952,7 +5952,7 @@ interface SandboxExecOptions ### `SandboxFileBytesOutcome` -`type` +`type` — Represent the outcome of reading sandbox file bytes with success status and corresponding data or error ```ts type SandboxFileBytesOutcome @@ -5960,7 +5960,7 @@ type SandboxFileBytesOutcome ### `SandboxFileSizeOutcome` -`type` +`type` — Resolve the outcome of a sandbox file size check with success status and value or error message ```ts type SandboxFileSizeOutcome @@ -5968,7 +5968,7 @@ type SandboxFileSizeOutcome ### `SandboxPermissionLevel` -`type` +`type` — Define permission levels for sandbox access and control ```ts type SandboxPermissionLevel @@ -5976,7 +5976,7 @@ type SandboxPermissionLevel ### `SandboxResourceConfig` -`interface` +`interface` — Define configuration parameters for sandbox resource allocation and lifecycle management ```ts interface SandboxResourceConfig @@ -5984,7 +5984,7 @@ interface SandboxResourceConfig ### `SandboxRestoreSpec` -`interface` +`interface` — Define the specification for restoring a sandbox from a snapshot or another sandbox ID ```ts interface SandboxRestoreSpec @@ -5992,7 +5992,7 @@ interface SandboxRestoreSpec ### `SandboxRuntimeAuthRefreshError` -`class` +`class` — Represent an error thrown when sandbox runtime authentication refresh fails for a specific stage and name ```ts class SandboxRuntimeAuthRefreshError @@ -6000,7 +6000,7 @@ class SandboxRuntimeAuthRefreshError ### `SandboxRuntimeConfig` -`interface` +`interface` — Define runtime configuration methods for sandbox environments including credentials, metadata, and permissions ```ts interface SandboxRuntimeConfig @@ -6008,7 +6008,7 @@ interface SandboxRuntimeConfig ### `SandboxRuntimeConnection` -`interface` +`interface` — Define a connection configuration for sandbox runtime including URL and optional server-side auth token ```ts interface SandboxRuntimeConnection @@ -6016,7 +6016,7 @@ interface SandboxRuntimeConnection ### `SandboxScope` -`interface` +`interface` — Define a scope containing workspace and optional user identifiers for sandbox environments ```ts interface SandboxScope @@ -6024,7 +6024,7 @@ interface SandboxScope ### `SandboxStepTransition` -`type` +`type` — Define transitions marking the start or finish of a sandbox step with associated details ```ts type SandboxStepTransition @@ -6032,7 +6032,7 @@ type SandboxStepTransition ### `SandboxTerminalTokenOptions` -`interface` +`interface` — Define options for generating a sandbox terminal token including secret and expiration settings ```ts interface SandboxTerminalTokenOptions @@ -6040,7 +6040,7 @@ interface SandboxTerminalTokenOptions ### `SandboxTerminalTokenResult` -`interface` +`interface` — Provide token and expiration details for a sandbox terminal session ```ts interface SandboxTerminalTokenResult @@ -6048,7 +6048,7 @@ interface SandboxTerminalTokenResult ### `SandboxTerminalTokenSubject` -`type` +`type` — Resolve the identity type used for sandbox terminal token subjects ```ts type SandboxTerminalTokenSubject @@ -6056,7 +6056,7 @@ type SandboxTerminalTokenSubject ### `SandboxTerminalWsMatch` -`interface` +`interface` — Define the structure for matching a sandbox terminal WebSocket with workspace and path details ```ts interface SandboxTerminalWsMatch @@ -6064,7 +6064,7 @@ interface SandboxTerminalWsMatch ### `sandboxToolBinDir` -`function` +`function` — Resolve the binary directory path for a sandbox tool based on provided options ```ts (options: SandboxToolPathOptions) => string @@ -6072,7 +6072,7 @@ interface SandboxTerminalWsMatch ### `sandboxToolPath` -`function` +`function` — Resolve the file system path to a specified sandbox tool based on given options ```ts (options: SandboxToolPathOptions & { toolName: string; }) => string @@ -6080,7 +6080,7 @@ interface SandboxTerminalWsMatch ### `SandboxToolPathOptions` -`interface` +`interface` — Define options for resolving sandbox tool paths including appName, baseDir, and binDir ```ts interface SandboxToolPathOptions @@ -6088,7 +6088,7 @@ interface SandboxToolPathOptions ### `sandboxToolRootDir` -`function` +`function` — Resolve the root directory path for a sandbox tool based on provided options ```ts (options: SandboxToolPathOptions) => string @@ -6096,7 +6096,7 @@ interface SandboxToolPathOptions ### `SandboxToolSpec` -`interface` +`interface` — Define the specification for a sandbox tool including its name, content, and optional executability ```ts interface SandboxToolSpec @@ -6136,7 +6136,7 @@ type SatisfiedByRule ### `SCENE_ELEMENT_KINDS` -`const` +`const` — Define all valid kinds of scene elements used in the application ```ts readonly ("text" | "image" | "rect" | "video" | "ellipse" | "line" | "group")[] @@ -6144,7 +6144,7 @@ readonly ("text" | "image" | "rect" | "video" | "ellipse" | "line" | "group")[] ### `SCENE_OPERATION_TYPES` -`const` +`const` — Define all valid operation types for scene manipulation in the application ```ts readonly ("add_element" | "set_attrs" | "reorder_element" | "delete_element" | "group_elements" | "ungroup_element" | "… @@ -6152,7 +6152,7 @@ readonly ("add_element" | "set_attrs" | "reorder_element" | "delete_element" | " ### `SCENE_SCHEMA_VERSION` -`const` +`const` — Define the current version number of the scene schema ```ts 1 @@ -6160,7 +6160,7 @@ readonly ("add_element" | "set_attrs" | "reorder_element" | "delete_element" | " ### `SceneApplyResult` -`type` +`type` — Represent the result of applying changes to a scene as an element, page, or entire document ```ts type SceneApplyResult @@ -6176,7 +6176,7 @@ type SceneAttrsPatch ### `SceneDecision` -`interface` +`interface` — Define the structure for decisions made within a scene including type, instructions, and metadata ```ts interface SceneDecision @@ -6184,7 +6184,7 @@ interface SceneDecision ### `SceneDocument` -`interface` +`interface` — Define the structure and properties of a scene document including version, title, pages, settings, and metadata ```ts interface SceneDocument @@ -6192,7 +6192,7 @@ interface SceneDocument ### `SceneDocumentRecord` -`interface` +`interface` — Represent a scene document with its current revision number for version tracking ```ts interface SceneDocumentRecord @@ -6200,7 +6200,7 @@ interface SceneDocumentRecord ### `SceneElement` -`type` +`type` — Represent a graphical element in a scene including shapes, text, media, or groups ```ts type SceneElement @@ -6216,7 +6216,7 @@ interface SceneElementBase ### `SceneElementKind` -`type` +`type` — Extract the kind property from a SceneElement to identify its element type ```ts type SceneElementKind @@ -6224,7 +6224,7 @@ type SceneElementKind ### `SceneExportFormat` -`type` +`type` — Define supported formats for exporting a scene including image and JSON options ```ts type SceneExportFormat @@ -6232,7 +6232,7 @@ type SceneExportFormat ### `SceneExportRecord` -`interface` +`interface` — Describe a scene export with its status, format, metadata, and result information ```ts interface SceneExportRecord @@ -6240,7 +6240,7 @@ interface SceneExportRecord ### `SceneOperation` -`type` +`type` — Represent operations that modify scenes by adding, updating, reordering, grouping, or deleting elements and pages ```ts type SceneOperation @@ -6248,7 +6248,7 @@ type SceneOperation ### `SceneOperationType` -`type` +`type` — Extract the type property from a SceneOperation to represent its operation type ```ts type SceneOperationType @@ -6256,7 +6256,7 @@ type SceneOperationType ### `ScenePage` -`interface` +`interface` — Define the structure and properties of a scene page including layout, background, and elements ```ts interface ScenePage @@ -6264,7 +6264,7 @@ interface ScenePage ### `ScenePlan` -`interface` +`interface` — Define a plan summarizing a scene with its description and associated operations ```ts interface ScenePlan @@ -6272,7 +6272,7 @@ interface ScenePlan ### `SceneSettings` -`interface` +`interface` — Define settings for scene export including print conversion factor for unit calculations ```ts interface SceneSettings @@ -6280,7 +6280,7 @@ interface SceneSettings ### `SceneStore` -`interface` +`interface` — Manage scene documents, decisions, and exports with atomic save and revision control ```ts interface SceneStore @@ -6296,7 +6296,7 @@ interface SceneStoreScope ### `ScheduleFollowupArgs` -`interface` +`interface` — Define arguments required to schedule a follow-up with optional priority ```ts interface ScheduleFollowupArgs @@ -6304,7 +6304,7 @@ interface ScheduleFollowupArgs ### `ScheduleFollowupResult` -`interface` +`interface` — Define the result structure for scheduling a follow-up with unique identification and due date ```ts interface ScheduleFollowupResult @@ -6320,7 +6320,7 @@ interface ScopedMcpServerEntryOptions ### `ScopedTokenResult` -`interface` +`interface` — Represent a token with its expiration date and associated scope ```ts interface ScopedTokenResult @@ -6328,7 +6328,7 @@ interface ScopedTokenResult ### `secondsToFrames` -`function` +`function` — Convert seconds to the nearest whole number of frames based on frames per second ```ts (seconds: number, fps: number) => number @@ -6336,7 +6336,7 @@ interface ScopedTokenResult ### `SecretStore` -`interface` +`interface` — Define methods to create, update, retrieve, and delete secrets asynchronously ```ts interface SecretStore @@ -6344,7 +6344,7 @@ interface SecretStore ### `secretStoreFromClient` -`function` +`function` — Resolve a SecretStore interface using the provided SandboxRuntimeConfig shell ```ts (shell: SandboxRuntimeConfig) => SecretStore @@ -6352,7 +6352,7 @@ interface SecretStore ### `SecurityHeaderOptions` -`interface` +`interface` — Define options for configuring security-related HTTP headers including disclaimers and retention labels ```ts interface SecurityHeaderOptions @@ -6360,7 +6360,7 @@ interface SecurityHeaderOptions ### `SEQUENCE_EXPORT_FORMATS` -`const` +`const` — Define supported export formats for sequence outputs including video, subtitle, and metadata types ```ts readonly ["mp4", "otio", "xml", "edl", "vtt", "srt", "contact_sheet"] @@ -6368,7 +6368,7 @@ readonly ["mp4", "otio", "xml", "edl", "vtt", "srt", "contact_sheet"] ### `SEQUENCE_MCP_TOOLS` -`const` +`const` — Resolve an array of immutable sequence MCP tool definitions for timeline and frame operations ```ts readonly SequenceMcpToolDefinition[] @@ -6376,7 +6376,7 @@ readonly SequenceMcpToolDefinition[] ### `SEQUENCE_MEDIA_KINDS` -`const` +`const` — Define the allowed media kinds for sequences including video, image, and audio ```ts readonly ["video", "image", "audio"] @@ -6384,7 +6384,7 @@ readonly ["video", "image", "audio"] ### `SEQUENCE_OPERATION_TYPES` -`const` +`const` — List all valid sequence operation types used in editing workflows ```ts readonly ("place_clip" | "add_caption" | "move_clip" | "trim_clip" | "split_clip" | "set_clip_text" | "set_clip_disable… @@ -6392,7 +6392,7 @@ readonly ("place_clip" | "add_caption" | "move_clip" | "trim_clip" | "split_clip ### `SEQUENCE_TRACK_KINDS` -`const` +`const` — Define immutable sequence track kinds for video, audio, caption, reference, and agent ```ts readonly ["video", "audio", "caption", "reference", "agent"] @@ -6408,7 +6408,7 @@ type SequenceApplyResult ### `SequenceClip` -`interface` +`interface` — Define properties for a media sequence clip including timing, source, track, and caption details ```ts interface SequenceClip @@ -6424,7 +6424,7 @@ interface SequenceClipMedia ### `SequenceClipPatch` -`interface` +`interface` — Define optional properties to update or patch a sequence clip's attributes in a timeline ```ts interface SequenceClipPatch @@ -6440,7 +6440,7 @@ interface SequenceDecision ### `SequenceExportFormat` -`type` +`type` — Define export formats available for sequence data including video, subtitle, and metadata types ```ts type SequenceExportFormat @@ -6448,7 +6448,7 @@ type SequenceExportFormat ### `SequenceExportRecord` -`interface` +`interface` — Describe a record representing the export details and status of a sequence ```ts interface SequenceExportRecord @@ -6456,7 +6456,7 @@ interface SequenceExportRecord ### `SequenceExportStatus` -`type` +`type` — Represent export status of a sequence as queued, processing, completed, failed, or cancelled ```ts type SequenceExportStatus @@ -6472,7 +6472,7 @@ interface SequenceFrameSnapshot ### `SequenceMcpToolDefinition` -`interface` +`interface` — Define a tool with metadata and a run method for processing input within a specific environment ```ts interface SequenceMcpToolDefinition @@ -6488,7 +6488,7 @@ interface SequenceMcpToolEnv ### `SequenceMediaKind` -`type` +`type` — Define media types allowed in a sequence including video, image, and audio ```ts type SequenceMediaKind @@ -6496,7 +6496,7 @@ type SequenceMediaKind ### `SequenceMeta` -`interface` +`interface` — Describe metadata and properties of a media sequence including dimensions, duration, and status ```ts interface SequenceMeta @@ -6504,7 +6504,7 @@ interface SequenceMeta ### `SequenceOperation` -`type` +`type` — Represent sequence editing actions for manipulating clips, tracks, captions, and exports ```ts type SequenceOperation @@ -6520,7 +6520,7 @@ interface SequenceOperationContext ### `SequenceOperationType` -`type` +`type` — Extract the type of operation from a sequence operation object ```ts type SequenceOperationType @@ -6544,7 +6544,7 @@ readonly ["2025-06-18", "2025-03-26", "2024-11-05"] ### `SequencesMcpServerInfo` -`interface` +`interface` — Describe server information including name and version for Sequences MCP integration ```ts interface SequencesMcpServerInfo @@ -6552,7 +6552,7 @@ interface SequencesMcpServerInfo ### `SequenceStatus` -`type` +`type` — Define sequence status as one of the specific lifecycle stages draft, active, exporting, or archived ```ts type SequenceStatus @@ -6560,7 +6560,7 @@ type SequenceStatus ### `SequenceStore` -`interface` +`interface` — Manage sequences by providing methods to get timelines, clips, and modify tracks and clips ```ts interface SequenceStore @@ -6584,7 +6584,7 @@ interface SequenceTimeline ### `SequenceTrack` -`interface` +`interface` — Define properties and state for a sequence track including id, kind, name, order, and flags ```ts interface SequenceTrack @@ -6608,7 +6608,7 @@ type SequenceTrackKind ### `SetAttrsOperation` -`interface` +`interface` — Define an operation to update attributes of a specific element on a page ```ts interface SetAttrsOperation @@ -6616,7 +6616,7 @@ interface SetAttrsOperation ### `SetClipDisabledOperation` -`interface` +`interface` — Define an operation to enable or disable a clip by its identifier ```ts interface SetClipDisabledOperation @@ -6624,7 +6624,7 @@ interface SetClipDisabledOperation ### `SetClipTextOperation` -`interface` +`interface` — Resolve an operation to set clipboard text with optional language and clip identifier ```ts interface SetClipTextOperation @@ -6632,7 +6632,7 @@ interface SetClipTextOperation ### `SetDocumentTitleOperation` -`interface` +`interface` — Define an operation to set the document title to a specified string ```ts interface SetDocumentTitleOperation @@ -6640,7 +6640,7 @@ interface SetDocumentTitleOperation ### `SetPageGuidesOperation` -`interface` +`interface` — Resolve an operation to set guides on a specific page by its identifier ```ts interface SetPageGuidesOperation @@ -6648,7 +6648,7 @@ interface SetPageGuidesOperation ### `SetPagePropsOperation` -`interface` +`interface` — Define an operation to set or update properties of a page including size, background, and bleed ```ts interface SetPagePropsOperation @@ -6656,7 +6656,7 @@ interface SetPagePropsOperation ### `SetStepStatusPatch` -`interface` +`interface` — Define a patch to update the status and optional metadata of a step in a process ```ts interface SetStepStatusPatch @@ -6664,7 +6664,7 @@ interface SetStepStatusPatch ### `SharedBillingState` -`interface` +`interface` — Define shared billing state including user ID, plan, balances, concurrency, and overage permission ```ts interface SharedBillingState @@ -6688,7 +6688,7 @@ interface SidecarInteractionsConnection ### `SidecarInteractionsError` -`interface` +`interface` — Describe error details including code, message, and upstream HTTP status for sidecar interactions ```ts interface SidecarInteractionsError @@ -6696,7 +6696,7 @@ interface SidecarInteractionsError ### `SidecarInteractionsResult` -`type` +`type` — Represent the outcome of sidecar interactions with success or error details ```ts type SidecarInteractionsResult @@ -6720,7 +6720,7 @@ interface SignObjectUrlArgs ### `SIZE_PRESETS` -`const` +`const` — Provide predefined size presets for social, presentation, and print categories ```ts readonly SizePreset[] @@ -6728,7 +6728,7 @@ readonly SizePreset[] ### `SizePreset` -`interface` +`interface` — Define size presets with identifiers, labels, categories, and dimensions for various media types ```ts interface SizePreset @@ -6736,7 +6736,7 @@ interface SizePreset ### `SlotFillKind` -`type` +`type` — Define allowed string literals representing different slot fill kinds ```ts type SlotFillKind @@ -6768,7 +6768,7 @@ type SlotFillKind ### `SplitClipOperation` -`interface` +`interface` — Split a clip at a specified frame inside the clip to create two separate segments ```ts interface SplitClipOperation @@ -6776,7 +6776,7 @@ interface SplitClipOperation ### `splitDeferredProfileFiles` -`function` +`function` — Split profile files into inline deferred files and a lean profile without them ```ts (profile: AgentProfile) => { leanProfile: AgentProfile; deferredFiles: AgentProfileFileMount[]; } @@ -6784,7 +6784,7 @@ interface SplitClipOperation ### `stablePlanReceipt` -`function` +`function` — Resolve a durable follow-up receipt ensuring idempotency for a given plan decision and revision ```ts (scope: DurableChatScope, planId: string, revision: number, decision: DurablePlanDecision, result: Pick Promise> @@ -6928,7 +6928,7 @@ interface StreamAppToolLoopOptions ### `StreamEvent` -`interface` +`interface` — Define an event object carrying a type and optional JSON data payload ```ts interface StreamEvent @@ -6944,7 +6944,7 @@ type StreamLoopYield ### `streamSandboxPrompt` -`function` +`function` — Resolve and stream AI-generated responses from a sandboxed environment based on input messages and options ```ts (shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options?: StreamSandboxPromptO… @@ -6952,7 +6952,7 @@ type StreamLoopYield ### `StreamSandboxPromptOptions` -`interface` +`interface` — Define options for configuring and controlling a streaming sandbox prompt session ```ts interface StreamSandboxPromptOptions @@ -6960,7 +6960,7 @@ interface StreamSandboxPromptOptions ### `SubmitProposalArgs` -`interface` +`interface` — Define the arguments required to submit a proposal including type, title, description, and approval status ```ts interface SubmitProposalArgs @@ -6968,7 +6968,7 @@ interface SubmitProposalArgs ### `SubmitProposalResult` -`interface` +`interface` — Describe the result of submitting a proposal including deduplication and execution status ```ts interface SubmitProposalResult @@ -6976,7 +6976,7 @@ interface SubmitProposalResult ### `summarize` -`function` +`function` — Summarize numeric values into a distribution summary including count, min, median, 90th percentile, and max ```ts (values: number[]) => DistributionSummary @@ -7024,7 +7024,7 @@ type SurfacePermissionValue ### `SurfaceRegistry` -`interface` +`interface` — Resolve and build the overlay for a given surface kind within a turn context ```ts interface SurfaceRegistry @@ -7032,7 +7032,7 @@ interface SurfaceRegistry ### `syncSandboxMemberAdd` -`function` +`function` — Resolve adding a user with a specific role to a sandbox and return the operation outcome ```ts (box: SandboxInstance, seam: MemberSyncSeam, userId: string, role: string) => Promise> @@ -7040,7 +7040,7 @@ interface SurfaceRegistry ### `syncSandboxMemberRemove` -`function` +`function` — Remove a member from the sandbox while preserving their home directory and handle the outcome ```ts (box: SandboxInstance, userId: string) => Promise> @@ -7048,7 +7048,7 @@ interface SurfaceRegistry ### `syncSandboxMemberRole` -`function` +`function` — Synchronize a sandbox member's role by updating permissions based on the provided role mapping ```ts (box: SandboxInstance, seam: MemberSyncSeam, userId: string, role: string) => Promise> @@ -7056,7 +7056,7 @@ interface SurfaceRegistry ### `TangleBillingEnforcementOptions` -`interface` +`interface` — Define options for configuring billing enforcement environment variables and overrides ```ts interface TangleBillingEnforcementOptions @@ -7064,7 +7064,7 @@ interface TangleBillingEnforcementOptions ### `TangleExecutionEnvironment` -`type` +`type` — Define the environment context for executing Tangle operations ```ts type TangleExecutionEnvironment @@ -7072,7 +7072,7 @@ type TangleExecutionEnvironment ### `TangleExecutionKeyError` -`class` +`class` — Represent execution key errors with specific codes and HTTP status information ```ts class TangleExecutionKeyError @@ -7080,7 +7080,7 @@ class TangleExecutionKeyError ### `TangleExecutionKeyErrorCode` -`type` +`type` — Define error codes for Tangle execution key issues related to API key and account connection ```ts type TangleExecutionKeyErrorCode @@ -7088,7 +7088,7 @@ type TangleExecutionKeyErrorCode ### `tangleExecutionKeyHttpError` -`function` +`function` — Resolve and format TangleExecutionKey HTTP errors into a standardized error object or return null ```ts (error: unknown) => TangleExecutionKeyHttpError | null @@ -7096,7 +7096,7 @@ type TangleExecutionKeyErrorCode ### `TangleExecutionKeyHttpError` -`interface` +`interface` — Represent HTTP error response containing status, error message, and specific error code ```ts interface TangleExecutionKeyHttpError @@ -7104,7 +7104,7 @@ interface TangleExecutionKeyHttpError ### `TangleExecutionKeySource` -`type` +`type` — Resolve the source of the Tangle execution key as either local environment or user input ```ts type TangleExecutionKeySource @@ -7136,7 +7136,7 @@ interface TcloudKeyClient ### `TemplateSlot` -`interface` +`interface` — Define a slot template specifying its name, page, element, and fill characteristics ```ts interface TemplateSlot @@ -7160,7 +7160,7 @@ interface TemplateSlot ### `terminalizeDanglingToolParts` -`function` +`function` — Resolve dangling tool parts into terminal forms within the given JSON records array ```ts (parts: JsonRecord[]) => JsonRecord[] @@ -7168,7 +7168,7 @@ interface TemplateSlot ### `TerminalProxyIdentity` -`interface` +`interface` — Define identity details for a terminal proxy including user, workspace, and sandbox identifiers ```ts interface TerminalProxyIdentity @@ -7176,7 +7176,7 @@ interface TerminalProxyIdentity ### `terminalTokenFromRequest` -`function` +`function` — Resolve the terminal token from request headers using Authorization or Sec-WebSocket-Protocol fields ```ts (headers: Headers) => string | null @@ -7184,7 +7184,7 @@ interface TerminalProxyIdentity ### `TextElement` -`interface` +`interface` — Define properties for a text element including content, style, alignment, and layout parameters ```ts interface TextElement @@ -7200,7 +7200,7 @@ interface TextElement ### `ThemeContractMiss` -`interface` +`interface` — Describe a missing theme contract variable and where it was referenced ```ts interface ThemeContractMiss @@ -7208,7 +7208,7 @@ interface ThemeContractMiss ### `ThemeContractOptions` -`interface` +`interface` — Define options for scanning source directories and CSS token files in a theme contract ```ts interface ThemeContractOptions @@ -7216,7 +7216,7 @@ interface ThemeContractOptions ### `ThemeContractResult` -`interface` +`interface` — Describe the result of validating a theme contract including success status and missing items ```ts interface ThemeContractResult @@ -7240,7 +7240,7 @@ interface ThemeContractResult ### `TimedEvent` -`interface` +`interface` — Represent a timed event with a timestamp and associated event data ```ts interface TimedEvent @@ -7256,7 +7256,7 @@ interface TimedEvent ### `TimelineClipBounds` -`interface` +`interface` — Define the start frame and duration in frames for a timeline clip's bounds ```ts interface TimelineClipBounds @@ -7264,7 +7264,7 @@ interface TimelineClipBounds ### `TimelineInterval` -`interface` +`interface` — Define a time range with inclusive start and end frame numbers ```ts interface TimelineInterval @@ -7288,7 +7288,7 @@ interface TimelineInterval ### `ToolAuthResult` -`type` +`type` — Represent the result of tool authentication with success context or failure response ```ts type ToolAuthResult @@ -7368,7 +7368,7 @@ interface TranscriptSegment ### `TrimClipOperation` -`interface` +`interface` — Define an operation to trim a clip by adjusting its start, duration, and optional source in/out points ```ts interface TrimClipOperation @@ -7376,7 +7376,7 @@ interface TrimClipOperation ### `trimOrNull` -`function` +`function` — Resolve a string by trimming whitespace or returning null if empty or undefined ```ts (value: string | null | undefined) => string | null @@ -7400,7 +7400,7 @@ interface TrimClipOperation ### `TurnEventStore` -`interface` +`interface` — Manage and query turn events and their lifecycle statuses within a scoped event store ```ts interface TurnEventStore @@ -7416,7 +7416,7 @@ type TurnStatus ### `UngroupElementOperation` -`interface` +`interface` — Resolve an operation to ungroup elements within a specified page and group context ```ts interface UngroupElementOperation @@ -7432,7 +7432,7 @@ interface UngroupElementOperation ### `validateAddCaption` -`function` +`function` — Validate the parameters and context of an AddCaptionOperation within a sequence timeline ```ts (timeline: SequenceTimeline, operation: AddCaptionOperation, ctx: SequenceOperationContext) => void @@ -7448,7 +7448,7 @@ interface UngroupElementOperation ### `validateCreateTrack` -`function` +`function` — Validate that a CreateTrackOperation has a supported kind and a non-empty name ```ts (operation: CreateTrackOperation) => void @@ -7456,7 +7456,7 @@ interface UngroupElementOperation ### `validateDeleteClip` -`function` +`function` — Validate that the clip to delete exists and is mutable in the given timeline ```ts (timeline: SequenceTimeline, operation: DeleteClipOperation) => void @@ -7464,7 +7464,7 @@ interface UngroupElementOperation ### `validateExtendSequence` -`function` +`function` — Validate that the extend sequence operation has a positive duration and exceeds the last clip end frame ```ts (timeline: SequenceTimeline, operation: ExtendSequenceOperation) => void @@ -7480,7 +7480,7 @@ interface UngroupElementOperation ### `validateMoveClip` -`function` +`function` — Validate that a clip move operation is within bounds and targets a compatible unlocked track ```ts (timeline: SequenceTimeline, operation: MoveClipOperation) => void @@ -7488,7 +7488,7 @@ interface UngroupElementOperation ### `validatePlaceClip` -`function` +`function` — Validate the properties and constraints of a PlaceClipOperation within a SequenceTimeline ```ts (timeline: SequenceTimeline, operation: PlaceClipOperation) => void @@ -7496,7 +7496,7 @@ interface UngroupElementOperation ### `validateQueueExport` -`function` +`function` — Validate that the queue export operation uses a supported export format ```ts (operation: QueueExportOperation) => void @@ -7504,7 +7504,7 @@ interface UngroupElementOperation ### `validateSceneOperation` -`function` +`function` — Validate a scene operation against the document to ensure it meets required constraints ```ts (document: SceneDocument, operation: SceneOperation) => void @@ -7512,7 +7512,7 @@ interface UngroupElementOperation ### `validateSceneOperations` -`function` +`function` — Validate each scene operation against the document and throw detailed errors for invalid operations ```ts (document: SceneDocument, operations: SceneOperation[]) => void @@ -7520,7 +7520,7 @@ interface UngroupElementOperation ### `validateSequenceOperation` -`function` +`function` — Validate a sequence operation against the timeline and context to ensure correctness ```ts (timeline: SequenceTimeline, operation: SequenceOperation, ctx: SequenceOperationContext) => void @@ -7528,7 +7528,7 @@ interface UngroupElementOperation ### `validateSequenceOperations` -`function` +`function` — Validate each operation in a sequence against the timeline and context, throwing detailed errors on failure ```ts (timeline: SequenceTimeline, operations: SequenceOperation[], ctx: SequenceOperationContext) => void @@ -7536,7 +7536,7 @@ interface UngroupElementOperation ### `validateSetClipDisabled` -`function` +`function` — Validate that the clip can be disabled within the given timeline and operation constraints ```ts (timeline: SequenceTimeline, operation: SetClipDisabledOperation) => void @@ -7544,7 +7544,7 @@ interface UngroupElementOperation ### `validateSetClipText` -`function` +`function` — Validate that a SetClipTextOperation targets a caption clip with non-empty text and valid language tag ```ts (timeline: SequenceTimeline, operation: SetClipTextOperation) => void @@ -7560,7 +7560,7 @@ interface UngroupElementOperation ### `validateSplitClip` -`function` +`function` — Validate that a split operation on a clip is within valid frame boundaries and conditions ```ts (timeline: SequenceTimeline, operation: SplitClipOperation) => void @@ -7568,7 +7568,7 @@ interface UngroupElementOperation ### `validateTrimClip` -`function` +`function` — Validate that a trim clip operation respects timeline bounds and source frame constraints ```ts (timeline: SequenceTimeline, operation: TrimClipOperation) => void @@ -7624,7 +7624,7 @@ type VerifyObjectUrlResult ### `verifySandboxTerminalToken` -`function` +`function` — Verify the validity of a sandbox terminal token against the expected identity and options ```ts (token: string, expected: TerminalProxyIdentity, opts: SandboxTerminalTokenOptions) => Promise @@ -7632,7 +7632,7 @@ type VerifyObjectUrlResult ### `verifyTerminalProxyToken` -`function` +`function` — Verify the authenticity and validity of a terminal proxy token against expected identity and timestamp ```ts (secret: string, token: string, expected: TerminalProxyIdentity, now?: () => number) => Promise @@ -7640,7 +7640,7 @@ type VerifyObjectUrlResult ### `VideoCaption` -`interface` +`interface` — Define video caption segments with start and end times and associated text content ```ts interface VideoCaption @@ -7648,7 +7648,7 @@ interface VideoCaption ### `VideoContent` -`interface` +`interface` — Describe video content including duration, scenes, optional audio, captions, and rendered URL ```ts interface VideoContent @@ -7656,7 +7656,7 @@ interface VideoContent ### `VideoContentSchema` -`const` +`const` — Define the schema for validating video content including duration, scenes, audio, captions, and rendered URL ```ts ZodObject<{ durationSeconds: ZodNumber; scenes: ZodArray Promise> diff --git a/docs/api/intakes-api.md b/docs/api/intakes-api.md index dc11b1f..0854a26 100644 --- a/docs/api/intakes-api.md +++ b/docs/api/intakes-api.md @@ -24,7 +24,7 @@ interface CurrentIntakeView ### `IntakeApiOptions` -`interface` +`interface` — Define configuration options for initializing the intake API with store and graph components ```ts interface IntakeApiOptions diff --git a/docs/api/intakes-drizzle.md b/docs/api/intakes-drizzle.md index 0fa3b14..c5e22f7 100644 --- a/docs/api/intakes-drizzle.md +++ b/docs/api/intakes-drizzle.md @@ -24,7 +24,7 @@ type AnyIntakeTables ### `CreateIntakeTablesOptions` -`interface` +`interface` — Define options for creating intake tables including user and optional workspace references ```ts interface CreateIntakeTablesOptions @@ -40,7 +40,7 @@ interface CreateIntakeTablesOptions ### `CreateProjectIntakeStoreOptions` -`interface` +`interface` — Define options required to create a project intake store including database, table, graph, and workspace ID ```ts interface CreateProjectIntakeStoreOptions @@ -56,7 +56,7 @@ interface CreateProjectIntakeStoreOptions ### `CreateUserIntakeStoreOptions` -`interface` +`interface` — Define options required to create a user intake store for onboarding data collection ```ts interface CreateUserIntakeStoreOptions @@ -80,7 +80,7 @@ class IntakeError ### `IntakeErrorCode` -`type` +`type` — Define error codes representing specific intake validation failures ```ts type IntakeErrorCode @@ -120,7 +120,7 @@ type IntakeTables ### `ProjectIntakeRow` -`type` +`type` — Resolve the selected data structure for a project intake table row ```ts type ProjectIntakeRow @@ -128,7 +128,7 @@ type ProjectIntakeRow ### `ProjectIntakeTable` -`type` +`type` — Resolve the structure and data of the project intake table from the factory function ```ts type ProjectIntakeTable @@ -136,7 +136,7 @@ type ProjectIntakeTable ### `UserIntakeRow` -`type` +`type` — Infer and represent a selected row from the UserIntakeTable data structure ```ts type UserIntakeRow @@ -144,7 +144,7 @@ type UserIntakeRow ### `UserIntakeTable` -`type` +`type` — Resolve the structure and data of a user intake table based on the createUserIntakeTable function ```ts type UserIntakeTable diff --git a/docs/api/intakes-react-lazy.md b/docs/api/intakes-react-lazy.md index 677d650..b26241b 100644 --- a/docs/api/intakes-react-lazy.md +++ b/docs/api/intakes-react-lazy.md @@ -8,7 +8,7 @@ Source: `src/intakes-react/lazy.tsx` ### `IntakeInterviewLazy` -`function` +`function` — Load IntakeInterview component lazily to optimize initial application rendering ```ts LazyExoticComponent<({ view: initialView, onAnswer, onComplete, onDone, onNotice, }: IntakeInterviewProps) => Element> @@ -16,7 +16,7 @@ LazyExoticComponent<({ view: initialView, onAnswer, onComplete, onDone, onNotice ### `IntakeInterviewProps` -`interface` +`interface` — Define properties and callbacks for managing the intake interview flow and user interactions ```ts interface IntakeInterviewProps diff --git a/docs/api/intakes-react.md b/docs/api/intakes-react.md index a59c31c..74b334c 100644 --- a/docs/api/intakes-react.md +++ b/docs/api/intakes-react.md @@ -16,7 +16,7 @@ Source: `src/intakes-react/index.ts` ### `IntakeInterviewProps` -`interface` +`interface` — Define properties and callbacks for managing the intake interview flow and user interactions ```ts interface IntakeInterviewProps diff --git a/docs/api/intakes.md b/docs/api/intakes.md index 2ca79a6..d9ff2f2 100644 --- a/docs/api/intakes.md +++ b/docs/api/intakes.md @@ -16,7 +16,7 @@ type AnswerRejectionReason ### `AnswerValidationResult` -`interface` +`interface` — Describe validation outcome of an answer including success status and optional rejection reason ```ts interface AnswerValidationResult diff --git a/docs/api/integrations.md b/docs/api/integrations.md index f9825a7..b2eedb2 100644 --- a/docs/api/integrations.md +++ b/docs/api/integrations.md @@ -16,7 +16,7 @@ class HubExecClient ### `HubExecClientOptions` -`interface` +`interface` — Define configuration options for initializing a Hub execution client ```ts interface HubExecClientOptions @@ -40,7 +40,7 @@ type HubExecResult ### `HubInvokeDeps` -`interface` +`interface` — Define dependencies for invoking hub operations including API key resolution and optional configuration ```ts interface HubInvokeDeps @@ -48,7 +48,7 @@ interface HubInvokeDeps ### `HubInvokeInput` -`interface` +`interface` — Define input parameters for invoking a hub tool with user ID, tool name, and optional arguments ```ts interface HubInvokeInput @@ -56,7 +56,7 @@ interface HubInvokeInput ### `HubInvokeOutcome` -`interface` +`interface` — Describe the outcome of a hub invocation including status and response body ```ts interface HubInvokeOutcome diff --git a/docs/api/interactions.md b/docs/api/interactions.md index b311157..5fcbdf3 100644 --- a/docs/api/interactions.md +++ b/docs/api/interactions.md @@ -8,7 +8,7 @@ Source: `src/interactions/index.ts` ### `BeforeInteractionAnswerArgs` -`interface` +`interface` — Describe the arguments provided before processing an interaction answer including request, body, and connection details ```ts interface BeforeInteractionAnswerArgs @@ -40,7 +40,7 @@ interface ChatInteraction ### `ChatInteractionField` -`type` +`type` — Resolve a chat interaction field excluding select types or including chat select fields ```ts type ChatInteractionField @@ -48,7 +48,7 @@ type ChatInteractionField ### `ChatInteractionStatus` -`type` +`type` — Define possible statuses representing the state of a chat interaction ```ts type ChatInteractionStatus @@ -56,7 +56,7 @@ type ChatInteractionStatus ### `ChatSelectField` -`type` +`type` — Extract select-type interaction fields and optionally allow custom values ```ts type ChatSelectField @@ -80,7 +80,7 @@ type ChatSelectField ### `ComposerAnswerDelivery` -`interface` +`interface` — Define the structure for delivering answers linked to a specific chat interaction and field ```ts interface ComposerAnswerDelivery @@ -88,7 +88,7 @@ interface ComposerAnswerDelivery ### `createInteractionAnswerRoute` -`function` +`function` — Create an interaction answer route that handles listing and resolving interaction requests ```ts (options: InteractionAnswerRouteOptions) => InteractionAnswerRoute @@ -96,7 +96,7 @@ interface ComposerAnswerDelivery ### `dedupeQuestionInteractionsByContent` -`function` +`function` — Remove duplicate question interactions based on their content signature to ensure uniqueness ```ts (interactions: ChatInteraction[]) => ChatInteraction[] @@ -104,7 +104,7 @@ interface ComposerAnswerDelivery ### `DurableInteractionRouteArgs` -`interface` +`interface` — Define arguments for durable interaction routes including a stable caller-created attempt key ```ts interface DurableInteractionRouteArgs @@ -120,7 +120,7 @@ interface DurableInteractionRoutePersistence ### `fieldAcceptsFreeText` -`function` +`function` — Determine if a chat interaction field allows free text input ```ts (field: ChatInteractionField) => boolean @@ -152,7 +152,7 @@ interface DurableInteractionRoutePersistence ### `InteractionAnswerBodyValidation` -`type` +`type` — Validate interaction answer body and return success with data or failure with error message ```ts type InteractionAnswerBodyValidation @@ -160,7 +160,7 @@ type InteractionAnswerBodyValidation ### `InteractionAnswerRoute` -`interface` +`interface` — Define routes to list outstanding interactions and resolve answers for live turns ```ts interface InteractionAnswerRoute @@ -168,7 +168,7 @@ interface InteractionAnswerRoute ### `InteractionAnswerRouteOptions` -`interface` +`interface` — Define options to authenticate, authorize, and manage persistence for interaction answer routes ```ts interface InteractionAnswerRouteOptions @@ -176,7 +176,7 @@ interface InteractionAnswerRouteOptions ### `InteractionAnswers` -`type` +`type` — Map interaction identifiers to their corresponding answer values ```ts type InteractionAnswers @@ -192,7 +192,7 @@ type InteractionAnswerValue ### `InteractionCancelData` -`interface` +`interface` — Describe data required to cancel an interaction including its identifier and optional reason ```ts interface InteractionCancelData @@ -200,7 +200,7 @@ interface InteractionCancelData ### `InteractionClientOutcome` -`type` +`type` — Define possible outcomes for an interaction client as accepted or declined ```ts type InteractionClientOutcome @@ -240,7 +240,7 @@ type InteractionOutcome ### `interactionPartKey` -`function` +`function` — Generate a unique key string for an interaction using the given identifier ```ts (id: string) => string @@ -272,7 +272,7 @@ type InteractionRequestWire ### `InteractionRouteLogger` -`type` +`type` — Provide logging methods for warnings and errors in interaction routes ```ts type InteractionRouteLogger @@ -288,7 +288,7 @@ type InteractionRouteLogger ### `isRenderableInteractionKind` -`function` +`function` — Resolve if the given interaction kind is renderable within the application context ```ts (kind: string) => boolean @@ -304,7 +304,7 @@ type InteractionRouteLogger ### `isTerminalInteractionStatus` -`function` +`function` — Resolve if the interaction status is a terminal state excluding pending ```ts (status: ChatInteractionStatus) => boolean @@ -328,7 +328,7 @@ type InteractionRouteLogger ### `NoticeKind` -`type` +`type` — Define specific string literals representing different kinds of notices ```ts type NoticeKind @@ -344,7 +344,7 @@ type NoticeKind ### `noticePartKey` -`function` +`function` — Generate a unique key string for a notice using the given identifier ```ts (id: string) => string @@ -352,7 +352,7 @@ type NoticeKind ### `NoticePersistedPart` -`type` +`type` — Define a persisted notice part with type, id, kind, and text properties ```ts type NoticePersistedPart @@ -368,7 +368,7 @@ type NoticePersistedPart ### `ParseInteractionAnswersResult` -`type` +`type` — Resolve the result of parsing interaction answers with success status and corresponding data or error message ```ts type ParseInteractionAnswersResult @@ -376,7 +376,7 @@ type ParseInteractionAnswersResult ### `parseInteractionCancel` -`function` +`function` — Parse interaction cancel data and return success status with parsed value or error message ```ts (data: Record | undefined) => { succeeded: true; value: InteractionCancelData; } | { succeeded: false;… @@ -392,7 +392,7 @@ type ParseInteractionAnswersResult ### `ParseInteractionResult` -`type` +`type` — Resolve interaction parsing outcome as success with value or failure with error message ```ts type ParseInteractionResult @@ -416,7 +416,7 @@ type ParseInteractionResult ### `ResolveInteractionConnectionArgs` -`interface` +`interface` — Define arguments required to resolve interaction connections based on request and intent ```ts interface ResolveInteractionConnectionArgs @@ -440,7 +440,7 @@ interface SidecarInteractionsConnection ### `SidecarInteractionsError` -`interface` +`interface` — Describe error details including code, message, and upstream HTTP status for sidecar interactions ```ts interface SidecarInteractionsError @@ -448,7 +448,7 @@ interface SidecarInteractionsError ### `SidecarInteractionsResult` -`type` +`type` — Represent the outcome of sidecar interactions with success or error details ```ts type SidecarInteractionsResult diff --git a/docs/api/knowledge-loop.md b/docs/api/knowledge-loop.md index 6ea033f..ae996e3 100644 --- a/docs/api/knowledge-loop.md +++ b/docs/api/knowledge-loop.md @@ -16,7 +16,7 @@ Source: `src/knowledge-loop/index.ts` ### `CreateKnowledgeLoopDeps` -`interface` +`interface` — Define dependencies required to create and run a knowledge processing loop ```ts interface CreateKnowledgeLoopDeps @@ -48,7 +48,7 @@ interface KnowledgeDecider ### `KnowledgeDeciderInput` -`interface` +`interface` — Define the input parameters required to decide knowledge proposals within an agent-knowledge loop ```ts interface KnowledgeDeciderInput @@ -56,7 +56,7 @@ interface KnowledgeDeciderInput ### `KnowledgeDecision` -`interface` +`interface` — Define a decision containing a candidate and the gate's verdict on that candidate ```ts interface KnowledgeDecision diff --git a/docs/api/knowledge.md b/docs/api/knowledge.md index 53cbc00..6d5d630 100644 --- a/docs/api/knowledge.md +++ b/docs/api/knowledge.md @@ -24,7 +24,7 @@ Source: `src/knowledge/index.ts` ### `KnowledgeRequirementSpec` -`interface` +`interface` — Define the criteria and conditions required to satisfy a specific knowledge requirement ```ts interface KnowledgeRequirementSpec @@ -32,7 +32,7 @@ interface KnowledgeRequirementSpec ### `KnowledgeSignal` -`interface` +`interface` — Define a signal representing knowledge with confidence level and optional supporting evidence ```ts interface KnowledgeSignal diff --git a/docs/api/missions.md b/docs/api/missions.md index 65ef5bf..ad91ba9 100644 --- a/docs/api/missions.md +++ b/docs/api/missions.md @@ -40,7 +40,7 @@ Source: `src/missions/index.ts` ### `CompleteMissionInput` -`interface` +`interface` — Define input parameters to complete a mission with status and optional summary ```ts interface CompleteMissionInput @@ -56,7 +56,7 @@ interface CompleteMissionInput ### `createMissionEngine` -`function` +`function` — Create a mission engine configured with options to manage mission execution and error handling ```ts (options: MissionEngineOptions) => MissionEngine @@ -64,7 +64,7 @@ interface CompleteMissionInput ### `CreateMissionInput` -`interface` +`interface` — Define input parameters for creating a mission including optional deterministic id and unique plan steps ```ts interface CreateMissionInput @@ -72,7 +72,7 @@ interface CreateMissionInput ### `createMissionService` -`function` +`function` — Create a mission service that manages mission records and audit events with customizable options ```ts (options: MissionServiceOptions) => MissionService @@ -88,7 +88,7 @@ readonly string[] ### `InMemoryMissionStore` -`interface` +`interface` — Define an in-memory mission store that tracks events and allows direct record writes ```ts interface InMemoryMissionStore @@ -152,7 +152,7 @@ class MissionConcurrencyError ### `MissionCostLedger` -`interface` +`interface` — Define the structure for tracking mission token usage, cost, duration, and LLM call counts ```ts interface MissionCostLedger @@ -160,7 +160,7 @@ interface MissionCostLedger ### `MissionEngine` -`interface` +`interface` — Resolve mission plan steps with concurrency control and durable state management ```ts interface MissionEngine @@ -168,7 +168,7 @@ interface MissionEngine ### `MissionEngineOptions` -`interface` +`interface` — Define configuration options for initializing and controlling the mission engine behavior ```ts interface MissionEngineOptions @@ -176,7 +176,7 @@ interface MissionEngineOptions ### `MissionEventSink` -`interface` +`interface` — Handle mission stream events by processing emitted MissionStreamEvent objects ```ts interface MissionEventSink @@ -184,7 +184,7 @@ interface MissionEventSink ### `MissionGateKind` -`type` +`type` — Define mission gate categories as step, budget, or volume ```ts type MissionGateKind @@ -192,7 +192,7 @@ type MissionGateKind ### `MissionGateOptions` -`interface` +`interface` — Define configuration options for mission gating including approvals, step classification, and action limits ```ts interface MissionGateOptions @@ -216,7 +216,7 @@ type MissionOutcome ### `MissionPlanRunOptions` -`interface` +`interface` — Define options to control mission plan execution with optional pre-step veto logic ```ts interface MissionPlanRunOptions @@ -240,7 +240,7 @@ interface MissionRecord ### `MissionService` -`interface` +`interface` — Define methods to create, retrieve, and update missions with controlled engine binding and metadata merging ```ts interface MissionService @@ -248,7 +248,7 @@ interface MissionService ### `MissionServiceOptions` -`interface` +`interface` — Define options for configuring mission service behavior including storage, time, and ID generation ```ts interface MissionServiceOptions @@ -272,7 +272,7 @@ type MissionStatus ### `MissionStep` -`interface` +`interface` — Define the structure and state details of a mission step within a workflow system ```ts interface MissionStep @@ -288,7 +288,7 @@ interface MissionStepState ### `MissionStepStatus` -`type` +`type` — Define possible statuses for a mission step during its execution lifecycle ```ts type MissionStepStatus @@ -312,7 +312,7 @@ type MissionStreamEvent ### `MissionStreamStatus` -`type` +`type` — Define possible statuses representing the current state of a mission stream ```ts type MissionStreamStatus @@ -328,7 +328,7 @@ interface MissionStreamStep ### `MissionStreamStepStatus` -`type` +`type` — Define possible status values for a mission stream step ```ts type MissionStreamStepStatus @@ -360,7 +360,7 @@ MissionEventSink ### `ParsedMission` -`interface` +`interface` — Describe a mission with a title and an ordered list of parsed steps ```ts interface ParsedMission @@ -368,7 +368,7 @@ interface ParsedMission ### `ParsedMissionStep` -`interface` +`interface` — Define the structure representing a parsed mission step with id, kind, and intent fields ```ts interface ParsedMissionStep @@ -384,7 +384,7 @@ interface ParsedMissionStep ### `ParseMissionBlocksOptions` -`interface` +`interface` — Define options to specify allowed lowercase step kinds for parsing mission blocks ```ts interface ParseMissionBlocksOptions @@ -432,7 +432,7 @@ type SandboxDispatch ### `SandboxDispatchDoneResult` -`interface` +`interface` — Define the result of a completed sandbox dispatch including artifact reference and optional cost details ```ts interface SandboxDispatchDoneResult @@ -448,7 +448,7 @@ interface SandboxDispatchInProgressResult ### `SandboxDispatchInput` -`interface` +`interface` — Define input parameters for dispatching a mission step in the sandbox environment ```ts interface SandboxDispatchInput @@ -456,7 +456,7 @@ interface SandboxDispatchInput ### `SandboxDispatchResult` -`type` +`type` — Resolve the result of a sandbox dispatch as done or in progress ```ts type SandboxDispatchResult @@ -464,7 +464,7 @@ type SandboxDispatchResult ### `SetStepStatusPatch` -`interface` +`interface` — Define a patch to update the status and optional metadata of a step in a process ```ts interface SetStepStatusPatch diff --git a/docs/api/model-resolution.md b/docs/api/model-resolution.md index 9bc8261..88602be 100644 --- a/docs/api/model-resolution.md +++ b/docs/api/model-resolution.md @@ -8,7 +8,7 @@ Source: `src/model-resolution/index.ts` ### `catalogIdsForModel` -`function` +`function` — Resolve unique catalog IDs associated with a given model including its canonical form if applicable ```ts (model: ModelInfo) => string[] @@ -16,7 +16,7 @@ Source: `src/model-resolution/index.ts` ### `ChatModelSource` -`type` +`type` — Define possible origins for the chat model configuration values ```ts type ChatModelSource @@ -24,7 +24,7 @@ type ChatModelSource ### `ChatModelValidationFailure` -`interface` +`interface` — Describe a failed chat model validation result with an error message ```ts interface ChatModelValidationFailure @@ -32,7 +32,7 @@ interface ChatModelValidationFailure ### `ChatModelValidationResult` -`type` +`type` — Resolve the outcome of validating a chat model as either success or failure ```ts type ChatModelValidationResult @@ -40,7 +40,7 @@ type ChatModelValidationResult ### `ChatModelValidationSuccess` -`interface` +`interface` — Represent successful chat model validation with a true status and a validated string value ```ts interface ChatModelValidationSuccess @@ -48,7 +48,7 @@ interface ChatModelValidationSuccess ### `cleanModelId` -`function` +`function` — Resolve and return a trimmed string model ID or undefined for invalid or empty input ```ts (value: unknown) => string | undefined @@ -56,7 +56,7 @@ interface ChatModelValidationSuccess ### `isWellFormedModelId` -`function` +`function` — Validate if a model ID string conforms to length and character format requirements ```ts (modelId: string) => boolean @@ -88,7 +88,7 @@ interface ModelInfo ### `ResolveChatModelInput` -`interface` +`interface` — Resolve the effective chat model input by prioritizing request, workspace, environment, and default models ```ts interface ResolveChatModelInput @@ -96,7 +96,7 @@ interface ResolveChatModelInput ### `ResolvedChatModel` -`interface` +`interface` — Resolve a chat model with its identifier and source information ```ts interface ResolvedChatModel @@ -112,7 +112,7 @@ interface ResolvedChatModel ### `ValidateChatModelIdInput` -`interface` +`interface` — Define input parameters for validating chat model IDs with optional allowlist and catalog access details ```ts interface ValidateChatModelIdInput diff --git a/docs/api/plans.md b/docs/api/plans.md index 2f7bc33..94a5cc8 100644 --- a/docs/api/plans.md +++ b/docs/api/plans.md @@ -48,7 +48,7 @@ type ChatPlanStatus ### `ParsePlanSubmittedResult` -`type` +`type` — Resolve the result of parsing a plan submission into success with value or failure with error ```ts type ParsePlanSubmittedResult @@ -56,7 +56,7 @@ type ParsePlanSubmittedResult ### `persistedPartToPlan` -`function` +`function` — Resolve a persisted part object into a ChatPlan or return null if the type is not 'plan ```ts (part: Record) => ChatPlan | null @@ -72,7 +72,7 @@ type ParsePlanSubmittedResult ### `planFollowUpTurnId` -`function` +`function` — Generate a unique follow-up turn ID based on the plan ID and its outcome ```ts (planId: string, outcome: "approved" | "rejected") => string @@ -80,7 +80,7 @@ type ParsePlanSubmittedResult ### `planPartKey` -`function` +`function` — Generate a unique key string for a given plan identifier ```ts (planId: string) => string @@ -88,7 +88,7 @@ type ParsePlanSubmittedResult ### `planRevisionKey` -`function` +`function` — Generate a unique key string for a plan based on its ID and revision number ```ts (planId: string, revision: number) => string @@ -96,7 +96,7 @@ type ParsePlanSubmittedResult ### `planToPersistedPart` -`function` +`function` — Resolve a ChatPlan into its persisted part representation for storage or transmission ```ts (plan: ChatPlan) => ChatPlanPersistedPart diff --git a/docs/api/platform.md b/docs/api/platform.md index c1daa77..54de32c 100644 --- a/docs/api/platform.md +++ b/docs/api/platform.md @@ -8,7 +8,7 @@ Source: `src/platform/index.ts` ### `AdminGuardOptions` -`interface` +`interface` — Define options to resolve user session and control access based on allowed admin emails ```ts interface AdminGuardOptions @@ -24,7 +24,7 @@ interface AdminGuardOptions ### `AssertBillableBalanceOptions` -`interface` +`interface` — Define options to assert and customize billable balance enforcement behavior ```ts interface AssertBillableBalanceOptions @@ -32,7 +32,7 @@ interface AssertBillableBalanceOptions ### `AuthGuard` -`interface` +`interface` — Resolve user authentication and session requirements for page and API requests ```ts interface AuthGuard @@ -40,7 +40,7 @@ interface AuthGuard ### `AuthGuardOptions` -`interface` +`interface` — Define options for configuring authentication guard behavior and session retrieval ```ts interface AuthGuardOptions @@ -48,7 +48,7 @@ interface AuthGuardOptions ### `BetterAuthSessionCookieMinterOptions` -`interface` +`interface` — Define options to customize warning behavior for shadowed cookie names in authentication sessions ```ts interface BetterAuthSessionCookieMinterOptions @@ -64,7 +64,7 @@ interface BetterAuthSessionCookieSource ### `BillableBalanceState` -`interface` +`interface` — Describe the billable balance state including overage permission and remaining USD balance ```ts interface BillableBalanceState @@ -80,7 +80,7 @@ interface BillableBalanceState ### `createAuthGuard` -`function` +`function` — Create an authentication guard that enforces session presence and handles unauthorized access responses ```ts (opts: AuthGuardOptions) => AuthGuard @@ -96,7 +96,7 @@ interface BillableBalanceState ### `createHubProxyRoutes` -`function` +`function` — Resolve hub proxy routes with authentication and error handling based on the given context ```ts (ctx: HubProxyContext) => HubProxyRoutes @@ -104,7 +104,7 @@ interface BillableBalanceState ### `createPlatformBillingHttp` -`function` +`function` — Create a PlatformBillingHttp instance configured with given options and default behaviors ```ts (opts: PlatformBillingHttpOptions) => PlatformBillingHttp @@ -128,7 +128,7 @@ interface BillableBalanceState ### `createTangleSsoHandlers` -`function` +`function` — Create Tangle SSO handlers to manage authentication state, callbacks, and session cookies ```ts (opts: TangleSsoHandlerOptions) => TangleSsoHandlers @@ -144,7 +144,7 @@ interface BillableBalanceState ### `DEFAULT_TANGLE_TIER_POLICY` -`const` +`const` — Define default concurrency and overage policies for each TanglePlanTier level ```ts Record @@ -176,7 +176,7 @@ Record ### `GuardResolution` -`type` +`type` — Resolve a value or an HTTP response indicating failure in a guarded operation ```ts type GuardResolution @@ -192,7 +192,7 @@ interface HubClientLike ### `HubProxyContext` -`interface` +`interface` — Define methods to require user ID, get bearer token, and create a hub client bound to the bearer ```ts interface HubProxyContext @@ -200,7 +200,7 @@ interface HubProxyContext ### `HubProxyRouteArgs` -`interface` +`interface` — Define arguments for configuring a proxy route with request and optional parameters ```ts interface HubProxyRouteArgs @@ -208,7 +208,7 @@ interface HubProxyRouteArgs ### `HubProxyRoutes` -`interface` +`interface` — Define routes for hub proxy handling catalog, connections, healthchecks, and authorization actions ```ts interface HubProxyRoutes @@ -272,7 +272,7 @@ interface HubProxyRoutes ### `PlatformBalanceSnapshot` -`interface` +`interface` — Describe the platform balance and lifetime spending with an optional update timestamp ```ts interface PlatformBalanceSnapshot @@ -280,7 +280,7 @@ interface PlatformBalanceSnapshot ### `PlatformBillingHttp` -`interface` +`interface` — Define methods to interact with platform billing endpoints using user or service authentication ```ts interface PlatformBillingHttp @@ -288,7 +288,7 @@ interface PlatformBillingHttp ### `PlatformBillingHttpError` -`class` +`class` — Represent platform billing HTTP errors with status code and detailed message ```ts class PlatformBillingHttpError @@ -296,7 +296,7 @@ class PlatformBillingHttpError ### `PlatformBillingHttpOptions` -`interface` +`interface` — Define HTTP options for platform billing including base URL, service token, product slug, fetch implementation, and timeout ```ts interface PlatformBillingHttpOptions @@ -304,7 +304,7 @@ interface PlatformBillingHttpOptions ### `PlatformIdentityStore` -`interface` +`interface` — Define a contract for resolving platform identities based on user identifiers ```ts interface PlatformIdentityStore @@ -312,7 +312,7 @@ interface PlatformIdentityStore ### `PlatformSubscriptionInfo` -`interface` +`interface` — Describe subscription tier and status information for a platform user ```ts interface PlatformSubscriptionInfo @@ -320,7 +320,7 @@ interface PlatformSubscriptionInfo ### `PlatformUsageProductRow` -`interface` +`interface` — Describe a product's usage and spending metrics on the platform ```ts interface PlatformUsageProductRow @@ -344,7 +344,7 @@ interface ProductEntitlement ### `ResolvedTangleHubBearer` -`interface` +`interface` — Represent a resolved bearer token with its associated TangleHub bearer source ```ts interface ResolvedTangleHubBearer @@ -360,7 +360,7 @@ interface ResolvedTangleHubBearer ### `resolveUserTangleHubBearerForUser` -`function` +`function` — Resolve the TangleHub bearer token for a specified user based on provided options ```ts (opts: ResolveUserTangleHubBearerForUserOptions) => Promise @@ -368,7 +368,7 @@ interface ResolvedTangleHubBearer ### `ResolveUserTangleHubBearerForUserOptions` -`interface` +`interface` — Resolve options for retrieving a TangleHub bearer token for a specified user ```ts interface ResolveUserTangleHubBearerForUserOptions @@ -376,7 +376,7 @@ interface ResolveUserTangleHubBearerForUserOptions ### `ResolveUserTangleHubBearerOptions` -`interface` +`interface` — Resolve options required to obtain a user's TangleHub bearer token including environment and API key retrieval ```ts interface ResolveUserTangleHubBearerOptions @@ -384,7 +384,7 @@ interface ResolveUserTangleHubBearerOptions ### `SeatBillingFlagOptions` -`interface` +`interface` — Define options to configure seat billing flag environment variables and override flag name ```ts interface SeatBillingFlagOptions @@ -416,7 +416,7 @@ type SeatStatus ### `SsoStateConfig` -`interface` +`interface` — Define configuration options for managing SSO state including secret, lifetime, and clock injection ```ts interface SsoStateConfig @@ -424,7 +424,7 @@ interface SsoStateConfig ### `TangleBearerMissingError` -`class` +`class` — Represent missing Tangle platform link error for a specified user ID ```ts class TangleBearerMissingError @@ -440,7 +440,7 @@ type TangleHubBearerSource ### `TanglePlanTier` -`type` +`type` — Define available subscription tiers for the TanglePlan service ```ts type TanglePlanTier @@ -464,7 +464,7 @@ interface TangleSsoAuthClient ### `TangleSsoExchangeResult` -`interface` +`interface` — Describe the result of exchanging SSO credentials including API key, user info, and optional plan details ```ts interface TangleSsoExchangeResult @@ -472,7 +472,7 @@ interface TangleSsoExchangeResult ### `TangleSsoHandlerOptions` -`interface` +`interface` — Define configuration options for handling Tangle SSO authentication and session management ```ts interface TangleSsoHandlerOptions @@ -480,7 +480,7 @@ interface TangleSsoHandlerOptions ### `TangleSsoHandlers` -`interface` +`interface` — Define handlers for SSO start and callback routes managing authentication flow and session cookies ```ts interface TangleSsoHandlers @@ -504,7 +504,7 @@ class TangleSsoUserCreateError ### `TangleTierPolicy` -`interface` +`interface` — Define policy settings for concurrency and overage allowance in a tangle tier ```ts interface TangleTierPolicy @@ -512,7 +512,7 @@ interface TangleTierPolicy ### `TangleTierState` -`interface` +`interface` — Describe the state of a Tangle plan tier including subscription, balance, spending, and concurrency details ```ts interface TangleTierState diff --git a/docs/api/preflight.md b/docs/api/preflight.md index a9495af..0dd2965 100644 --- a/docs/api/preflight.md +++ b/docs/api/preflight.md @@ -24,7 +24,7 @@ Source: `src/preflight/index.ts` ### `HttpHeadProbeConfig` -`interface` +`interface` — Define configuration options for performing an HTTP HEAD probe to check URL availability ```ts interface HttpHeadProbeConfig @@ -72,7 +72,7 @@ interface PreflightReport ### `RouterChatProbeConfig` -`interface` +`interface` — Define configuration options for probing an LLM router with authentication and model details ```ts interface RouterChatProbeConfig @@ -96,7 +96,7 @@ interface RouterChatProbeConfig ### `SandboxAuthProbeConfig` -`interface` +`interface` — Define configuration options for probing sandbox authentication endpoints ```ts interface SandboxAuthProbeConfig diff --git a/docs/api/preset-cloudflare.md b/docs/api/preset-cloudflare.md index e8df19e..0f2522d 100644 --- a/docs/api/preset-cloudflare.md +++ b/docs/api/preset-cloudflare.md @@ -104,7 +104,7 @@ readonly string[] ### `PresetBillingOptions` -`interface` +`interface` — Define preset billing options including database, provisioner, encryption key, budget, and optional settings ```ts interface PresetBillingOptions @@ -112,7 +112,7 @@ interface PresetBillingOptions ### `PresetKnowledgeAccessorOptions` -`interface` +`interface` — Define options for accessing preset knowledge scoped to a specific workspace and configuration ```ts interface PresetKnowledgeAccessorOptions @@ -120,7 +120,7 @@ interface PresetKnowledgeAccessorOptions ### `PresetToolHandlerOptions` -`interface` +`interface` — Define configuration options for handling preset tools including database, vault, and optional utilities ```ts interface PresetToolHandlerOptions diff --git a/docs/api/redact.md b/docs/api/redact.md index 7eac2cb..8192a49 100644 --- a/docs/api/redact.md +++ b/docs/api/redact.md @@ -16,7 +16,7 @@ Source: `src/redact/index.ts` ### `BuildRedactedDocumentOptions` -`interface` +`interface` — Define options to encrypt text and specify patterns for redacting sensitive document content ```ts interface BuildRedactedDocumentOptions @@ -56,7 +56,7 @@ type RedactedDocSegment ### `RedactedDocument` -`interface` +`interface` — Define a document composed of multiple redacted content segments ```ts interface RedactedDocument @@ -72,7 +72,7 @@ interface RedactedDocument ### `RedactForIngestionOptions` -`interface` +`interface` — Define options to customize sensitive data redaction patterns and key names for ingestion ```ts interface RedactForIngestionOptions @@ -96,7 +96,7 @@ interface RedactionSpan ### `RevealResult` -`interface` +`interface` — Describe the outcome of a reveal operation including success status, value, and failure reason ```ts interface RevealResult @@ -112,7 +112,7 @@ interface RevealResult ### `RevealSpanOptions` -`interface` +`interface` — Define options to decrypt, authorize, and audit the reveal of a span segment ```ts interface RevealSpanOptions diff --git a/docs/api/run.md b/docs/api/run.md index 7b73b6b..1840391 100644 --- a/docs/api/run.md +++ b/docs/api/run.md @@ -8,7 +8,7 @@ Source: `src/run/index.ts` ### `ExecutionMode` -`type` +`type` — Define execution mode as either router or sandbox ```ts type ExecutionMode @@ -32,7 +32,7 @@ type ExecutionMode ### `ProfileHarness` -`type` +`type` — Resolve a ProfileHarness as a Harness, RouterHarness, null, or undefined value ```ts type ProfileHarness @@ -56,7 +56,7 @@ type ProfileHarness ### `RouterHarness` -`type` +`type` — Provide a type alias for the ROUTER_HARNESS constant to enable consistent router harness usage ```ts type RouterHarness diff --git a/docs/api/runtime.md b/docs/api/runtime.md index 39d14d2..0e8c705 100644 --- a/docs/api/runtime.md +++ b/docs/api/runtime.md @@ -8,7 +8,7 @@ Source: `src/runtime/index.ts` ### `AgentRuntime` -`interface` +`interface` — Resolve and stream tool execution loops with final results and intermediate events for agent runtime ```ts interface AgentRuntime @@ -24,7 +24,7 @@ interface AgentRuntimeModelConfig ### `AgentTurnOptions` -`interface` +`interface` — Define options for configuring a single agent turn including context, prior messages, prompts, and event handlers ```ts interface AgentTurnOptions @@ -56,7 +56,7 @@ interface AppToolLoopOptions ### `CatalogModel` -`interface` +`interface` — Define the structure and capabilities of a catalog item with optional pricing and feature flags ```ts interface CatalogModel @@ -64,7 +64,7 @@ interface CatalogModel ### `CertifiedDelivery` -`interface` +`interface` — Resolve and manage certified profiles with refresh and composition capabilities ```ts interface CertifiedDelivery @@ -72,7 +72,7 @@ interface CertifiedDelivery ### `CertifiedDeliveryConfig` -`interface` +`interface` — Define configuration options for delivering certified artifacts to a specified tenant target ```ts interface CertifiedDeliveryConfig @@ -88,7 +88,7 @@ interface CertifiedDeliveryConfig ### `CreateAgentRuntimeOptions` -`interface` +`interface` — Define options for creating an agent runtime including model config and optional profile transformation ```ts interface CreateAgentRuntimeOptions @@ -128,7 +128,7 @@ interface CreateAgentRuntimeOptions ### `CreateTangleRouterModelConfigOptions` -`interface` +`interface` — Define configuration options for creating a Tangle router model including API key and model details ```ts interface CreateTangleRouterModelConfigOptions @@ -136,7 +136,7 @@ interface CreateTangleRouterModelConfigOptions ### `DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR` -`const` +`const` — Define the default environment variable name for Tangle billing enforcement ```ts "TANGLE_BILLING_ENFORCEMENT" @@ -144,7 +144,7 @@ interface CreateTangleRouterModelConfigOptions ### `DEFAULT_TANGLE_ROUTER_BASE_URL` -`const` +`const` — Provide the default base URL for the Tangle router API endpoint ```ts "https://router.tangle.tools/v1" @@ -176,7 +176,7 @@ interface CreateTangleRouterModelConfigOptions ### `isTangleExecutionKeyError` -`function` +`function` — Identify whether an error is a TangleExecutionKeyError based on its properties and type ```ts (error: unknown) => error is TangleExecutionKeyError @@ -224,7 +224,7 @@ interface LoopToolCall ### `ModelCatalog` -`interface` +`interface` — Define a catalog containing models with a default ID and fetch timestamp ```ts interface ModelCatalog @@ -240,7 +240,7 @@ interface ModelCatalog ### `OpenAICompatStreamTurnOptions` -`interface` +`interface` — Define options for configuring an OpenAI-compatible streaming chat turn including API details and tools ```ts interface OpenAICompatStreamTurnOptions @@ -264,7 +264,7 @@ interface ResolvedAgentProfile ### `ResolvedTangleExecutionKey` -`interface` +`interface` — Define a resolved key combining an API key with its Tangle execution source ```ts interface ResolvedTangleExecutionKey @@ -272,7 +272,7 @@ interface ResolvedTangleExecutionKey ### `ResolveModelOptions` -`interface` +`interface` — Resolve options for model configuration including environment variables and default router base URL ```ts interface ResolveModelOptions @@ -288,7 +288,7 @@ interface ResolveModelOptions ### `ResolveTangleDevOrUserKeyOptions` -`interface` +`interface` — Resolve options for retrieving a Tangle developer or user API key based on environment and context ```ts interface ResolveTangleDevOrUserKeyOptions @@ -296,7 +296,7 @@ interface ResolveTangleDevOrUserKeyOptions ### `resolveTangleExecutionEnvironment` -`function` +`function` — Resolve the current Tangle execution environment based on provided or process environment variables ```ts (env?: Record) => TangleExecutionEnvironment @@ -320,7 +320,7 @@ interface ResolveTangleDevOrUserKeyOptions ### `resolveUserTangleExecutionKeyForUser` -`function` +`function` — Resolve the Tangle execution key for a specified user using provided environment and API key options ```ts (opts: ResolveUserTangleExecutionKeyForUserOptions) => Promise @@ -328,7 +328,7 @@ interface ResolveTangleDevOrUserKeyOptions ### `ResolveUserTangleExecutionKeyForUserOptions` -`interface` +`interface` — Resolve options for retrieving a user's Tangle execution key with environment and API key access parameters ```ts interface ResolveUserTangleExecutionKeyForUserOptions @@ -336,7 +336,7 @@ interface ResolveUserTangleExecutionKeyForUserOptions ### `ResolveUserTangleExecutionKeyOptions` -`interface` +`interface` — Resolve options for retrieving user API keys within a specific Tangle execution environment ```ts interface ResolveUserTangleExecutionKeyOptions @@ -424,7 +424,7 @@ type SurfacePermissionValue ### `SurfaceRegistry` -`interface` +`interface` — Resolve and build the overlay for a given surface kind within a turn context ```ts interface SurfaceRegistry @@ -432,7 +432,7 @@ interface SurfaceRegistry ### `TangleBillingEnforcementOptions` -`interface` +`interface` — Define options for configuring billing enforcement environment variables and overrides ```ts interface TangleBillingEnforcementOptions @@ -440,7 +440,7 @@ interface TangleBillingEnforcementOptions ### `TangleExecutionEnvironment` -`type` +`type` — Define the environment context for executing Tangle operations ```ts type TangleExecutionEnvironment @@ -448,7 +448,7 @@ type TangleExecutionEnvironment ### `TangleExecutionKeyError` -`class` +`class` — Represent execution key errors with specific codes and HTTP status information ```ts class TangleExecutionKeyError @@ -456,7 +456,7 @@ class TangleExecutionKeyError ### `TangleExecutionKeyErrorCode` -`type` +`type` — Define error codes for Tangle execution key issues related to API key and account connection ```ts type TangleExecutionKeyErrorCode @@ -464,7 +464,7 @@ type TangleExecutionKeyErrorCode ### `tangleExecutionKeyHttpError` -`function` +`function` — Resolve and format TangleExecutionKey HTTP errors into a standardized error object or return null ```ts (error: unknown) => TangleExecutionKeyHttpError | null @@ -472,7 +472,7 @@ type TangleExecutionKeyErrorCode ### `TangleExecutionKeyHttpError` -`interface` +`interface` — Represent HTTP error response containing status, error message, and specific error code ```ts interface TangleExecutionKeyHttpError @@ -480,7 +480,7 @@ interface TangleExecutionKeyHttpError ### `TangleExecutionKeySource` -`type` +`type` — Resolve the source of the Tangle execution key as either local environment or user input ```ts type TangleExecutionKeySource @@ -528,7 +528,7 @@ type ToolLoopStopReason ### `trimOrNull` -`function` +`function` — Resolve a string by trimming whitespace or returning null if empty or undefined ```ts (value: string | null | undefined) => string | null diff --git a/docs/api/sandbox.md b/docs/api/sandbox.md index 694744e..706d7cf 100644 --- a/docs/api/sandbox.md +++ b/docs/api/sandbox.md @@ -8,7 +8,7 @@ Source: `src/sandbox/index.ts` ### `AppToolDescriptor` -`interface` +`interface` — Describe an application tool with its name, unique key, and description ```ts interface AppToolDescriptor @@ -32,7 +32,7 @@ interface AppToolDescriptor ### `attachReasoningEffort` -`function` +`function` — Attach a specified reasoning effort level to an agent profile for a given harness ```ts (profile: AgentProfile, harness: "opencode" | "claude-code" | "nanoclaw" | "kimi-code" | "codex" | "amp" | "factory-dro… @@ -40,7 +40,7 @@ interface AppToolDescriptor ### `AuthenticatedSandboxUser` -`interface` +`interface` — Represent an authenticated user within a sandbox environment with a unique identifier ```ts interface AuthenticatedSandboxUser @@ -48,7 +48,7 @@ interface AuthenticatedSandboxUser ### `bearerSubprotocolToken` -`function` +`function` — Resolve and decode a bearer token from a comma-separated subprotocol string or return null ```ts (value: string | null) => string | null @@ -56,7 +56,7 @@ interface AuthenticatedSandboxUser ### `bearerToken` -`function` +`function` — Extract the token from a bearer authorization string or return null if invalid or missing ```ts (value: string | null) => string | null @@ -64,7 +64,7 @@ interface AuthenticatedSandboxUser ### `buildAppToolMcpServers` -`function` +`function` — Build a mapping of MCP server profiles keyed by tool identifiers from provided options ```ts (options: BuildAppToolMcpServersOptions) => Record @@ -72,7 +72,7 @@ interface AuthenticatedSandboxUser ### `BuildAppToolMcpServersOptions` -`interface` +`interface` — Define options for building MCP server configurations in the app tool environment ```ts interface BuildAppToolMcpServersOptions @@ -80,7 +80,7 @@ interface BuildAppToolMcpServersOptions ### `buildSandboxRuntimeProxyHeaders` -`function` +`function` — Build proxy headers for sandbox runtime including authorization and forwarded headers ```ts (source: Headers, sandboxApiKey: string, forwardHeaders?: string[]) => Headers @@ -88,7 +88,7 @@ interface BuildAppToolMcpServersOptions ### `buildSandboxToolFileMounts` -`function` +`function` — Build file mounts for sandbox tools based on provided options and tool configurations ```ts (options: BuildSandboxToolFileMountsOptions) => AgentProfileFileMount[] @@ -96,7 +96,7 @@ interface BuildAppToolMcpServersOptions ### `BuildSandboxToolFileMountsOptions` -`interface` +`interface` — Define options for building sandbox tool file mounts including tool specifications and paths ```ts interface BuildSandboxToolFileMountsOptions @@ -104,7 +104,7 @@ interface BuildSandboxToolFileMountsOptions ### `buildSandboxToolPathSetupScript` -`function` +`function` — Build a shell script that sets up and exports the sandbox tool binary directory in user profiles ```ts (options: SandboxToolPathOptions) => string @@ -112,7 +112,7 @@ interface BuildSandboxToolFileMountsOptions ### `classifySeveredStream` -`function` +`function` — Resolve the severed stream event to a corresponding sandbox step transition or null ```ts (event: unknown) => SandboxStepTransition | null @@ -120,7 +120,7 @@ interface BuildSandboxToolFileMountsOptions ### `createSandboxTerminalToken` -`function` +`function` — Generate a sandbox terminal token for a given subject with specified options ```ts (subject: TerminalProxyIdentity, opts: SandboxTerminalTokenOptions) => Promise @@ -128,7 +128,7 @@ interface BuildSandboxToolFileMountsOptions ### `createWorkspaceSandboxConnectionHandler` -`function` +`function` — Create a handler to resolve workspace sandbox connections with user and access validation ```ts (opts: WorkspaceSandboxConnectionHandlerOptions) => ({ request, params… @@ -136,7 +136,7 @@ interface BuildSandboxToolFileMountsOptions ### `createWorkspaceSandboxManager` -`function` +`function` — Create a manager to handle workspace sandbox instances with client and options configuration ```ts (opts: WorkspaceSandboxManagerOptions ({ request, params }: WorkspaceSandboxRuntimeProxyArgs) => Promis… @@ -160,7 +160,7 @@ interface BuildSandboxToolFileMountsOptions ### `DEFAULT_SANDBOX_RESOURCES` -`const` +`const` — Define default resource limits and settings for sandbox environments ```ts SandboxResourceConfig @@ -176,7 +176,7 @@ SandboxResourceConfig ### `deleteSecret` -`function` +`function` — Delete a secret by name from the given secret store and return the operation outcome ```ts (store: SecretStore, name: string) => Promise> @@ -184,7 +184,7 @@ SandboxResourceConfig ### `detectInteractiveQuestion` -`function` +`function` — Resolve the interactive question text from a structured event or return null if none found ```ts (event: unknown) => string | null @@ -192,7 +192,7 @@ SandboxResourceConfig ### `driveSandboxTurn` -`function` +`function` — Resolve a sandbox turn by processing a message with given configuration and options ```ts (shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options: DriveSandboxTurnOptio… @@ -200,7 +200,7 @@ SandboxResourceConfig ### `DriveSandboxTurnOptions` -`interface` +`interface` — Define options to manage deterministic session resumption and turn idempotency in sandboxed drive turns ```ts interface DriveSandboxTurnOptions @@ -208,7 +208,7 @@ interface DriveSandboxTurnOptions ### `encodeSandboxRuntimePath` -`function` +`function` — Encode a runtime path by URI-encoding each valid segment and returning null for invalid segments ```ts (runtimePath: string) => string | null @@ -216,7 +216,7 @@ interface DriveSandboxTurnOptions ### `ensureWorkspaceSandbox` -`function` +`function` — Resolve or create a workspace sandbox instance with optional reuse and progress tracking ```ts (shell: SandboxRuntimeConfig, options: EnsureWorkspaceSandboxOptions) => Promise @@ -224,7 +224,7 @@ interface DriveSandboxTurnOptions ### `EnsureWorkspaceSandboxOptions` -`interface` +`interface` — Define options for ensuring a workspace sandbox with provisioning and progress handling ```ts interface EnsureWorkspaceSandboxOptions @@ -248,7 +248,7 @@ interface EnsureWorkspaceSandboxOptions ### `flattenHistory` -`function` +`function` — Build a single string combining conversation history and the current user message ```ts (message: string, history?: { role: "user" | "assistant"; content: string; }[] | undefined) => string @@ -256,7 +256,7 @@ interface EnsureWorkspaceSandboxOptions ### `getClient` -`function` +`function` — Resolve a synchronous sandbox client from provided runtime configuration credentials ```ts (shell: SandboxRuntimeConfig) => SandboxClient @@ -272,7 +272,7 @@ interface EnsureWorkspaceSandboxOptions ### `isTerminalPromptEvent` -`function` +`function` — Determine if an event is a terminal prompt event with type 'result' or 'done ```ts (event: unknown) => boolean @@ -280,7 +280,7 @@ interface EnsureWorkspaceSandboxOptions ### `LivenessProbeConfig` -`interface` +`interface` — Define configuration for liveness probes including sidecar process pattern and optional timeouts ```ts interface LivenessProbeConfig @@ -296,7 +296,7 @@ interface LivenessProbeConfig ### `MemberSyncSeam` -`interface` +`interface` — Map workspace roles to corresponding sandbox permission levels ```ts interface MemberSyncSeam @@ -304,7 +304,7 @@ interface MemberSyncSeam ### `mergeExtraMcp` -`function` +`function` — Resolve conflicts and merge extra MCP profiles into the app tool MCP without overwriting existing keys ```ts (appToolMcp: Record, baseProfileMcp: Record, extra: Recor… @@ -328,7 +328,7 @@ interface MemberSyncSeam ### `mintTerminalProxyToken` -`function` +`function` — Generate a signed token for TerminalProxyIdentity with an expiration based on TTL milliseconds ```ts (secret: string, identity: TerminalProxyIdentity, ttlMs?: number, now?: () => number) => Promise Promise> @@ -424,7 +424,7 @@ interface ProvisionProfileSection ### `resetClientCache` -`function` +`function` — Reset the client cache to clear stored data and force fresh retrieval ```ts () => void @@ -432,7 +432,7 @@ interface ProvisionProfileSection ### `ResolvedModel` -`interface` +`interface` — Represent a fully configured model with optional API key and base URL for sandbox platform integration ```ts interface ResolvedModel @@ -440,7 +440,7 @@ interface ResolvedModel ### `resolveModel` -`function` +`function` — Resolve and return the appropriate model configuration based on provider settings and optional overrides ```ts (config: ProviderResolutionConfig | undefined, override?: { model?: string | undefined; modelApiKey?: string | undefine… @@ -448,7 +448,7 @@ interface ResolvedModel ### `resolveSandboxClientCredentials` -`function` +`function` — Resolve sandbox client credentials based on environment and provided options asynchronously ```ts (options?: ResolveSandboxClientCredentialsOptions) => Promise @@ -456,7 +456,7 @@ interface ResolvedModel ### `ResolveSandboxClientCredentialsOptions` -`interface` +`interface` — Resolve options for obtaining sandbox client credentials from environment variables and classification ```ts interface ResolveSandboxClientCredentialsOptions @@ -464,7 +464,7 @@ interface ResolveSandboxClientCredentialsOptions ### `runSandboxPrompt` -`function` +`function` — Resolve a sandbox prompt by streaming and aggregating message parts into a complete string ```ts (shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options?: StreamSandboxPromptO… @@ -472,7 +472,7 @@ interface ResolveSandboxClientCredentialsOptions ### `runSandboxToolPathSetup` -`function` +`function` — Resolve the sandbox environment PATH setup by executing the configuration script with given options ```ts (box: SandboxInstance, options: SandboxToolPathOptions) => Promise> @@ -480,7 +480,7 @@ interface ResolveSandboxClientCredentialsOptions ### `SandboxApiCredentials` -`interface` +`interface` — Define credentials required to access the sandbox API environment ```ts interface SandboxApiCredentials @@ -488,7 +488,7 @@ interface SandboxApiCredentials ### `SandboxBuildContext` -`interface` +`interface` — Define the context for building a sandbox including workspace, integrations, and optional user ID ```ts interface SandboxBuildContext @@ -496,7 +496,7 @@ interface SandboxBuildContext ### `SandboxClientCredentials` -`interface` +`interface` — Define client credentials for accessing the sandbox environment with API key and base URL ```ts interface SandboxClientCredentials @@ -520,7 +520,7 @@ interface SandboxExecChannel ### `SandboxExecOptions` -`interface` +`interface` — Define options to execute code within a sandbox environment with optional session control ```ts interface SandboxExecOptions @@ -528,7 +528,7 @@ interface SandboxExecOptions ### `SandboxFileBytesOutcome` -`type` +`type` — Represent the outcome of reading sandbox file bytes with success status and corresponding data or error ```ts type SandboxFileBytesOutcome @@ -536,7 +536,7 @@ type SandboxFileBytesOutcome ### `SandboxFileSizeOutcome` -`type` +`type` — Resolve the outcome of a sandbox file size check with success status and value or error message ```ts type SandboxFileSizeOutcome @@ -544,7 +544,7 @@ type SandboxFileSizeOutcome ### `SandboxPermissionLevel` -`type` +`type` — Define permission levels for sandbox access and control ```ts type SandboxPermissionLevel @@ -552,7 +552,7 @@ type SandboxPermissionLevel ### `SandboxResourceConfig` -`interface` +`interface` — Define configuration parameters for sandbox resource allocation and lifecycle management ```ts interface SandboxResourceConfig @@ -560,7 +560,7 @@ interface SandboxResourceConfig ### `SandboxRestoreSpec` -`interface` +`interface` — Define the specification for restoring a sandbox from a snapshot or another sandbox ID ```ts interface SandboxRestoreSpec @@ -568,7 +568,7 @@ interface SandboxRestoreSpec ### `SandboxRuntimeAuthRefreshError` -`class` +`class` — Represent an error thrown when sandbox runtime authentication refresh fails for a specific stage and name ```ts class SandboxRuntimeAuthRefreshError @@ -576,7 +576,7 @@ class SandboxRuntimeAuthRefreshError ### `SandboxRuntimeConfig` -`interface` +`interface` — Define runtime configuration methods for sandbox environments including credentials, metadata, and permissions ```ts interface SandboxRuntimeConfig @@ -584,7 +584,7 @@ interface SandboxRuntimeConfig ### `SandboxRuntimeConnection` -`interface` +`interface` — Define a connection configuration for sandbox runtime including URL and optional server-side auth token ```ts interface SandboxRuntimeConnection @@ -592,7 +592,7 @@ interface SandboxRuntimeConnection ### `SandboxScope` -`interface` +`interface` — Define a scope containing workspace and optional user identifiers for sandbox environments ```ts interface SandboxScope @@ -600,7 +600,7 @@ interface SandboxScope ### `SandboxStepTransition` -`type` +`type` — Define transitions marking the start or finish of a sandbox step with associated details ```ts type SandboxStepTransition @@ -608,7 +608,7 @@ type SandboxStepTransition ### `SandboxTerminalTokenOptions` -`interface` +`interface` — Define options for generating a sandbox terminal token including secret and expiration settings ```ts interface SandboxTerminalTokenOptions @@ -616,7 +616,7 @@ interface SandboxTerminalTokenOptions ### `SandboxTerminalTokenResult` -`interface` +`interface` — Provide token and expiration details for a sandbox terminal session ```ts interface SandboxTerminalTokenResult @@ -624,7 +624,7 @@ interface SandboxTerminalTokenResult ### `SandboxTerminalTokenSubject` -`type` +`type` — Resolve the identity type used for sandbox terminal token subjects ```ts type SandboxTerminalTokenSubject @@ -632,7 +632,7 @@ type SandboxTerminalTokenSubject ### `SandboxTerminalWsMatch` -`interface` +`interface` — Define the structure for matching a sandbox terminal WebSocket with workspace and path details ```ts interface SandboxTerminalWsMatch @@ -640,7 +640,7 @@ interface SandboxTerminalWsMatch ### `sandboxToolBinDir` -`function` +`function` — Resolve the binary directory path for a sandbox tool based on provided options ```ts (options: SandboxToolPathOptions) => string @@ -648,7 +648,7 @@ interface SandboxTerminalWsMatch ### `sandboxToolPath` -`function` +`function` — Resolve the file system path to a specified sandbox tool based on given options ```ts (options: SandboxToolPathOptions & { toolName: string; }) => string @@ -656,7 +656,7 @@ interface SandboxTerminalWsMatch ### `SandboxToolPathOptions` -`interface` +`interface` — Define options for resolving sandbox tool paths including appName, baseDir, and binDir ```ts interface SandboxToolPathOptions @@ -664,7 +664,7 @@ interface SandboxToolPathOptions ### `sandboxToolRootDir` -`function` +`function` — Resolve the root directory path for a sandbox tool based on provided options ```ts (options: SandboxToolPathOptions) => string @@ -672,7 +672,7 @@ interface SandboxToolPathOptions ### `SandboxToolSpec` -`interface` +`interface` — Define the specification for a sandbox tool including its name, content, and optional executability ```ts interface SandboxToolSpec @@ -680,7 +680,7 @@ interface SandboxToolSpec ### `ScopedTokenResult` -`interface` +`interface` — Represent a token with its expiration date and associated scope ```ts interface ScopedTokenResult @@ -688,7 +688,7 @@ interface ScopedTokenResult ### `SecretStore` -`interface` +`interface` — Define methods to create, update, retrieve, and delete secrets asynchronously ```ts interface SecretStore @@ -696,7 +696,7 @@ interface SecretStore ### `secretStoreFromClient` -`function` +`function` — Resolve a SecretStore interface using the provided SandboxRuntimeConfig shell ```ts (shell: SandboxRuntimeConfig) => SecretStore @@ -712,7 +712,7 @@ interface SecretStore ### `splitDeferredProfileFiles` -`function` +`function` — Split profile files into inline deferred files and a lean profile without them ```ts (profile: AgentProfile) => { leanProfile: AgentProfile; deferredFiles: AgentProfileFileMount[]; } @@ -728,7 +728,7 @@ interface SecretStore ### `StoppedSandboxResumeFailure` -`interface` +`interface` — Describe the failure details when resuming a stopped sandbox instance ```ts interface StoppedSandboxResumeFailure @@ -736,7 +736,7 @@ interface StoppedSandboxResumeFailure ### `StoppedSandboxResumeRecovery` -`interface` +`interface` — Define the structure for resuming a stopped sandbox with replacement key and optional restore options ```ts interface StoppedSandboxResumeRecovery @@ -752,7 +752,7 @@ interface StorageConfig ### `storeSecret` -`function` +`function` — Resolve storing a secret by creating or updating it in the given SecretStore ```ts (store: SecretStore, name: string, value: string) => Promise> @@ -760,7 +760,7 @@ interface StorageConfig ### `streamSandboxPrompt` -`function` +`function` — Resolve and stream AI-generated responses from a sandboxed environment based on input messages and options ```ts (shell: SandboxRuntimeConfig, box: SandboxInstance, message: string | PromptInputPart[], options?: StreamSandboxPromptO… @@ -768,7 +768,7 @@ interface StorageConfig ### `StreamSandboxPromptOptions` -`interface` +`interface` — Define options for configuring and controlling a streaming sandbox prompt session ```ts interface StreamSandboxPromptOptions @@ -776,7 +776,7 @@ interface StreamSandboxPromptOptions ### `syncSandboxMemberAdd` -`function` +`function` — Resolve adding a user with a specific role to a sandbox and return the operation outcome ```ts (box: SandboxInstance, seam: MemberSyncSeam, userId: string, role: string) => Promise> @@ -784,7 +784,7 @@ interface StreamSandboxPromptOptions ### `syncSandboxMemberRemove` -`function` +`function` — Remove a member from the sandbox while preserving their home directory and handle the outcome ```ts (box: SandboxInstance, userId: string) => Promise> @@ -792,7 +792,7 @@ interface StreamSandboxPromptOptions ### `syncSandboxMemberRole` -`function` +`function` — Synchronize a sandbox member's role by updating permissions based on the provided role mapping ```ts (box: SandboxInstance, seam: MemberSyncSeam, userId: string, role: string) => Promise> @@ -800,7 +800,7 @@ interface StreamSandboxPromptOptions ### `TerminalProxyIdentity` -`interface` +`interface` — Define identity details for a terminal proxy including user, workspace, and sandbox identifiers ```ts interface TerminalProxyIdentity @@ -808,7 +808,7 @@ interface TerminalProxyIdentity ### `terminalTokenFromRequest` -`function` +`function` — Resolve the terminal token from request headers using Authorization or Sec-WebSocket-Protocol fields ```ts (headers: Headers) => string | null @@ -816,7 +816,7 @@ interface TerminalProxyIdentity ### `verifySandboxTerminalToken` -`function` +`function` — Verify the validity of a sandbox terminal token against the expected identity and options ```ts (token: string, expected: TerminalProxyIdentity, opts: SandboxTerminalTokenOptions) => Promise @@ -824,7 +824,7 @@ interface TerminalProxyIdentity ### `verifyTerminalProxyToken` -`function` +`function` — Verify the authenticity and validity of a terminal proxy token against expected identity and timestamp ```ts (secret: string, token: string, expected: TerminalProxyIdentity, now?: () => number) => Promise @@ -832,7 +832,7 @@ interface TerminalProxyIdentity ### `WorkspaceSandboxConnectionArgs` -`interface` +`interface` — Define arguments required to establish a workspace sandbox connection ```ts interface WorkspaceSandboxConnectionArgs @@ -840,7 +840,7 @@ interface WorkspaceSandboxConnectionArgs ### `WorkspaceSandboxConnectionHandlerOptions` -`interface` +`interface` — Define options to handle workspace sandbox connections with user authentication and access control ```ts interface WorkspaceSandboxConnectionHandlerOptions @@ -848,7 +848,7 @@ interface WorkspaceSandboxConnectionHandlerOptions ### `WorkspaceSandboxEnsureContext` -`interface` +`interface` — Define the context containing workspace and user identifiers for sandbox environment operations ```ts interface WorkspaceSandboxEnsureContext @@ -856,7 +856,7 @@ interface WorkspaceSandboxEnsureContext ### `WorkspaceSandboxInstanceLike` -`interface` +`interface` — Define the shape of a workspace sandbox instance including its connection details and status ```ts interface WorkspaceSandboxInstanceLike @@ -864,7 +864,7 @@ interface WorkspaceSandboxInstanceLike ### `WorkspaceSandboxManager` -`interface` +`interface` — Manage workspace sandboxes by ensuring their creation and retrieval for specified users ```ts interface WorkspaceSandboxManager @@ -872,7 +872,7 @@ interface WorkspaceSandboxManager ### `WorkspaceSandboxManagerOptions` -`interface` +`interface` — Define configuration options for managing and interacting with workspace sandboxes ```ts interface WorkspaceSandboxManagerOptions @@ -880,7 +880,7 @@ interface WorkspaceSandboxManagerOptions ### `WorkspaceSandboxRuntimeProxyArgs` -`interface` +`interface` — Define arguments for proxying runtime requests within a workspace sandbox environment ```ts interface WorkspaceSandboxRuntimeProxyArgs @@ -888,7 +888,7 @@ interface WorkspaceSandboxRuntimeProxyArgs ### `WorkspaceSandboxRuntimeProxyHandlerOptions` -`interface` +`interface` — Define options for handling workspace sandbox runtime proxy including user, access, credentials, and connection retrieval ```ts interface WorkspaceSandboxRuntimeProxyHandlerOptions @@ -896,7 +896,7 @@ interface WorkspaceSandboxRuntimeProxyHandlerOptions ### `WorkspaceSandboxTerminalUpgradeHandlerOptions` -`interface` +`interface` — Define options to handle user authentication, workspace access, and sandbox API credential retrieval ```ts interface WorkspaceSandboxTerminalUpgradeHandlerOptions @@ -904,7 +904,7 @@ interface WorkspaceSandboxTerminalUpgradeHandlerOptions ### `WriteProfileFilesOptions` -`interface` +`interface` — Define options to control execution timeout, pacing, and retry behavior when writing profile files ```ts interface WriteProfileFilesOptions @@ -912,7 +912,7 @@ interface WriteProfileFilesOptions ### `writeProfileFilesToBox` -`function` +`function` — Write profile files to a sandbox with pacing, retries, and optional execution timeout handling ```ts (box: SandboxInstance, files: AgentProfileFileMount[], options?: WriteProfileFilesOptions) => Promise> diff --git a/docs/api/sequences-drizzle.md b/docs/api/sequences-drizzle.md index 2a12c5c..6c04a65 100644 --- a/docs/api/sequences-drizzle.md +++ b/docs/api/sequences-drizzle.md @@ -8,7 +8,7 @@ Source: `src/sequences/drizzle.ts` ### `createDrizzleSequenceStore` -`function` +`function` — Create a sequence store scoped to a specific sequence and workspace with database access and media resolution ```ts (options: CreateDrizzleSequenceStoreOptions) => SequenceStore @@ -16,7 +16,7 @@ Source: `src/sequences/drizzle.ts` ### `CreateDrizzleSequenceStoreOptions` -`interface` +`interface` — Define options for creating a Drizzle sequence store including database, tables, scope, and media resolver ```ts interface CreateDrizzleSequenceStoreOptions @@ -24,7 +24,7 @@ interface CreateDrizzleSequenceStoreOptions ### `createSequenceTables` -`function` +`function` — Build SQLite sequence tables with defined columns and relationships based on provided options ```ts (opts: CreateSequenceTablesOptions) => { sequences: SQLiteTableWithColumns<{ name: "sequence"; schema: undefined; colum… @@ -32,7 +32,7 @@ interface CreateDrizzleSequenceStoreOptions ### `CreateSequenceTablesOptions` -`interface` +`interface` — Define options for creating sequence-related database tables including workspace and user tables ```ts interface CreateSequenceTablesOptions @@ -40,7 +40,7 @@ interface CreateSequenceTablesOptions ### `SequenceClipRow` -`type` +`type` — Resolve the selected fields of sequence clips from the sequence tables data structure ```ts type SequenceClipRow @@ -56,7 +56,7 @@ type SequenceDatabase ### `SequenceDecisionRow` -`type` +`type` — Resolve a sequence decision row from the sequenceDecisions table data ```ts type SequenceDecisionRow @@ -64,7 +64,7 @@ type SequenceDecisionRow ### `SequenceExportRow` -`type` +`type` — Resolve a row type representing exported sequence data from sequenceExports table ```ts type SequenceExportRow @@ -88,7 +88,7 @@ type SequenceParentTable ### `SequenceRow` -`type` +`type` — Resolve a sequence row by inferring the selected fields from the sequences table ```ts type SequenceRow @@ -96,7 +96,7 @@ type SequenceRow ### `SequenceTables` -`type` +`type` — Resolve sequence tables by invoking the createSequenceTables factory function ```ts type SequenceTables @@ -104,7 +104,7 @@ type SequenceTables ### `SequenceTrackRow` -`type` +`type` — Resolve the selected sequence track row from the sequenceTracks table ```ts type SequenceTrackRow diff --git a/docs/api/sequences-react.md b/docs/api/sequences-react.md index 9628435..09e0684 100644 --- a/docs/api/sequences-react.md +++ b/docs/api/sequences-react.md @@ -8,7 +8,7 @@ Source: `src/sequences-react/index.ts` ### `addCaptionCommand` -`function` +`function` — Resolve a command to add a caption to a specified caption track within a timeline ```ts (input: AddCaptionInput) => TimelineCommand @@ -16,7 +16,7 @@ Source: `src/sequences-react/index.ts` ### `AddCaptionInput` -`interface` +`interface` — Define input parameters for adding a caption clip to a sequence timeline ```ts interface AddCaptionInput @@ -32,7 +32,7 @@ interface AddCaptionInput ### `ApplySnapOptions` -`interface` +`interface` — Define options to configure snapping behavior including zoom, threshold, and exclusion criteria ```ts interface ApplySnapOptions @@ -136,7 +136,7 @@ interface ClipTrimCommit ### `CommandStack` -`interface` +`interface` — Manage and track command execution with undo, redo, state subscription, and timeline reset capabilities ```ts interface CommandStack @@ -168,7 +168,7 @@ interface CommandStack ### `createCommandStack` -`function` +`function` — Create a command stack managing undo and redo operations for a given timeline ```ts (initial: SequenceTimeline) => CommandStack @@ -192,7 +192,7 @@ interface CommandStack ### `createPlaybackClock` -`function` +`function` — Create a playback clock that manages frame timing and playback state based on configuration ```ts (config: PlaybackClockConfig) => PlaybackClock @@ -208,7 +208,7 @@ interface CommandStack ### `createWhisperTranscriptionProvider` -`function` +`function` — Create a Whisper-based transcription provider with optional model configuration ```ts (opts?: { model?: string | undefined; } | undefined) => TranscriptionProvider @@ -216,7 +216,7 @@ interface CommandStack ### `createZoomMath` -`function` +`function` — Create a ZoomMath object that validates config and calculates zoom ratio within bounds ```ts (config: ZoomMathConfig) => ZoomMath @@ -224,7 +224,7 @@ interface CommandStack ### `DEFAULT_MAX_MEDIA_ELEMENTS` -`const` +`const` — Define the default maximum number of media elements allowed in a collection ```ts 4 @@ -232,7 +232,7 @@ interface CommandStack ### `DEFAULT_TIMELINE_LABELS` -`const` +`const` — Provide default labels and accessibility text for timeline editor UI elements ```ts Required @@ -240,7 +240,7 @@ Required ### `DEFAULT_WHISPER_MODEL` -`const` +`const` — Provide the default Whisper model identifier for ONNX community large v3 turbo ```ts "onnx-community/whisper-large-v3-turbo" @@ -256,7 +256,7 @@ Required ### `DeleteClipInput` -`interface` +`interface` — Define input parameters required to delete a clip from a sequence timeline ```ts interface DeleteClipInput @@ -280,7 +280,7 @@ interface EditorTimelineState ### `FrameRect` -`interface` +`interface` — Define a rectangular frame with position and size properties x, y, width, and height ```ts interface FrameRect @@ -336,7 +336,7 @@ interface LetterboxRect ### `MediaElementPool` -`interface` +`interface` — Manage a pool of media elements to acquire, check, count, and dispose resources efficiently ```ts interface MediaElementPool @@ -360,7 +360,7 @@ interface MediaElementPool ### `MoveClipInput` -`interface` +`interface` — Define input parameters to move a clip within a timeline including optional track and resolver ```ts interface MoveClipInput @@ -384,7 +384,7 @@ interface MoveDragInput ### `needsSeek` -`function` +`function` — Determine if seeking is required based on the difference between current and target times ```ts (currentTimeSeconds: number, targetSeconds: number) => boolean @@ -400,7 +400,7 @@ interface MoveDragInput ### `placeClipCommand` -`function` +`function` — Resolve and validate clip placement parameters to create a timeline command ```ts (input: PlaceClipInput) => TimelineCommand @@ -408,7 +408,7 @@ interface MoveDragInput ### `PlaceClipInput` -`interface` +`interface` — Define input parameters required to place a clip within a sequence timeline ```ts interface PlaceClipInput @@ -424,7 +424,7 @@ interface PlaybackClock ### `PlaybackClockConfig` -`interface` +`interface` — Define configuration settings for playback clock including frames per second and total duration frames ```ts interface PlaybackClockConfig @@ -432,7 +432,7 @@ interface PlaybackClockConfig ### `PooledElementLease` -`interface` +`interface` — Manage a leased element from a pool and release it to enable LRU eviction ```ts interface PooledElementLease @@ -504,7 +504,7 @@ LazyExoticComponent<(props: TimelineEditorProps) => Element> ### `SetClipTextInput` -`interface` +`interface` — Define input parameters for setting text and optional language on a specific clip in a timeline ```ts interface SetClipTextInput @@ -536,7 +536,7 @@ interface SnapIndicatorLineProps ### `SnapPoint` -`interface` +`interface` — Define a point in a timeline where snapping occurs based on frame and kind ```ts interface SnapPoint @@ -544,7 +544,7 @@ interface SnapPoint ### `SnapResult` -`interface` +`interface` — Describe the result of snapping a point to a frame including success status and snapped point details ```ts interface SnapResult @@ -560,7 +560,7 @@ interface SnapResult ### `SplitClipInput` -`interface` +`interface` — Define input parameters for splitting a clip at a specific frame within a timeline ```ts interface SplitClipInput @@ -608,7 +608,7 @@ interface TimelineEditorLabels ### `TimelineEditorProps` -`interface` +`interface` — Define properties and callbacks for editing and applying operations on a sequence timeline ```ts interface TimelineEditorProps @@ -728,7 +728,7 @@ interface TimelineTrackRowProps ### `ToggleClipDisabledInput` -`interface` +`interface` — Define input parameters to toggle the disabled state of a clip within a timeline ```ts interface ToggleClipDisabledInput @@ -744,7 +744,7 @@ interface TranscriptionProvider ### `TranscriptionSegment` -`interface` +`interface` — Represent a segment of transcription with text and start and end times in seconds ```ts interface TranscriptionSegment @@ -760,7 +760,7 @@ interface TranscriptionSegment ### `TrimClipInput` -`interface` +`interface` — Define input parameters for trimming a clip within a sequence timeline ```ts interface TrimClipInput @@ -832,7 +832,7 @@ interface WaveformData ### `WhisperOutput` -`interface` +`interface` — Define the structure for transcribed text output with optional segmented chunks ```ts interface WhisperOutput @@ -864,7 +864,7 @@ interface ZoomMath ### `ZoomMathConfig` -`interface` +`interface` — Define configuration settings for minimum and maximum zoom levels ```ts interface ZoomMathConfig diff --git a/docs/api/sequences.md b/docs/api/sequences.md index c905a63..2a3e9bd 100644 --- a/docs/api/sequences.md +++ b/docs/api/sequences.md @@ -8,7 +8,7 @@ Source: `src/sequences/index.ts` ### `AddCaptionOperation` -`interface` +`interface` — Add a caption with optional language, timing, and track placement details ```ts interface AddCaptionOperation @@ -16,7 +16,7 @@ interface AddCaptionOperation ### `applySequenceOperation` -`function` +`function` — Apply a sequence operation to update the store and timeline asynchronously ```ts (store: SequenceStore, timeline: SequenceTimeline, op: SequenceOperation, ctx: SequenceOperationContext) => Promise<...> @@ -32,7 +32,7 @@ interface AddCaptionOperation ### `assertClipFitsSequence` -`function` +`function` — Validate that a clip's start and duration fit within the sequence duration without overflow ```ts (input: { startFrame: number; durationFrames: number; sequenceDurationFrames: number; label: string; }) => void @@ -56,7 +56,7 @@ interface AddCaptionOperation ### `BuildCaptionChunksOptions` -`interface` +`interface` — Define options to configure caption chunk size, duration, and frame rate constraints ```ts interface BuildCaptionChunksOptions @@ -96,7 +96,7 @@ interface BuildCaptionChunksOptions ### `BuildSequencesMcpServerEntryOptions` -`type` +`type` — Extend ScopedMcpServerEntryOptions to configure MCP server entry options for sequence building ```ts type BuildSequencesMcpServerEntryOptions @@ -144,7 +144,7 @@ interface CaptionCoverageEntry ### `CaptionExportOptions` -`interface` +`interface` — Define options to export captions filtered by an optional BCP-47 language tag ```ts interface CaptionExportOptions @@ -152,7 +152,7 @@ interface CaptionExportOptions ### `CaptionTargetResolution` -`type` +`type` — Resolve caption target by specifying an existing track or creating a new one with language and name ```ts type CaptionTargetResolution @@ -176,7 +176,7 @@ type CaptionTargetResolution ### `clampClipDuration` -`function` +`function` — Clamp clip duration to fit within sequence bounds and minimum length constraints ```ts (input: { startFrame: number; durationFrames: number; sequenceDurationFrames: number; }) => number @@ -184,7 +184,7 @@ type CaptionTargetResolution ### `clampClipStart` -`function` +`function` — Clamp the clip start frame within the valid range of the sequence duration and clip length ```ts (input: { startFrame: number; durationFrames: number; sequenceDurationFrames: number; }) => number @@ -192,7 +192,7 @@ type CaptionTargetResolution ### `ContactSheetEntry` -`interface` +`interface` — Describe a single entry in a contact sheet with timing and media source details ```ts interface ContactSheetEntry @@ -200,7 +200,7 @@ interface ContactSheetEntry ### `ContactSheetManifest` -`interface` +`interface` — Define the structure for a contact sheet manifest including metadata and entries ```ts interface ContactSheetManifest @@ -208,7 +208,7 @@ interface ContactSheetManifest ### `createSequencesMcpHandler` -`function` +`function` — Create a handler to process MCP sequence requests with optional playhead frame and server info ```ts (opts: CreateSequencesMcpHandlerOptions) => (request: Request) => Promise @@ -216,7 +216,7 @@ interface ContactSheetManifest ### `CreateSequencesMcpHandlerOptions` -`interface` +`interface` — Define options for creating sequences MCP handler including store, playhead frame, and server info ```ts interface CreateSequencesMcpHandlerOptions @@ -224,7 +224,7 @@ interface CreateSequencesMcpHandlerOptions ### `CreateTrackOperation` -`interface` +`interface` — Define an operation to create a new sequence track with a specified kind and name ```ts interface CreateTrackOperation @@ -232,7 +232,7 @@ interface CreateTrackOperation ### `DEFAULT_SEQUENCES_MCP_DESCRIPTION` -`const` +`const` — Describe live timeline editor features for current video sequence including clip and caption management ```ts "Live timeline editor for the current video sequence: read timeline state, place/move/trim/split clips, add captions, m… @@ -240,7 +240,7 @@ interface CreateTrackOperation ### `DeleteClipOperation` -`interface` +`interface` — Represent a delete clip operation with a specified clip identifier ```ts interface DeleteClipOperation @@ -248,7 +248,7 @@ interface DeleteClipOperation ### `ExtendSequenceOperation` -`interface` +`interface` — Define an operation to extend a sequence by a specified number of frames ```ts interface ExtendSequenceOperation @@ -256,7 +256,7 @@ interface ExtendSequenceOperation ### `findSequenceMcpTool` -`function` +`function` — Resolve the SequenceMcpToolDefinition matching the given name or return undefined ```ts (name: string) => SequenceMcpToolDefinition | undefined @@ -264,7 +264,7 @@ interface ExtendSequenceOperation ### `formatSeconds` -`function` +`function` — Format a number of seconds into a string with integer or two-decimal precision suffix s ```ts (seconds: number) => string @@ -280,7 +280,7 @@ interface ExtendSequenceOperation ### `framesToSeconds` -`function` +`function` — Convert a frame count to seconds based on the given frames per second rate ```ts (frames: number, fps: number) => number @@ -288,7 +288,7 @@ interface ExtendSequenceOperation ### `LanguageFanoutOptions` -`interface` +`interface` — Define options to specify target languages and an optional source language for fan-out operations ```ts interface LanguageFanoutOptions @@ -320,7 +320,7 @@ interface LanguageFanoutOptions ### `MoveClipOperation` -`interface` +`interface` — Resolve an operation to move a clip to a new start frame and optional track ```ts interface MoveClipOperation @@ -328,7 +328,7 @@ interface MoveClipOperation ### `NewSequenceClip` -`interface` +`interface` — Define properties for a new sequence clip including timing, labels, and optional metadata ```ts interface NewSequenceClip @@ -336,7 +336,7 @@ interface NewSequenceClip ### `NewSequenceDecision` -`interface` +`interface` — Define the structure for a new sequence decision with optional metadata and acceptance status ```ts interface NewSequenceDecision @@ -344,7 +344,7 @@ interface NewSequenceDecision ### `NewSequenceTrack` -`interface` +`interface` — Define properties for a new sequence track including kind, name, and optional sort order ```ts interface NewSequenceTrack @@ -360,7 +360,7 @@ interface NewSequenceTrack ### `OtioClip` -`interface` +`interface` — Define a clip object with metadata, source range, and media reference according to OTIO schema ```ts interface OtioClip @@ -368,7 +368,7 @@ interface OtioClip ### `OtioExternalReference` -`interface` +`interface` — Define the structure for an external media reference with schema, URL, and optional time range ```ts interface OtioExternalReference @@ -376,7 +376,7 @@ interface OtioExternalReference ### `OtioGap` -`interface` +`interface` — Define the structure for a gap element with schema, name, and source time range properties ```ts interface OtioGap @@ -384,7 +384,7 @@ interface OtioGap ### `OtioMissingReference` -`interface` +`interface` — Represent missing references in OTIO with a fixed schema identifier ```ts interface OtioMissingReference @@ -392,7 +392,7 @@ interface OtioMissingReference ### `OtioRationalTime` -`interface` +`interface` — Represent a rational time value with a specific rate and numeric value for OTIO schema ```ts interface OtioRationalTime @@ -400,7 +400,7 @@ interface OtioRationalTime ### `OtioStack` -`interface` +`interface` — Represent a stack container holding a named collection of OtioTrack children ```ts interface OtioStack @@ -408,7 +408,7 @@ interface OtioStack ### `OtioTimeline` -`interface` +`interface` — Define the structure of a timeline with metadata, tracks, and global start time in OTIO format ```ts interface OtioTimeline @@ -416,7 +416,7 @@ interface OtioTimeline ### `OtioTimeRange` -`interface` +`interface` — Define a time range with a start time and duration using OtioRationalTime values ```ts interface OtioTimeRange @@ -424,7 +424,7 @@ interface OtioTimeRange ### `OtioTrack` -`interface` +`interface` — Define a track containing video or audio clips with metadata and child elements ```ts interface OtioTrack @@ -440,7 +440,7 @@ interface OtioTrack ### `PlaceClipOperation` -`interface` +`interface` — Define an operation to place a media clip with timing, track, and playback options ```ts interface PlaceClipOperation @@ -456,7 +456,7 @@ interface PlaceClipOperation ### `QueueExportOperation` -`interface` +`interface` — Define the structure for a queue export operation with format and optional metadata ```ts interface QueueExportOperation @@ -488,7 +488,7 @@ interface QueueExportOperation ### `secondsToFrames` -`function` +`function` — Convert seconds to the nearest whole number of frames based on frames per second ```ts (seconds: number, fps: number) => number @@ -496,7 +496,7 @@ interface QueueExportOperation ### `SEQUENCE_EXPORT_FORMATS` -`const` +`const` — Define supported export formats for sequence outputs including video, subtitle, and metadata types ```ts readonly ["mp4", "otio", "xml", "edl", "vtt", "srt", "contact_sheet"] @@ -504,7 +504,7 @@ readonly ["mp4", "otio", "xml", "edl", "vtt", "srt", "contact_sheet"] ### `SEQUENCE_MCP_TOOLS` -`const` +`const` — Resolve an array of immutable sequence MCP tool definitions for timeline and frame operations ```ts readonly SequenceMcpToolDefinition[] @@ -512,7 +512,7 @@ readonly SequenceMcpToolDefinition[] ### `SEQUENCE_MEDIA_KINDS` -`const` +`const` — Define the allowed media kinds for sequences including video, image, and audio ```ts readonly ["video", "image", "audio"] @@ -520,7 +520,7 @@ readonly ["video", "image", "audio"] ### `SEQUENCE_OPERATION_TYPES` -`const` +`const` — List all valid sequence operation types used in editing workflows ```ts readonly ("place_clip" | "add_caption" | "move_clip" | "trim_clip" | "split_clip" | "set_clip_text" | "set_clip_disable… @@ -528,7 +528,7 @@ readonly ("place_clip" | "add_caption" | "move_clip" | "trim_clip" | "split_clip ### `SEQUENCE_TRACK_KINDS` -`const` +`const` — Define immutable sequence track kinds for video, audio, caption, reference, and agent ```ts readonly ["video", "audio", "caption", "reference", "agent"] @@ -544,7 +544,7 @@ type SequenceApplyResult ### `SequenceClip` -`interface` +`interface` — Define properties for a media sequence clip including timing, source, track, and caption details ```ts interface SequenceClip @@ -560,7 +560,7 @@ interface SequenceClipMedia ### `SequenceClipPatch` -`interface` +`interface` — Define optional properties to update or patch a sequence clip's attributes in a timeline ```ts interface SequenceClipPatch @@ -576,7 +576,7 @@ interface SequenceDecision ### `SequenceExportFormat` -`type` +`type` — Define export formats available for sequence data including video, subtitle, and metadata types ```ts type SequenceExportFormat @@ -584,7 +584,7 @@ type SequenceExportFormat ### `SequenceExportRecord` -`interface` +`interface` — Describe a record representing the export details and status of a sequence ```ts interface SequenceExportRecord @@ -592,7 +592,7 @@ interface SequenceExportRecord ### `SequenceExportStatus` -`type` +`type` — Represent export status of a sequence as queued, processing, completed, failed, or cancelled ```ts type SequenceExportStatus @@ -608,7 +608,7 @@ interface SequenceFrameSnapshot ### `SequenceMcpToolDefinition` -`interface` +`interface` — Define a tool with metadata and a run method for processing input within a specific environment ```ts interface SequenceMcpToolDefinition @@ -624,7 +624,7 @@ interface SequenceMcpToolEnv ### `SequenceMediaKind` -`type` +`type` — Define media types allowed in a sequence including video, image, and audio ```ts type SequenceMediaKind @@ -632,7 +632,7 @@ type SequenceMediaKind ### `SequenceMeta` -`interface` +`interface` — Describe metadata and properties of a media sequence including dimensions, duration, and status ```ts interface SequenceMeta @@ -640,7 +640,7 @@ interface SequenceMeta ### `SequenceOperation` -`type` +`type` — Represent sequence editing actions for manipulating clips, tracks, captions, and exports ```ts type SequenceOperation @@ -656,7 +656,7 @@ interface SequenceOperationContext ### `SequenceOperationType` -`type` +`type` — Extract the type of operation from a sequence operation object ```ts type SequenceOperationType @@ -680,7 +680,7 @@ readonly ["2025-06-18", "2025-03-26", "2024-11-05"] ### `SequencesMcpServerInfo` -`interface` +`interface` — Describe server information including name and version for Sequences MCP integration ```ts interface SequencesMcpServerInfo @@ -688,7 +688,7 @@ interface SequencesMcpServerInfo ### `SequenceStatus` -`type` +`type` — Define sequence status as one of the specific lifecycle stages draft, active, exporting, or archived ```ts type SequenceStatus @@ -696,7 +696,7 @@ type SequenceStatus ### `SequenceStore` -`interface` +`interface` — Manage sequences by providing methods to get timelines, clips, and modify tracks and clips ```ts interface SequenceStore @@ -720,7 +720,7 @@ interface SequenceTimeline ### `SequenceTrack` -`interface` +`interface` — Define properties and state for a sequence track including id, kind, name, order, and flags ```ts interface SequenceTrack @@ -736,7 +736,7 @@ type SequenceTrackKind ### `SetClipDisabledOperation` -`interface` +`interface` — Define an operation to enable or disable a clip by its identifier ```ts interface SetClipDisabledOperation @@ -744,7 +744,7 @@ interface SetClipDisabledOperation ### `SetClipTextOperation` -`interface` +`interface` — Resolve an operation to set clipboard text with optional language and clip identifier ```ts interface SetClipTextOperation @@ -760,7 +760,7 @@ interface SetClipTextOperation ### `SplitClipOperation` -`interface` +`interface` — Split a clip at a specified frame inside the clip to create two separate segments ```ts interface SplitClipOperation @@ -768,7 +768,7 @@ interface SplitClipOperation ### `TimelineClipBounds` -`interface` +`interface` — Define the start frame and duration in frames for a timeline clip's bounds ```ts interface TimelineClipBounds @@ -776,7 +776,7 @@ interface TimelineClipBounds ### `TimelineInterval` -`interface` +`interface` — Define a time range with inclusive start and end frame numbers ```ts interface TimelineInterval @@ -800,7 +800,7 @@ interface TranscriptSegment ### `TrimClipOperation` -`interface` +`interface` — Define an operation to trim a clip by adjusting its start, duration, and optional source in/out points ```ts interface TrimClipOperation @@ -808,7 +808,7 @@ interface TrimClipOperation ### `validateAddCaption` -`function` +`function` — Validate the parameters and context of an AddCaptionOperation within a sequence timeline ```ts (timeline: SequenceTimeline, operation: AddCaptionOperation, ctx: SequenceOperationContext) => void @@ -816,7 +816,7 @@ interface TrimClipOperation ### `validateCreateTrack` -`function` +`function` — Validate that a CreateTrackOperation has a supported kind and a non-empty name ```ts (operation: CreateTrackOperation) => void @@ -824,7 +824,7 @@ interface TrimClipOperation ### `validateDeleteClip` -`function` +`function` — Validate that the clip to delete exists and is mutable in the given timeline ```ts (timeline: SequenceTimeline, operation: DeleteClipOperation) => void @@ -832,7 +832,7 @@ interface TrimClipOperation ### `validateExtendSequence` -`function` +`function` — Validate that the extend sequence operation has a positive duration and exceeds the last clip end frame ```ts (timeline: SequenceTimeline, operation: ExtendSequenceOperation) => void @@ -840,7 +840,7 @@ interface TrimClipOperation ### `validateMoveClip` -`function` +`function` — Validate that a clip move operation is within bounds and targets a compatible unlocked track ```ts (timeline: SequenceTimeline, operation: MoveClipOperation) => void @@ -848,7 +848,7 @@ interface TrimClipOperation ### `validatePlaceClip` -`function` +`function` — Validate the properties and constraints of a PlaceClipOperation within a SequenceTimeline ```ts (timeline: SequenceTimeline, operation: PlaceClipOperation) => void @@ -856,7 +856,7 @@ interface TrimClipOperation ### `validateQueueExport` -`function` +`function` — Validate that the queue export operation uses a supported export format ```ts (operation: QueueExportOperation) => void @@ -864,7 +864,7 @@ interface TrimClipOperation ### `validateSequenceOperation` -`function` +`function` — Validate a sequence operation against the timeline and context to ensure correctness ```ts (timeline: SequenceTimeline, operation: SequenceOperation, ctx: SequenceOperationContext) => void @@ -872,7 +872,7 @@ interface TrimClipOperation ### `validateSequenceOperations` -`function` +`function` — Validate each operation in a sequence against the timeline and context, throwing detailed errors on failure ```ts (timeline: SequenceTimeline, operations: SequenceOperation[], ctx: SequenceOperationContext) => void @@ -880,7 +880,7 @@ interface TrimClipOperation ### `validateSetClipDisabled` -`function` +`function` — Validate that the clip can be disabled within the given timeline and operation constraints ```ts (timeline: SequenceTimeline, operation: SetClipDisabledOperation) => void @@ -888,7 +888,7 @@ interface TrimClipOperation ### `validateSetClipText` -`function` +`function` — Validate that a SetClipTextOperation targets a caption clip with non-empty text and valid language tag ```ts (timeline: SequenceTimeline, operation: SetClipTextOperation) => void @@ -896,7 +896,7 @@ interface TrimClipOperation ### `validateSplitClip` -`function` +`function` — Validate that a split operation on a clip is within valid frame boundaries and conditions ```ts (timeline: SequenceTimeline, operation: SplitClipOperation) => void @@ -904,7 +904,7 @@ interface TrimClipOperation ### `validateTrimClip` -`function` +`function` — Validate that a trim clip operation respects timeline bounds and source frame constraints ```ts (timeline: SequenceTimeline, operation: TrimClipOperation) => void diff --git a/docs/api/store.md b/docs/api/store.md index 9448a98..7b053a3 100644 --- a/docs/api/store.md +++ b/docs/api/store.md @@ -32,7 +32,7 @@ interface DatabaseProvider ### `DatabaseProviderOptions` -`interface` +`interface` — Define options for configuring database provider behavior including error messaging ```ts interface DatabaseProviderOptions @@ -40,7 +40,7 @@ interface DatabaseProviderOptions ### `KVGetWithMetadataResult` -`interface` +`interface` — Resolve a key-value pair retrieval including its associated metadata and value ```ts interface KVGetWithMetadataResult @@ -48,7 +48,7 @@ interface KVGetWithMetadataResult ### `KVListResult` -`interface` +`interface` — Describe the result of listing keys with completion status and optional pagination cursor ```ts interface KVListResult @@ -56,7 +56,7 @@ interface KVListResult ### `KVPutOptions` -`interface` +`interface` — Define options for storing a key-value pair with expiration and metadata settings ```ts interface KVPutOptions @@ -64,7 +64,7 @@ interface KVPutOptions ### `KVStore` -`interface` +`interface` — Define a key-value store interface for asynchronous data retrieval, storage, deletion, and listing ```ts interface KVStore diff --git a/docs/api/stream.md b/docs/api/stream.md index 0b82099..a21eedf 100644 --- a/docs/api/stream.md +++ b/docs/api/stream.md @@ -8,7 +8,7 @@ Source: `src/stream/index.ts` ### `asRecord` -`function` +`function` — Resolve an unknown value to a JsonRecord if it is a non-array object or return undefined ```ts (value: unknown) => JsonRecord | undefined @@ -16,7 +16,7 @@ Source: `src/stream/index.ts` ### `asString` -`function` +`function` — Resolve a non-empty string from a value or return undefined ```ts (value: unknown) => string | undefined @@ -32,7 +32,7 @@ Source: `src/stream/index.ts` ### `BufferedTurnEvent` -`interface` +`interface` — Represent a buffered turn event with a sequence number and serialized event data ```ts interface BufferedTurnEvent @@ -40,7 +40,7 @@ interface BufferedTurnEvent ### `BufferedTurnOptions` -`interface` +`interface` — Define options for buffering and flushing turn events with optional live client delivery and event coalescing ```ts interface BufferedTurnOptions @@ -56,7 +56,7 @@ interface BufferedTurnTap ### `buildUserTextParts` -`function` +`function` — Build an array of text parts with optional turn ID for user input ```ts (text: string, turnId: string | undefined) => JsonRecord[] @@ -96,7 +96,7 @@ interface BufferedTurnTap ### `createD1TurnEventStore` -`function` +`function` — Resolve a TurnEventStore that appends and reads turn events using a D1-like database interface ```ts (db: D1LikeForTurns) => TurnEventStore @@ -120,7 +120,7 @@ interface D1LikeForTurns ### `encodeEvent` -`function` +`function` — Encode a StreamEvent object into a Uint8Array using the provided TextEncoder ```ts (encoder: TextEncoder, event: StreamEvent) => Uint8Array @@ -128,7 +128,7 @@ interface D1LikeForTurns ### `finalizeAssistantParts` -`function` +`function` — Resolve and clean up assistant parts by terminalizing and collapsing redundant segments ```ts (partOrder: string[], partMap: Map, finalText: string) => JsonRecord[] @@ -144,7 +144,7 @@ interface D1LikeForTurns ### `getPartKey` -`function` +`function` — Resolve a unique key string for a part based on its type and identifying properties ```ts (part: JsonRecord) => string @@ -152,7 +152,7 @@ interface D1LikeForTurns ### `JsonRecord` -`type` +`type` — Represent a JSON-compatible object with string keys and values of any type ```ts type JsonRecord @@ -160,7 +160,7 @@ type JsonRecord ### `mergePersistedPart` -`function` +`function` — Merge incoming JSON with existing persisted data, applying delta for text types when provided ```ts (existing: JsonRecord | undefined, incoming: JsonRecord, delta?: string | undefined) => JsonRecord @@ -168,7 +168,7 @@ type JsonRecord ### `messageHasTurnId` -`function` +`function` — Resolve whether a message contains any part with the specified turn ID ```ts (message: PersistedChatMessageForTurn, turnId: string) => boolean @@ -176,7 +176,7 @@ type JsonRecord ### `MISSING_TOOL_TERMINAL_ERROR` -`const` +`const` — Resolve errors when a tool fails to report a terminal result before the assistant turn ends ```ts "Tool did not report a terminal result before the assistant turn completed." @@ -184,7 +184,7 @@ type JsonRecord ### `MISSING_TOOL_TERMINAL_REASON` -`const` +`const` — Provide the reason identifier for a missing tool in the terminal environment ```ts "missing-tool-terminal" @@ -192,7 +192,7 @@ type JsonRecord ### `normalizeClientTurnId` -`function` +`function` — Normalize and validate a client turn ID string ensuring it meets format and length requirements ```ts (value: unknown) => string | undefined @@ -200,7 +200,7 @@ type JsonRecord ### `normalizePersistedPart` -`function` +`function` — Normalize a persisted part object by standardizing its structure and fields ```ts (rawPart: JsonRecord) => JsonRecord | null @@ -208,7 +208,7 @@ type JsonRecord ### `normalizeTime` -`function` +`function` — Resolve time properties from various keys into a normalized record with numeric start and end fields ```ts (value: unknown) => JsonRecord | undefined @@ -216,7 +216,7 @@ type JsonRecord ### `normalizeToolEvent` -`function` +`function` — Normalize tool-related events into a standardized message.part.updated format ```ts (event: StreamEvent) => StreamEvent @@ -224,7 +224,7 @@ type JsonRecord ### `PersistedChatMessageForTurn` -`interface` +`interface` — Define the structure of a chat message stored for a specific conversation turn ```ts interface PersistedChatMessageForTurn @@ -240,7 +240,7 @@ interface PersistedChatMessageForTurn ### `PumpBufferedTurnOptions` -`interface` +`interface` — Define options to pump data from an asynchronous iterable source with buffered turn control ```ts interface PumpBufferedTurnOptions @@ -256,7 +256,7 @@ interface PumpBufferedTurnOptions ### `ReplayTurnEventsOptions` -`interface` +`interface` — Define options for replaying turn events with control over sequence, polling, and timeout ```ts interface ReplayTurnEventsOptions @@ -264,7 +264,7 @@ interface ReplayTurnEventsOptions ### `resolveChatTurn` -`function` +`function` — Resolve a chat turn by determining message reuse and constructing user message parts ```ts (input: { existingMessages: PersistedChatMessageForTurn[]; userContent: string; turnId?: string | undefined; }) => Reso… @@ -272,7 +272,7 @@ interface ReplayTurnEventsOptions ### `ResolvedChatTurn` -`interface` +`interface` — Represent a chat turn with resolved user message insertion and prior message context ```ts interface ResolvedChatTurn @@ -280,7 +280,7 @@ interface ResolvedChatTurn ### `resolveToolId` -`function` +`function` — Resolve a unique tool identifier from various possible properties or generate a fallback ID ```ts (part: JsonRecord) => string @@ -288,7 +288,7 @@ interface ResolvedChatTurn ### `resolveToolName` -`function` +`function` — Resolve the tool name from a JSON record using tool, name, or a default value ```ts (part: JsonRecord) => string @@ -296,7 +296,7 @@ interface ResolvedChatTurn ### `StreamEvent` -`interface` +`interface` — Define an event object carrying a type and optional JSON data payload ```ts interface StreamEvent @@ -320,7 +320,7 @@ interface StreamEvent ### `terminalizeDanglingToolParts` -`function` +`function` — Resolve dangling tool parts into terminal forms within the given JSON records array ```ts (parts: JsonRecord[]) => JsonRecord[] @@ -344,7 +344,7 @@ interface StreamEvent ### `TurnEventStore` -`interface` +`interface` — Manage and query turn events and their lifecycle statuses within a scoped event store ```ts interface TurnEventStore diff --git a/docs/api/studio-react.md b/docs/api/studio-react.md index c4c34c9..30cf833 100644 --- a/docs/api/studio-react.md +++ b/docs/api/studio-react.md @@ -208,7 +208,7 @@ interface StudioWorkspaceProps ### `TYPE_CONFIG` -`const` +`const` — Map type keys to their corresponding configuration objects including labels, icons, and colors ```ts Record @@ -216,7 +216,7 @@ Record ### `TypeConfig` -`interface` +`interface` — Define configuration options for a type including label, icon, and color properties ```ts interface TypeConfig @@ -224,7 +224,7 @@ interface TypeConfig ### `typeConfigFor` -`function` +`function` — Resolve the configuration object for a given type or return the default image configuration ```ts (type: string) => TypeConfig diff --git a/docs/api/studio.md b/docs/api/studio.md index d848b0c..a35ce21 100644 --- a/docs/api/studio.md +++ b/docs/api/studio.md @@ -8,7 +8,7 @@ Source: `src/studio/index.ts` ### `buildGenerationRequestBody` -`function` +`function` — Build the request body object for a generation operation from provided fields ```ts (fields: GenerationRequestFields) => Record @@ -16,7 +16,7 @@ Source: `src/studio/index.ts` ### `buildPublishPackage` -`function` +`function` — Build a PublishPackage object from caption, description, mentions, cadence, and destinations inputs ```ts ({ caption, postDescription, mentions, cadence, destinations, }: { caption: string; postDescription: string; mentions:… @@ -24,7 +24,7 @@ Source: `src/studio/index.ts` ### `CADENCES` -`const` +`const` — Provide an array of predefined cadence options for scheduling or approval processes ```ts string[] @@ -32,7 +32,7 @@ string[] ### `DESTINATIONS` -`const` +`const` — List available social media platforms with their publishing fields and provider identifiers ```ts PublishDestination[] @@ -40,7 +40,7 @@ PublishDestination[] ### `failedOptimisticGeneration` -`function` +`function` — Mark a generation as failed with updated status and error information ```ts (generation: Generation) => Generation @@ -48,7 +48,7 @@ PublishDestination[] ### `Generation` -`interface` +`interface` — Define the structure for a generation entity including its metadata and creation details ```ts interface Generation @@ -56,7 +56,7 @@ interface Generation ### `GENERATION_TYPES` -`const` +`const` — Provide an array of supported generation types for media and content processing ```ts readonly GenerationType[] @@ -64,7 +64,7 @@ readonly GenerationType[] ### `generationError` -`function` +`function` — Resolve and return the first user-safe error message from generation metadata or null if none exist ```ts (generation: Generation) => string | null @@ -72,7 +72,7 @@ readonly GenerationType[] ### `generationMergeKey` -`function` +`function` — Resolve a unique merge key from a generation using batch slot or client request ID ```ts (generation: Generation) => string | null @@ -80,7 +80,7 @@ readonly GenerationType[] ### `GenerationRequestFields` -`interface` +`interface` — Define fields required to configure and request various types of media generation ```ts interface GenerationRequestFields @@ -88,7 +88,7 @@ interface GenerationRequestFields ### `generationStatus` -`function` +`function` — Resolve the current status of a generation based on its metadata and result fields ```ts (generation: Generation) => GenerationStatus @@ -96,7 +96,7 @@ interface GenerationRequestFields ### `GenerationStatus` -`type` +`type` — Define possible states representing the progress of a generation process ```ts type GenerationStatus @@ -104,7 +104,7 @@ type GenerationStatus ### `GenerationType` -`type` +`type` — Define generation categories for media including image, video, speech, avatar, and transcription ```ts type GenerationType @@ -112,7 +112,7 @@ type GenerationType ### `generationVaultPath` -`function` +`function` — Resolve the vault path string from a Generation object or return null if unavailable ```ts (generation: Generation) => string | null @@ -120,7 +120,7 @@ type GenerationType ### `isDestinationConnected` -`function` +`function` — Determine if a destination has any active connections in the given list of studio integration connections ```ts (destination: PublishDestination, connections: StudioIntegrationConnection[]) => boolean @@ -128,7 +128,7 @@ type GenerationType ### `isGenerationType` -`function` +`function` — Resolve whether a string value matches a valid GenerationType ```ts (value: string) => value is GenerationType @@ -136,7 +136,7 @@ type GenerationType ### `isLocalGeneration` -`function` +`function` — Determine if a generation ID indicates a local generation ```ts (generation: Generation) => boolean @@ -144,7 +144,7 @@ type GenerationType ### `isPublishPackage` -`function` +`function` — Determine if a value conforms to the PublishPackage structure with optional metadata fields ```ts (value: unknown) => value is { caption?: string | undefined; description?: string | undefined; mentions?: string[] | un… @@ -152,7 +152,7 @@ type GenerationType ### `latestBatchOf` -`function` +`function` — Resolve and return the latest batch of generations grouped and sorted by client request ID and output index ```ts (generations: Generation[]) => Generation[] @@ -160,7 +160,7 @@ type GenerationType ### `MAX_IMAGE_COUNT` -`const` +`const` — Define the maximum number of images allowed for upload or display ```ts 4 @@ -168,7 +168,7 @@ type GenerationType ### `MediaModelCatalogResponse` -`interface` +`interface` — Represent media model catalog with default values, model options, and optional error message ```ts interface MediaModelCatalogResponse @@ -176,7 +176,7 @@ interface MediaModelCatalogResponse ### `MediaModelOption` -`interface` +`interface` — Describe media model option properties including id, name, type, status, and optional provider and reason ```ts interface MediaModelOption @@ -184,7 +184,7 @@ interface MediaModelOption ### `MediaModelStatus` -`type` +`type` — Define possible status values for a media model's availability and accessibility ```ts type MediaModelStatus @@ -192,7 +192,7 @@ type MediaModelStatus ### `mergeLiveGeneration` -`function` +`function` — Merge a new generation into the current list by replacing or prepending it based on matching keys ```ts (current: Generation[], generation: Generation) => Generation[] @@ -200,7 +200,7 @@ type MediaModelStatus ### `mergeLoaderAndLive` -`function` +`function` — Merge two Generation arrays prioritizing live entries and matching by merge keys or IDs ```ts (loader: Generation[], live: Generation[]) => Generation[] @@ -208,7 +208,7 @@ type MediaModelStatus ### `MIN_IMAGE_COUNT` -`const` +`const` — Define the minimum number of images required for processing or validation ```ts 1 @@ -216,7 +216,7 @@ type MediaModelStatus ### `modelMessage` -`function` +`function` — Resolve the appropriate status message for a media model based on loading state and availability ```ts (model: MediaModelOption | undefined, loading: boolean, count: number) => string | null @@ -224,7 +224,7 @@ type MediaModelStatus ### `normalizeImageCount` -`function` +`function` — Normalize a value to a finite integer within the allowed image count range ```ts (value: unknown) => number @@ -232,7 +232,7 @@ type MediaModelStatus ### `optimisticGeneration` -`function` +`function` — Generate content optimistically based on input parameters and optional model and output details ```ts ({ type, prompt, model, clientRequestId, outputIndex, outputCount, }: { type: GenerationType; prompt: string; model?: s… @@ -240,7 +240,7 @@ type MediaModelStatus ### `outputPathFor` -`function` +`function` — Resolve the output directory path based on the specified generation type ```ts (type: GenerationType) => string @@ -248,7 +248,7 @@ type MediaModelStatus ### `preferredModelId` -`function` +`function` — Resolve the preferred model ID for a given generation type from the media model catalog ```ts (type: GenerationType, catalog: MediaModelCatalogResponse | null) => string | undefined @@ -256,7 +256,7 @@ type MediaModelStatus ### `PublishDestination` -`interface` +`interface` — Define a destination for publishing content with identifiers, label, provider IDs, and fields ```ts interface PublishDestination @@ -264,7 +264,7 @@ interface PublishDestination ### `PublishPackage` -`interface` +`interface` — Define the structure for configuring package publishing details and evaluation criteria ```ts interface PublishPackage @@ -272,7 +272,7 @@ interface PublishPackage ### `relativeTime` -`function` +`function` — Resolve a human-readable relative time string from a given date or return an empty string if null ```ts (date: Date | null) => string @@ -280,7 +280,7 @@ interface PublishPackage ### `selectedModelsWithDefaults` -`function` +`function` — Resolve selected models by applying defaults for missing or unavailable entries in the catalog ```ts (current: Partial>, catalog: MediaModelCatalogResponse) => Partial string diff --git a/docs/api/tangle.md b/docs/api/tangle.md index 15ecd56..8464807 100644 --- a/docs/api/tangle.md +++ b/docs/api/tangle.md @@ -24,7 +24,7 @@ interface BrokerTokenMinter ### `BrokerTokenProvider` -`interface` +`interface` — Provide and refresh broker bearer tokens, allowing forced token invalidation ```ts interface BrokerTokenProvider @@ -32,7 +32,7 @@ interface BrokerTokenProvider ### `BrokerTokenProviderOptions` -`interface` +`interface` — Define options for configuring a broker token provider including client credentials and token management settings ```ts interface BrokerTokenProviderOptions @@ -48,7 +48,7 @@ interface BrokerTokenProviderOptions ### `ConsentUrlInput` -`interface` +`interface` — Define input parameters required to generate a consent URL for OAuth authorization ```ts interface ConsentUrlInput diff --git a/docs/api/teams-drizzle.md b/docs/api/teams-drizzle.md index 3ddd084..c648538 100644 --- a/docs/api/teams-drizzle.md +++ b/docs/api/teams-drizzle.md @@ -8,7 +8,7 @@ Source: `src/teams/drizzle.ts` ### `CreateAccessOptions` -`interface` +`interface` — Define options required to create access with database, tables, and workspace table references ```ts interface CreateAccessOptions @@ -16,7 +16,7 @@ interface CreateAccessOptions ### `createEnsurePersonalOrganization` -`function` +`function` — Ensure a user has a personal organization by creating or retrieving it as needed ```ts (opts: CreatePersonalOrganizationOptions) => (user: EnsurePersonalOrganizationUser) => Promise OrganizationAccessApi @@ -32,7 +32,7 @@ interface CreateAccessOptions ### `CreateOrganizationAccessOptions` -`interface` +`interface` — Define options required to create access for an organization including database and tables ```ts interface CreateOrganizationAccessOptions @@ -40,7 +40,7 @@ interface CreateOrganizationAccessOptions ### `CreatePersonalOrganizationOptions` -`interface` +`interface` — Define options required to create a personal organization including database and tables references ```ts interface CreatePersonalOrganizationOptions @@ -48,7 +48,7 @@ interface CreatePersonalOrganizationOptions ### `createTeamTables` -`function` +`function` — Build SQLite tables for organizations and related team structures using provided options ```ts (opts: CreateTeamTablesOptions) => { organizations: SQLiteTableWithColumns<{ name: "organization"; schema: undefined; c… @@ -56,7 +56,7 @@ interface CreatePersonalOrganizationOptions ### `CreateTeamTablesOptions` -`interface` +`interface` — Define options specifying user and workspace tables for creating team-related tables ```ts interface CreateTeamTablesOptions @@ -64,7 +64,7 @@ interface CreateTeamTablesOptions ### `createWorkspaceAccess` -`function` +`function` — Create workspace access API to manage user roles and permissions within a workspace ```ts (opts: CreateAccessOptions) => WorkspaceAccessApi @@ -72,7 +72,7 @@ interface CreateTeamTablesOptions ### `createWorkspaceInvitationTable` -`function` +`function` — Build a workspace invitation table with defined columns and foreign key constraints ```ts (opts: CreateWorkspaceInvitationTableOptions) => { workspaceInvitations: SQLiteTableWithColumns<{ name: "workspace_invi… @@ -80,7 +80,7 @@ interface CreateTeamTablesOptions ### `CreateWorkspaceInvitationTableOptions` -`interface` +`interface` — Define options for creating a workspace invitation table with user, workspace, and organization references ```ts interface CreateWorkspaceInvitationTableOptions @@ -88,7 +88,7 @@ interface CreateWorkspaceInvitationTableOptions ### `EnsurePersonalOrganizationUser` -`interface` +`interface` — Define the structure for a user within a personal organization context ```ts interface EnsurePersonalOrganizationUser @@ -96,7 +96,7 @@ interface EnsurePersonalOrganizationUser ### `OrganizationAccess` -`interface` +`interface` — Define access details linking an organization, its member, and the member's role ```ts interface OrganizationAccess @@ -104,7 +104,7 @@ interface OrganizationAccess ### `OrganizationAccessApi` -`interface` +`interface` — Define methods to retrieve and enforce user access levels within an organization ```ts interface OrganizationAccessApi @@ -112,7 +112,7 @@ interface OrganizationAccessApi ### `OrganizationMemberRow` -`type` +`type` — Resolve the structure of an organization member row from the team tables selection ```ts type OrganizationMemberRow @@ -120,7 +120,7 @@ type OrganizationMemberRow ### `OrganizationRow` -`type` +`type` — Resolve the structure of an organization row from the organizations table in TeamTables ```ts type OrganizationRow @@ -128,7 +128,7 @@ type OrganizationRow ### `PersonalOrganizationResult` -`interface` +`interface` — Describe a personal organization result including organization, member, and role details ```ts interface PersonalOrganizationResult @@ -152,7 +152,7 @@ type TeamParentTable ### `TeamTables` -`type` +`type` — Resolve team tables by deriving the return type of createTeamTables ```ts type TeamTables @@ -160,7 +160,7 @@ type TeamTables ### `UserWorkspaceSummary` -`interface` +`interface` — Describe a user's workspace details including organization and role information ```ts interface UserWorkspaceSummary @@ -168,7 +168,7 @@ interface UserWorkspaceSummary ### `WorkspaceAccess` -`interface` +`interface` — Define access details including workspace data, organization info, member info, and role within workspace ```ts interface WorkspaceAccess @@ -176,7 +176,7 @@ interface WorkspaceAccess ### `WorkspaceAccessApi` -`interface` +`interface` — Define methods to retrieve and enforce user access permissions within workspaces ```ts interface WorkspaceAccessApi @@ -192,7 +192,7 @@ interface WorkspaceAccessTable ### `WorkspaceInvitationRow` -`type` +`type` — Resolve the structure of a workspace invitation row from the workspaceInvitations table ```ts type WorkspaceInvitationRow @@ -200,7 +200,7 @@ type WorkspaceInvitationRow ### `WorkspaceInvitationTables` -`type` +`type` — Resolve the structure of workspace invitation tables from the creation function ```ts type WorkspaceInvitationTables @@ -208,7 +208,7 @@ type WorkspaceInvitationTables ### `WorkspaceMemberRow` -`type` +`type` — Resolve a workspace member row with selected fields from the workspaceMembers table ```ts type WorkspaceMemberRow diff --git a/docs/api/teams-invitations-api.md b/docs/api/teams-invitations-api.md index 2856ee5..f5ea7ef 100644 --- a/docs/api/teams-invitations-api.md +++ b/docs/api/teams-invitations-api.md @@ -24,7 +24,7 @@ interface EnforceSeatSeam ### `InvitationOutcome` -`type` +`type` — Resolve the result of an invitation as success with a value or failure with status and error details ```ts type InvitationOutcome @@ -32,7 +32,7 @@ type InvitationOutcome ### `InvitationPreview` -`interface` +`interface` — Describe the structure of an invitation preview with workspace, email, permissions, status, and expiration details ```ts interface InvitationPreview @@ -40,7 +40,7 @@ interface InvitationPreview ### `InvitationsApiOptions` -`interface` +`interface` — Define configuration options required to manage workspace invitations and related data sources ```ts interface InvitationsApiOptions @@ -88,7 +88,7 @@ interface SendInvitationEmailInput ### `SendInvitationEmailResult` -`type` +`type` — Represent the outcome of sending an invitation email with success status and optional error message ```ts type SendInvitationEmailResult @@ -96,7 +96,7 @@ type SendInvitationEmailResult ### `SendInvitationEmailSeam` -`interface` +`interface` — Resolve sending an invitation email and return the result asynchronously ```ts interface SendInvitationEmailSeam @@ -104,7 +104,7 @@ interface SendInvitationEmailSeam ### `WorkspaceInvitationView` -`interface` +`interface` — Represent a workspace invitation with details about inviter, permissions, status, and timestamps ```ts interface WorkspaceInvitationView diff --git a/docs/api/teams-members-api.md b/docs/api/teams-members-api.md index f906177..bb132fa 100644 --- a/docs/api/teams-members-api.md +++ b/docs/api/teams-members-api.md @@ -24,7 +24,7 @@ interface EnforceSeatSeam ### `MemberListEntry` -`interface` +`interface` — Define the structure of a workspace member entry with identification, role, and status details ```ts interface MemberListEntry @@ -40,7 +40,7 @@ interface MembersApiActor ### `MembersApiOptions` -`interface` +`interface` — Define configuration options for managing team members and workspace access APIs ```ts interface MembersApiOptions diff --git a/docs/api/teams-react-lazy.md b/docs/api/teams-react-lazy.md index e184b1b..51ec9a2 100644 --- a/docs/api/teams-react-lazy.md +++ b/docs/api/teams-react-lazy.md @@ -8,7 +8,7 @@ Source: `src/teams-react/lazy.tsx` ### `InvitationsPanelLazy` -`function` +`function` — Load InvitationsPanel component lazily to optimize initial rendering performance ```ts LazyExoticComponent<({ invitations, currentRole, onInvite, onResend, onRevoke, onCopy, onNotice, }: InvitationsPanelPro… @@ -16,7 +16,7 @@ LazyExoticComponent<({ invitations, currentRole, onInvite, onResend, onRevoke, o ### `InvitationsPanelProps` -`interface` +`interface` — Define properties and callbacks for managing workspace invitations and user roles ```ts interface InvitationsPanelProps @@ -24,7 +24,7 @@ interface InvitationsPanelProps ### `InviteAcceptPageLazy` -`function` +`function` — Load InviteAcceptPage component lazily for optimized code splitting and performance ```ts LazyExoticComponent<({ details, onAccept, onNavigate, onResendVerification }: InviteAcceptPageProps) => Element> @@ -32,7 +32,7 @@ LazyExoticComponent<({ details, onAccept, onNavigate, onResendVerification }: In ### `InviteAcceptPageProps` -`interface` +`interface` — Define properties and callbacks for handling invite acceptance and navigation actions on the invite page ```ts interface InviteAcceptPageProps @@ -40,7 +40,7 @@ interface InviteAcceptPageProps ### `MembersPanelLazy` -`function` +`function` — Load MembersPanel component lazily to optimize initial rendering performance ```ts LazyExoticComponent<({ members, currentRole, onInvite, onChangeRole, onRemove, onNotice, showInviteForm, }: MembersPane… @@ -48,7 +48,7 @@ LazyExoticComponent<({ members, currentRole, onInvite, onChangeRole, onRemove, o ### `MembersPanelProps` -`interface` +`interface` — Define properties and callbacks for managing members and their roles in a workspace panel ```ts interface MembersPanelProps diff --git a/docs/api/teams-react.md b/docs/api/teams-react.md index 7f3bc29..30a9309 100644 --- a/docs/api/teams-react.md +++ b/docs/api/teams-react.md @@ -16,7 +16,7 @@ Source: `src/teams-react/index.ts` ### `InvitationsPanelProps` -`interface` +`interface` — Define properties and callbacks for managing workspace invitations and user roles ```ts interface InvitationsPanelProps @@ -32,7 +32,7 @@ interface InvitationView ### `InviteAcceptDetails` -`interface` +`interface` — Describe details of an accepted invite including status, workspace, inviter, role, emails, and expiration ```ts interface InviteAcceptDetails @@ -48,7 +48,7 @@ interface InviteAcceptDetails ### `InviteAcceptPageProps` -`interface` +`interface` — Define properties and callbacks for handling invite acceptance and navigation actions on the invite page ```ts interface InviteAcceptPageProps @@ -56,7 +56,7 @@ interface InviteAcceptPageProps ### `InviteAcceptStatus` -`type` +`type` — Define possible statuses for the acceptance state of an invitation ```ts type InviteAcceptStatus @@ -72,7 +72,7 @@ type InviteAcceptStatus ### `MembersPanelProps` -`interface` +`interface` — Define properties and callbacks for managing members and their roles in a workspace panel ```ts interface MembersPanelProps diff --git a/docs/api/teams-resend.md b/docs/api/teams-resend.md index a0353b8..454588d 100644 --- a/docs/api/teams-resend.md +++ b/docs/api/teams-resend.md @@ -16,7 +16,7 @@ Source: `src/teams/resend.ts` ### `ResendInvitationSenderOptions` -`interface` +`interface` — Define options for sending a resend invitation including sender address and optional API key ```ts interface ResendInvitationSenderOptions diff --git a/docs/api/teams.md b/docs/api/teams.md index d5913f3..2617250 100644 --- a/docs/api/teams.md +++ b/docs/api/teams.md @@ -8,7 +8,7 @@ Source: `src/teams/index.ts` ### `ASSIGNABLE_WORKSPACE_ROLES` -`const` +`const` — Define the list of roles that can be assigned within a workspace ```ts readonly ["viewer", "editor", "admin"] @@ -16,7 +16,7 @@ readonly ["viewer", "editor", "admin"] ### `AssignableWorkspaceRole` -`type` +`type` — Resolve the set of roles that can be assigned within a workspace ```ts type AssignableWorkspaceRole @@ -48,7 +48,7 @@ type AssignableWorkspaceRole ### `getInvitationExpiresAt` -`function` +`function` — Calculate the expiration date of an invitation based on the given or current date ```ts (now?: Date) => Date @@ -72,7 +72,7 @@ type AssignableWorkspaceRole ### `INVITATION_EXPIRY_DAYS` -`const` +`const` — Define the number of days before an invitation expires ```ts 7 @@ -80,7 +80,7 @@ type AssignableWorkspaceRole ### `InvitationEmailBrand` -`interface` +`interface` — Define the structure for an invitation email brand including the RFC-5322 From header ```ts interface InvitationEmailBrand @@ -88,7 +88,7 @@ interface InvitationEmailBrand ### `InvitationEmailStatus` -`type` +`type` — Define possible statuses for the sending state of an invitation email ```ts type InvitationEmailStatus @@ -104,7 +104,7 @@ type InvitationPermission ### `InvitationStatus` -`type` +`type` — Define possible states for an invitation's lifecycle including pending, accepted, expired, and revoked ```ts type InvitationStatus @@ -112,7 +112,7 @@ type InvitationStatus ### `InviteRejectionReason` -`type` +`type` — Define possible reasons for rejecting an invite including acceptance, expiration, or email mismatch ```ts type InviteRejectionReason @@ -128,7 +128,7 @@ interface InviteTokenState ### `inviteUrlForToken` -`function` +`function` — Generate an invite URL by combining the origin with an encoded token ```ts (origin: string, token: string) => string @@ -136,7 +136,7 @@ interface InviteTokenState ### `InviteValidationResult` -`interface` +`interface` — Represent the outcome of validating an invite with success status and optional rejection reason ```ts interface InviteValidationResult @@ -144,7 +144,7 @@ interface InviteValidationResult ### `isAssignableWorkspaceRole` -`function` +`function` — Determine if a value is a valid assignable workspace role among viewer, editor, or admin ```ts (value: unknown) => value is "viewer" | "editor" | "admin" @@ -160,7 +160,7 @@ interface InviteValidationResult ### `normalizeInvitationEmail` -`function` +`function` — Normalize an invitation email by trimming whitespace and converting to lowercase ```ts (email: string) => string @@ -168,7 +168,7 @@ interface InviteValidationResult ### `ORGANIZATION_ROLE_RANK` -`const` +`const` — Map organization roles to their hierarchical rank for permission and access control purposes ```ts Record<"admin" | "owner" | "member" | "billing", number> @@ -176,7 +176,7 @@ Record<"admin" | "owner" | "member" | "billing", number> ### `ORGANIZATION_ROLES` -`const` +`const` — Define the set of fixed roles available within an organization ```ts readonly ["owner", "admin", "member", "billing"] @@ -184,7 +184,7 @@ readonly ["owner", "admin", "member", "billing"] ### `OrganizationRole` -`type` +`type` — Resolve a role string from the predefined list of organization roles ```ts type OrganizationRole @@ -200,7 +200,7 @@ type OrganizationRole ### `parseInvitationPermission` -`function` +`function` — Resolve invitation permission from a string or return null if invalid ```ts (value: string | undefined) => "viewer" | "editor" | "admin" | null @@ -208,7 +208,7 @@ type OrganizationRole ### `RenderedInvitationEmail` -`interface` +`interface` — Define the structure of a fully rendered invitation email with sender, subject, and content fields ```ts interface RenderedInvitationEmail @@ -224,7 +224,7 @@ interface RenderedInvitationEmail ### `RenderInvitationEmailInput` -`interface` +`interface` — Define input data required to render an invitation email template ```ts interface RenderInvitationEmailInput @@ -240,7 +240,7 @@ interface RenderInvitationEmailInput ### `SandboxWorkspaceRole` -`type` +`type` — Define user roles available within a sandbox workspace environment ```ts type SandboxWorkspaceRole @@ -256,7 +256,7 @@ type SandboxWorkspaceRole ### `WORKSPACE_ROLE_RANK` -`const` +`const` — Map workspace roles to their corresponding hierarchical rank values ```ts Record<"viewer" | "editor" | "admin" | "owner", number> @@ -272,7 +272,7 @@ readonly ["viewer", "editor", "admin", "owner"] ### `WorkspaceCollaborationAccess` -`type` +`type` — Define access levels for workspace collaboration as either read or write ```ts type WorkspaceCollaborationAccess @@ -280,7 +280,7 @@ type WorkspaceCollaborationAccess ### `WorkspaceRole` -`type` +`type` — Resolve the union type of all possible workspace role string literals from WORKSPACE_ROLES array ```ts type WorkspaceRole @@ -288,7 +288,7 @@ type WorkspaceRole ### `workspaceRoleToCollaborationAccess` -`function` +`function` — Map a workspace role to the corresponding collaboration access level ```ts (role: "viewer" | "editor" | "admin" | "owner") => WorkspaceCollaborationAccess @@ -296,7 +296,7 @@ type WorkspaceRole ### `workspaceRoleToSandboxRole` -`function` +`function` — Map a workspace role to its corresponding sandbox workspace role ```ts (role: "viewer" | "editor" | "admin" | "owner") => SandboxWorkspaceRole diff --git a/docs/api/theme-contract.md b/docs/api/theme-contract.md index 4d62eeb..d40014a 100644 --- a/docs/api/theme-contract.md +++ b/docs/api/theme-contract.md @@ -16,7 +16,7 @@ Source: `src/theme-contract/index.ts` ### `ThemeContractMiss` -`interface` +`interface` — Describe a missing theme contract variable and where it was referenced ```ts interface ThemeContractMiss @@ -24,7 +24,7 @@ interface ThemeContractMiss ### `ThemeContractOptions` -`interface` +`interface` — Define options for scanning source directories and CSS token files in a theme contract ```ts interface ThemeContractOptions @@ -32,7 +32,7 @@ interface ThemeContractOptions ### `ThemeContractResult` -`interface` +`interface` — Describe the result of validating a theme contract including success status and missing items ```ts interface ThemeContractResult diff --git a/docs/api/theme-tailwind-preset.md b/docs/api/theme-tailwind-preset.md index 3f610b4..08eeb1f 100644 --- a/docs/api/theme-tailwind-preset.md +++ b/docs/api/theme-tailwind-preset.md @@ -8,7 +8,7 @@ Source: `src/theme/tailwind-preset.ts` ### `default` -`const` +`const` — Define a preset configuration for dark mode and extended theme colors with foreground variants ```ts { darkMode: [string, string]; theme: { extend: { colors: { background: string; foreground: string; border: string; inpu… diff --git a/docs/api/theme.md b/docs/api/theme.md index b3e39ec..ebc037d 100644 --- a/docs/api/theme.md +++ b/docs/api/theme.md @@ -24,7 +24,7 @@ interface CanvasRenderPalette ### `darkTheme` -`const` +`const` — Define a dark color scheme for the Agent app interface with specific background and foreground hues ```ts AgentAppTheme @@ -32,7 +32,7 @@ AgentAppTheme ### `lightTheme` -`const` +`const` — Define a light color theme with specific background, foreground, and accent color values ```ts AgentAppTheme diff --git a/docs/api/tools.md b/docs/api/tools.md index 09fc365..dcdc7d9 100644 --- a/docs/api/tools.md +++ b/docs/api/tools.md @@ -8,7 +8,7 @@ Source: `src/tools/index.ts` ### `AddCitationArgs` -`interface` +`interface` — Define arguments required to add a citation including path, quote, and optional label ```ts interface AddCitationArgs @@ -16,7 +16,7 @@ interface AddCitationArgs ### `AddCitationResult` -`interface` +`interface` — Represent the result of adding a citation including its identifier and location path ```ts interface AddCitationResult @@ -64,7 +64,7 @@ interface AppToolMcpServer ### `AppToolName` -`type` +`type` — Resolve a valid application tool name from the predefined list of tool names ```ts type AppToolName @@ -104,7 +104,7 @@ interface AppToolTaxonomy ### `AuthenticateOptions` -`interface` +`interface` — Define options to verify bearer tokens and customize authentication header names ```ts interface AuthenticateOptions @@ -152,7 +152,7 @@ interface BuildAppToolsOptions ### `BuildHttpMcpServerOptions` -`interface` +`interface` — Define configuration options for building an HTTP MCP server including path, baseUrl, token, context, and description ```ts interface BuildHttpMcpServerOptions @@ -160,7 +160,7 @@ interface BuildHttpMcpServerOptions ### `BuildMcpServerOptions` -`interface` +`interface` — Define configuration options required to build an MCP server including tool, baseUrl, token, and context ```ts interface BuildMcpServerOptions @@ -176,7 +176,7 @@ interface BuildMcpServerOptions ### `CapabilityTokenOptions` -`interface` +`interface` — Define options for creating and verifying capability tokens including secret and prefix ```ts interface CapabilityTokenOptions @@ -216,7 +216,7 @@ interface CapabilityTokenOptions ### `CreateMcpToolHandlerOptions` -`interface` +`interface` — Define options for creating a handler that manages MCP tools with environment support ```ts interface CreateMcpToolHandlerOptions @@ -240,7 +240,7 @@ Record<"submit_proposal" | "schedule_followup" | "render_ui" | "add_citation", s ### `DEFAULT_HEADER_NAMES` -`const` +`const` — Provide default HTTP header names for user, workspace, and thread identification ```ts ToolHeaderNames @@ -264,7 +264,7 @@ ToolHeaderNames ### `DispatchOptions` -`interface` +`interface` — Define options for dispatching tools including handlers, taxonomy, custom tools, and approval policies ```ts interface DispatchOptions @@ -272,7 +272,7 @@ interface DispatchOptions ### `ExpiringCapabilityTokenOptions` -`interface` +`interface` — Define options for capability tokens that expire after a specified lifetime in milliseconds ```ts interface ExpiringCapabilityTokenOptions @@ -296,7 +296,7 @@ interface ExpiringCapabilityTokenOptions ### `HandleToolRequestOptions` -`interface` +`interface` — Define options for handling tool requests including tool identification and token verification ```ts interface HandleToolRequestOptions @@ -304,7 +304,7 @@ interface HandleToolRequestOptions ### `isAppToolName` -`function` +`function` — Determine if a string matches a valid application tool name ```ts (name: string) => name is "submit_proposal" | "schedule_followup" | "render_ui" | "add_citation" @@ -320,7 +320,7 @@ readonly ["2025-06-18", "2025-03-26", "2024-11-05"] ### `McpProtocolVersion` -`type` +`type` — Resolve a valid protocol version from the predefined MCP_PROTOCOL_VERSIONS array ```ts type McpProtocolVersion @@ -328,7 +328,7 @@ type McpProtocolVersion ### `McpServerInfo` -`interface` +`interface` — Describe the structure of server information including name and version ```ts interface McpServerInfo @@ -368,7 +368,7 @@ interface OpenAIFunctionTool ### `RenderUiArgs` -`interface` +`interface` — Define arguments required to render a UI including title and schema ```ts interface RenderUiArgs @@ -376,7 +376,7 @@ interface RenderUiArgs ### `RenderUiResult` -`interface` +`interface` — Describe the result of rendering UI including the artifact path and exact persisted content ```ts interface RenderUiResult @@ -384,7 +384,7 @@ interface RenderUiResult ### `ResolvedToolCapabilities` -`interface` +`interface` — Describe resolved capabilities including proposal types and product tool groups to expose ```ts interface ResolvedToolCapabilities @@ -400,7 +400,7 @@ interface ResolvedToolCapabilities ### `ResolveToolCapabilitiesOptions` -`interface` +`interface` — Resolve options for determining tool capabilities based on taxonomy, capabilities, and enabled IDs ```ts interface ResolveToolCapabilitiesOptions @@ -416,7 +416,7 @@ interface ResolveToolCapabilitiesOptions ### `RuntimeExecutorOptions` -`interface` +`interface` — Define options for executing runtime tasks with a trusted per-turn context ```ts interface RuntimeExecutorOptions @@ -424,7 +424,7 @@ interface RuntimeExecutorOptions ### `ScheduleFollowupArgs` -`interface` +`interface` — Define arguments required to schedule a follow-up with optional priority ```ts interface ScheduleFollowupArgs @@ -432,7 +432,7 @@ interface ScheduleFollowupArgs ### `ScheduleFollowupResult` -`interface` +`interface` — Define the result structure for scheduling a follow-up with unique identification and due date ```ts interface ScheduleFollowupResult @@ -448,7 +448,7 @@ interface ScopedMcpServerEntryOptions ### `SubmitProposalArgs` -`interface` +`interface` — Define the arguments required to submit a proposal including type, title, description, and approval status ```ts interface SubmitProposalArgs @@ -456,7 +456,7 @@ interface SubmitProposalArgs ### `SubmitProposalResult` -`interface` +`interface` — Describe the result of submitting a proposal including deduplication and execution status ```ts interface SubmitProposalResult @@ -464,7 +464,7 @@ interface SubmitProposalResult ### `ToolAuthResult` -`type` +`type` — Represent the result of tool authentication with success context or failure response ```ts type ToolAuthResult diff --git a/docs/api/trace.md b/docs/api/trace.md index 2b0b9bd..3517026 100644 --- a/docs/api/trace.md +++ b/docs/api/trace.md @@ -48,7 +48,7 @@ Source: `src/trace/index.ts` ### `DistributionSummary` -`interface` +`interface` — Summarize key statistics of a numerical distribution including count, min, percentiles, and max ```ts interface DistributionSummary @@ -64,7 +64,7 @@ interface FlowSpan ### `FlowTrace` -`interface` +`interface` — Describe the structure of a flow trace including spans, timing, tokens, cost, and tool calls ```ts interface FlowTrace @@ -88,7 +88,7 @@ interface LoopTraceEventLike ### `MissionFlowStep` -`interface` +`interface` — Define a step in a mission flow with id, intent, optional status, start time, and duration ```ts interface MissionFlowStep @@ -128,7 +128,7 @@ interface MissionTraceContext ### `StepSpanContext` -`interface` +`interface` — Define context information for a step span including trace, span, and parent span identifiers ```ts interface StepSpanContext @@ -136,7 +136,7 @@ interface StepSpanContext ### `summarize` -`function` +`function` — Summarize numeric values into a distribution summary including count, min, median, 90th percentile, and max ```ts (values: number[]) => DistributionSummary @@ -144,7 +144,7 @@ interface StepSpanContext ### `TimedEvent` -`interface` +`interface` — Represent a timed event with a timestamp and associated event data ```ts interface TimedEvent diff --git a/docs/api/turn-stream.md b/docs/api/turn-stream.md index 452e398..9d5ec7b 100644 --- a/docs/api/turn-stream.md +++ b/docs/api/turn-stream.md @@ -8,7 +8,7 @@ Source: `src/turn-stream/index.ts` ### `acquireDurableTurnLock` -`function` +`function` — Acquire a durable turn lock in the specified namespace with given input parameters ```ts (namespace: TurnStreamNamespaceLike, input: AcquireDurableTurnLockInput) => Promise @@ -16,7 +16,7 @@ Source: `src/turn-stream/index.ts` ### `AcquireDurableTurnLockInput` -`interface` +`interface` — Define input parameters required to acquire a durable turn lock in a workspace thread context ```ts interface AcquireDurableTurnLockInput @@ -88,7 +88,7 @@ number ### `CreateDurableTurnLockOptions` -`interface` +`interface` — Define options for creating a durable turn lock with customizable scope and identification methods ```ts interface CreateDurableTurnLockOptions @@ -104,7 +104,7 @@ interface CreateDurableTurnLockOptions ### `createSegmentStore` -`function` +`function` — Create a SegmentStore with initialized segments and no active execution ID ```ts () => SegmentStore @@ -112,7 +112,7 @@ interface CreateDurableTurnLockOptions ### `createTurnLock` -`function` +`function` — Create a durable turn lock object with timing and scope based on input parameters ```ts (input: TurnLockAcquireInput, now: number, ttlMs?: number) => DurableTurnLock @@ -128,7 +128,7 @@ interface CreateDurableTurnLockOptions ### `CreateTurnStreamUpgradeHandlerOptions` -`interface` +`interface` — Define options for creating a TURN stream upgrade handler including namespace, path, and authorization logic ```ts interface CreateTurnStreamUpgradeHandlerOptions @@ -176,7 +176,7 @@ interface DurableTurnLock ### `MemoryTurnStreamChannel` -`interface` +`interface` — Define an in-memory channel for streaming turn-based data with viewer socket connection support ```ts interface MemoryTurnStreamChannel @@ -184,7 +184,7 @@ interface MemoryTurnStreamChannel ### `MemoryTurnStreamHarness` -`interface` +`interface` — Provide an interface to manage channels and namespaces for memory-based turn stream testing ```ts interface MemoryTurnStreamHarness @@ -216,7 +216,7 @@ interface MemoryTurnStreamSocket ### `ReconcileStaleDurableTurnLockOptions` -`interface` +`interface` — Define options to reconcile stale durable turn locks with context, namespace, workspace, and active lock details ```ts interface ReconcileStaleDurableTurnLockOptions @@ -224,7 +224,7 @@ interface ReconcileStaleDurableTurnLockOptions ### `releaseDurableTurnLock` -`function` +`function` — Release a durable turn lock and indicate if the release was successful or deferred ```ts (namespace: TurnStreamNamespaceLike, input: TurnLockReleaseInput) => Promise<{ released: boolean; deferred?: boolean |… @@ -240,7 +240,7 @@ interface ReconcileStaleDurableTurnLockOptions ### `ReleaseInterruptedDurableTurnLockInput` -`interface` +`interface` — Define input parameters to release an interrupted durable turn lock in a workspace or thread ```ts interface ReleaseInterruptedDurableTurnLockInput @@ -256,7 +256,7 @@ interface ReleaseInterruptedDurableTurnLockInput ### `scopeIndexChannelKey` -`function` +`function` — Generate a unique channel key string based on the provided scope identifier ```ts (scopeId: string) => string @@ -264,7 +264,7 @@ interface ReleaseInterruptedDurableTurnLockInput ### `SegmentStore` -`interface` +`interface` — Define a store managing segments and tracking the active execution identifier ```ts interface SegmentStore @@ -272,7 +272,7 @@ interface SegmentStore ### `threadChannelKey` -`function` +`function` — Generate a unique string key combining workspace and thread identifiers ```ts (workspaceId: string, threadId: string) => string @@ -288,7 +288,7 @@ number ### `TURN_STREAM_PATHS` -`const` +`const` — Provide constant paths for managing chat turn streams and locks ```ts { readonly broadcast: "/broadcast"; readonly lockAcquire: "/chat-turn-lock/acquire"; readonly lockRelease: "/chat-turn-… @@ -312,7 +312,7 @@ number ### `TurnLockAcquireInput` -`interface` +`interface` — Define input parameters required to acquire a turn-based lock in a workspace thread ```ts interface TurnLockAcquireInput @@ -320,7 +320,7 @@ interface TurnLockAcquireInput ### `TurnLockAcquireResult` -`type` +`type` — Resolve the result of attempting to acquire a turn lock indicating success or active lock status ```ts type TurnLockAcquireResult @@ -352,7 +352,7 @@ interface TurnLockInterruptedReleaseInput ### `TurnLockReleaseInput` -`interface` +`interface` — Define input parameters required to release a turn lock in a specific workspace thread ```ts interface TurnLockReleaseInput @@ -360,7 +360,7 @@ interface TurnLockReleaseInput ### `TurnLockScope` -`type` +`type` — Define the scope level for acquiring a turn lock within thread or workspace contexts ```ts type TurnLockScope @@ -384,7 +384,7 @@ type TurnLockSeamResult ### `TurnSegment` -`interface` +`interface` — Represent a segment of a turn containing events, sequence limit, and terminal status ```ts interface TurnSegment @@ -392,7 +392,7 @@ interface TurnSegment ### `turnStorageChannelKey` -`function` +`function` — Generate a storage channel key string for a given turn identifier ```ts (turnId: string) => string @@ -400,7 +400,7 @@ interface TurnSegment ### `TurnStreamDO` -`class` +`class` — Manage per-turn segments and track active threads with durable event storage ```ts class TurnStreamDO @@ -408,7 +408,7 @@ class TurnStreamDO ### `TurnStreamDOOptions` -`interface` +`interface` — Define options to override default TTL and event limits for TURN stream DO operations ```ts interface TurnStreamDOOptions @@ -456,7 +456,7 @@ interface TurnStreamStorage ### `TurnStreamStubLike` -`interface` +`interface` — Resolve a stub interface for handling fetch requests with optional initialization parameters ```ts interface TurnStreamStubLike @@ -464,7 +464,7 @@ interface TurnStreamStubLike ### `TurnStreamUpgradeAuthorization` -`type` +`type` — Represent success or failure of a TURN stream upgrade authorization with optional response data ```ts type TurnStreamUpgradeAuthorization @@ -472,7 +472,7 @@ type TurnStreamUpgradeAuthorization ### `workspaceChannelKey` -`function` +`function` — Generate a unique channel key based on the given workspace identifier ```ts (workspaceId: string) => string diff --git a/docs/api/vault-lazy.md b/docs/api/vault-lazy.md index ec336e9..e1799af 100644 --- a/docs/api/vault-lazy.md +++ b/docs/api/vault-lazy.md @@ -8,7 +8,7 @@ Source: `src/vault/lazy.tsx` ### `VaultPaneLazy` -`function` +`function` — Resolve VaultPane component lazily to optimize loading and improve performance ```ts LazyExoticComponent<(props: VaultPaneProps) => Element> @@ -16,7 +16,7 @@ LazyExoticComponent<(props: VaultPaneProps) => Element> ### `VaultPaneProps` -`interface` +`interface` — Define the properties and render methods for the vault pane UI components ```ts interface VaultPaneProps diff --git a/docs/api/vault.md b/docs/api/vault.md index 9d72d0a..402e25c 100644 --- a/docs/api/vault.md +++ b/docs/api/vault.md @@ -112,7 +112,7 @@ type VaultOperationPhase ### `VaultPaneProps` -`interface` +`interface` — Define the properties and render methods for the vault pane UI components ```ts interface VaultPaneProps diff --git a/docs/api/web-react-terminal.md b/docs/api/web-react-terminal.md index 71f478c..ae73d5e 100644 --- a/docs/api/web-react-terminal.md +++ b/docs/api/web-react-terminal.md @@ -8,7 +8,7 @@ Source: `src/web-react/terminal.ts` ### `SandboxTerminalConnection` -`interface` +`interface` — Define the connection details and status for a sandbox terminal session ```ts interface SandboxTerminalConnection @@ -16,7 +16,7 @@ interface SandboxTerminalConnection ### `SandboxTerminalConnectionResponse` -`interface` +`interface` — Define the response structure for a sandbox terminal connection including URLs, token, status, and errors ```ts interface SandboxTerminalConnectionResponse @@ -48,7 +48,7 @@ type TerminalStatusTone ### `useSandboxTerminalConnection` -`function` +`function` — Manage and maintain a sandbox terminal connection with automatic polling and token refresh handling ```ts (opts: UseSandboxTerminalConnectionOptions) => UseSandboxTerminalConnectionResult @@ -56,7 +56,7 @@ type TerminalStatusTone ### `UseSandboxTerminalConnectionOptions` -`interface` +`interface` — Define options for configuring a sandbox terminal connection including workspace ID and connection parameters ```ts interface UseSandboxTerminalConnectionOptions @@ -64,7 +64,7 @@ interface UseSandboxTerminalConnectionOptions ### `UseSandboxTerminalConnectionResult` -`interface` +`interface` — Resolve sandbox terminal connection status and provide a method to initiate the connection ```ts interface UseSandboxTerminalConnectionResult diff --git a/docs/api/web-react.md b/docs/api/web-react.md index 508769c..1c2c550 100644 --- a/docs/api/web-react.md +++ b/docs/api/web-react.md @@ -168,7 +168,7 @@ type AttachmentFileResult ### `CatalogModel` -`interface` +`interface` — Define the structure and capabilities of a catalog item with optional pricing and feature flags ```ts interface CatalogModel @@ -232,7 +232,7 @@ interface ChatEmptyDoor ### `ChatEmptyStateProps` -`interface` +`interface` — Define properties for rendering the chat empty state with customizable text and starting doors ```ts interface ChatEmptyStateProps @@ -248,7 +248,7 @@ interface ChatInteraction ### `ChatInteractionField` -`type` +`type` — Resolve a chat interaction field excluding select types or including chat select fields ```ts type ChatInteractionField @@ -256,7 +256,7 @@ type ChatInteractionField ### `ChatInteractionRestoreMode` -`type` +`type` — Define modes for restoring chat interactions with legacy or durable strategies ```ts type ChatInteractionRestoreMode @@ -264,7 +264,7 @@ type ChatInteractionRestoreMode ### `ChatInteractionStatus` -`type` +`type` — Define possible statuses representing the state of a chat interaction ```ts type ChatInteractionStatus @@ -288,7 +288,7 @@ interface ChatMentionPart ### `ChatMessageMetrics` -`interface` +`interface` — Describe metrics related to a chat message including model, token counts, and duration ```ts interface ChatMessageMetrics @@ -312,7 +312,7 @@ type ChatMessageSegment ### `ChatMessagesProps` -`interface` +`interface` — Define properties for rendering chat messages with optional models, markdown, extras, and durable cards ```ts interface ChatMessagesProps @@ -320,7 +320,7 @@ interface ChatMessagesProps ### `ChatSelectField` -`type` +`type` — Extract select-type interaction fields and optionally allow custom values ```ts type ChatSelectField @@ -328,7 +328,7 @@ type ChatSelectField ### `ChatStreamCallbacks` -`interface` +`interface` — Define callbacks to handle events and data during a chat streaming session ```ts interface ChatStreamCallbacks @@ -336,7 +336,7 @@ interface ChatStreamCallbacks ### `ChatStreamToolCall` -`interface` +`interface` — Define the structure for a chat tool call including optional ID, name, and arguments object ```ts interface ChatStreamToolCall @@ -344,7 +344,7 @@ interface ChatStreamToolCall ### `ChatStreamToolResult` -`interface` +`interface` — Describe the result of a chat stream tool including its outcome and optional metadata fields ```ts interface ChatStreamToolResult @@ -352,7 +352,7 @@ interface ChatStreamToolResult ### `ChatToolCallInfo` -`interface` +`interface` — Describe the structure and state of a tool call within a chat interaction ```ts interface ChatToolCallInfo @@ -368,7 +368,7 @@ interface ChatTurnFilePartInput ### `ChatTurnPartInput` -`type` +`type` — Resolve input as either a text part or a file part of a chat turn ```ts type ChatTurnPartInput @@ -392,7 +392,7 @@ interface ChatTurnRequestPayload ### `ChatUiMessage` -`interface` +`interface` — Describe the structure and properties of a chat message with roles, content, and optional metadata ```ts interface ChatUiMessage @@ -416,7 +416,7 @@ interface ChatUiMessage ### `ComposerAnswerDelivery` -`interface` +`interface` — Define the structure for delivering answers linked to a specific chat interaction and field ```ts interface ComposerAnswerDelivery @@ -456,7 +456,7 @@ interface ComposerMentionProp ### `ConsumeChatStreamResult` -`interface` +`interface` — Represent the result of consuming a chat stream including turn ID and content reception status ```ts interface ConsumeChatStreamResult @@ -488,7 +488,7 @@ interface ConsumeChatStreamResult ### `createMemoryInteractionAttemptStore` -`function` +`function` — Create an in-memory store to manage interaction attempts keyed by ID and signature ```ts () => InteractionAttemptStore @@ -496,7 +496,7 @@ interface ConsumeChatStreamResult ### `createSessionInteractionAttemptStore` -`function` +`function` — Create a session-based store to manage interaction attempts using provided storage and optional namespace ```ts (storage: Pick, namespace?: string) => InteractionAttemptStore @@ -504,7 +504,7 @@ interface ConsumeChatStreamResult ### `dedupeQuestionInteractionsByContent` -`function` +`function` — Remove duplicate question interactions based on their content signature to ensure uniqueness ```ts (interactions: ChatInteraction[]) => ChatInteraction[] @@ -608,7 +608,7 @@ interface DurableChatCardsProps ### `DurableInteractionAnswerSubmitterOptions` -`interface` +`interface` — Define options for submitting durable interaction answers with attempt tracking and optional key creation ```ts interface DurableInteractionAnswerSubmitterOptions @@ -632,7 +632,7 @@ interface DurablePlanCardProps ### `DurablePlanClientError` -`class` +`class` — Represent errors from DurablePlanClient operations including status, code, and current plan details ```ts class DurablePlanClientError @@ -640,7 +640,7 @@ class DurablePlanClientError ### `DurablePlanCurrentInput` -`interface` +`interface` — Define input parameters for retrieving the current durable plan including optional revision number ```ts interface DurablePlanCurrentInput @@ -648,7 +648,7 @@ interface DurablePlanCurrentInput ### `DurablePlanDecision` -`type` +`type` — Represent durable plan decisions as either approved or rejected ```ts type DurablePlanDecision @@ -656,7 +656,7 @@ type DurablePlanDecision ### `DurablePlanDecisionClient` -`interface` +`interface` — Define methods to obtain and decide durable plan decisions asynchronously ```ts interface DurablePlanDecisionClient @@ -664,7 +664,7 @@ interface DurablePlanDecisionClient ### `DurablePlanDecisionClientOptions` -`interface` +`interface` — Define configuration options for creating a durable plan decision client ```ts interface DurablePlanDecisionClientOptions @@ -672,7 +672,7 @@ interface DurablePlanDecisionClientOptions ### `DurablePlanDecisionInput` -`interface` +`interface` — Define input parameters for making a durable plan decision including optional feedback ```ts interface DurablePlanDecisionInput @@ -680,7 +680,7 @@ interface DurablePlanDecisionInput ### `DurablePlanDecisionResult` -`interface` +`interface` — Describe the result of a durable plan decision including plan details and pending statuses ```ts interface DurablePlanDecisionResult @@ -720,7 +720,7 @@ interface EffortPickerProps ### `fieldAcceptsFreeText` -`function` +`function` — Determine if a chat interaction field allows free text input ```ts (field: ChatInteractionField) => boolean @@ -736,7 +736,7 @@ interface EffortPickerProps ### `FieldValues` -`type` +`type` — Define a record mapping field names to objects with optional selected, text, and custom string arrays or values ```ts type FieldValues @@ -752,7 +752,7 @@ type FieldValues ### `FileIndexReadyResponse` -`interface` +`interface` — Describe a ready file index response with workspace-relative entries and truncation status ```ts interface FileIndexReadyResponse @@ -760,7 +760,7 @@ interface FileIndexReadyResponse ### `FileIndexResponse` -`type` +`type` — Resolve a response indicating the file index is either ready or warming up ```ts type FileIndexResponse @@ -888,7 +888,7 @@ number ### `INTERACTION_SUBMIT_TIMEOUT_MESSAGE` -`const` +`const` — Provide the timeout message displayed when the agent cannot be reached during interaction submission ```ts "Could not reach the agent. Try again." @@ -896,7 +896,7 @@ number ### `INTERACTION_SUBMIT_TIMEOUT_MS` -`const` +`const` — Define the timeout duration in milliseconds for submitting an interaction ```ts 30000 @@ -912,7 +912,7 @@ number ### `InteractionAnswers` -`type` +`type` — Map interaction identifiers to their corresponding answer values ```ts type InteractionAnswers @@ -928,7 +928,7 @@ interface InteractionAnswerSubmission ### `InteractionAnswerSubmitterOptions` -`interface` +`interface` — Define options for submitting interaction answers including URL, body, timeout, and fetch implementation ```ts interface InteractionAnswerSubmitterOptions @@ -944,7 +944,7 @@ type InteractionAnswerValue ### `InteractionAttemptStore` -`interface` +`interface` — Manage storage and retrieval of interaction attempt keys by interaction and submission identifiers ```ts interface InteractionAttemptStore @@ -968,7 +968,7 @@ type InteractionBadgeVariant ### `InteractionCancelData` -`interface` +`interface` — Describe data required to cancel an interaction including its identifier and optional reason ```ts interface InteractionCancelData @@ -1000,7 +1000,7 @@ type InteractionOutcome ### `interactionPartKey` -`function` +`function` — Generate a unique key string for an interaction using the given identifier ```ts (id: string) => string @@ -1072,7 +1072,7 @@ type InteractionRequestWire ### `interactionSubmissionSignature` -`function` +`function` — Generate a stable string signature from an interaction answer submission ```ts (submission: InteractionAnswerSubmission) => string @@ -1080,7 +1080,7 @@ type InteractionRequestWire ### `InteractionSubmitResult` -`type` +`type` — Resolve the result of an interaction submission indicating success or failure with details ```ts type InteractionSubmitResult @@ -1112,7 +1112,7 @@ type InteractionSubmitResult ### `isLateAnswerableStatus` -`function` +`function` — Determine if a status is late answerable by checking if it is expired or cancelled ```ts (status: ChatInteractionStatus) => boolean @@ -1120,7 +1120,7 @@ type InteractionSubmitResult ### `isRenderableInteractionKind` -`function` +`function` — Resolve if the given interaction kind is renderable within the application context ```ts (kind: string) => boolean @@ -1136,7 +1136,7 @@ type InteractionSubmitResult ### `isTerminalInteractionStatus` -`function` +`function` — Resolve if the interaction status is a terminal state excluding pending ```ts (status: ChatInteractionStatus) => boolean @@ -1272,7 +1272,7 @@ interface ModelPickerProps ### `NoticeKind` -`type` +`type` — Define specific string literals representing different kinds of notices ```ts type NoticeKind @@ -1288,7 +1288,7 @@ type NoticeKind ### `noticePartKey` -`function` +`function` — Generate a unique key string for a notice using the given identifier ```ts (id: string) => string @@ -1296,7 +1296,7 @@ type NoticeKind ### `NoticePersistedPart` -`type` +`type` — Define a persisted notice part with type, id, kind, and text properties ```ts type NoticePersistedPart @@ -1312,7 +1312,7 @@ type NoticePersistedPart ### `ParseInteractionAnswersResult` -`type` +`type` — Resolve the result of parsing interaction answers with success status and corresponding data or error message ```ts type ParseInteractionAnswersResult @@ -1320,7 +1320,7 @@ type ParseInteractionAnswersResult ### `parseInteractionCancel` -`function` +`function` — Parse interaction cancel data and return success status with parsed value or error message ```ts (data: Record | undefined) => { succeeded: true; value: InteractionCancelData; } | { succeeded: false;… @@ -1336,7 +1336,7 @@ type ParseInteractionAnswersResult ### `ParseInteractionResult` -`type` +`type` — Resolve interaction parsing outcome as success with value or failure with error message ```ts type ParseInteractionResult @@ -1360,7 +1360,7 @@ type ParseInteractionResult ### `ProducerErrorEvent` -`interface` +`interface` — Represent an error event emitted by a producer containing message, code, and optional details ```ts interface ProducerErrorEvent @@ -1368,7 +1368,7 @@ interface ProducerErrorEvent ### `ProducerNoticeEvent` -`interface` +`interface` — Define the structure for a producer notice event with type, id, kind, and text fields ```ts interface ProducerNoticeEvent @@ -1376,7 +1376,7 @@ interface ProducerNoticeEvent ### `ProducerPassthroughEvent` -`interface` +`interface` — Define an event carrying passthrough data with flexible properties for producer communication ```ts interface ProducerPassthroughEvent @@ -1392,7 +1392,7 @@ type ProducerPassthroughEventType ### `ProducerReasoningEvent` -`interface` +`interface` — Define an event representing reasoning output with a fixed type and associated text ```ts interface ProducerReasoningEvent @@ -1400,7 +1400,7 @@ interface ProducerReasoningEvent ### `ProducerTextEvent` -`interface` +`interface` — Represent a text event produced by a source with a fixed type and associated text content ```ts interface ProducerTextEvent @@ -1408,7 +1408,7 @@ interface ProducerTextEvent ### `ProducerToolCallEvent` -`interface` +`interface` — Represent an event triggered by a producer tool call with its identifier, name, and arguments ```ts interface ProducerToolCallEvent @@ -1416,7 +1416,7 @@ interface ProducerToolCallEvent ### `ProducerToolResultEvent` -`interface` +`interface` — Describe the structure of an event representing the result of a producer tool call ```ts interface ProducerToolResultEvent @@ -1424,7 +1424,7 @@ interface ProducerToolResultEvent ### `ProducerUsageEvent` -`interface` +`interface` — Describe usage event with prompt and completion token counts for a producer ```ts interface ProducerUsageEvent @@ -1432,7 +1432,7 @@ interface ProducerUsageEvent ### `ProducerWireEvent` -`type` +`type` — Represent events emitted by a producer during its operation for processing and handling ```ts type ProducerWireEvent @@ -1440,7 +1440,7 @@ type ProducerWireEvent ### `ProposalApprovalHandlers` -`interface` +`interface` — Handle approval and rejection actions for proposals with asynchronous support ```ts interface ProposalApprovalHandlers @@ -1520,7 +1520,7 @@ interface QuestionOptionListProps ### `RestoreChatInteractionsOptions` -`interface` +`interface` — Define options to control how chat interactions are restored during the restore process ```ts interface RestoreChatInteractionsOptions @@ -1536,7 +1536,7 @@ interface RestoreChatInteractionsOptions ### `RunDrillInProps` -`interface` +`interface` — Define properties required to run a drill and handle its closure event ```ts interface RunDrillInProps @@ -1544,7 +1544,7 @@ interface RunDrillInProps ### `SandboxTerminalConnection` -`interface` +`interface` — Define the connection details and status for a sandbox terminal session ```ts interface SandboxTerminalConnection @@ -1552,7 +1552,7 @@ interface SandboxTerminalConnection ### `SandboxTerminalConnectionResponse` -`interface` +`interface` — Define the response structure for a sandbox terminal connection including URLs, token, status, and errors ```ts interface SandboxTerminalConnectionResponse @@ -1584,7 +1584,7 @@ interface SeatPaywallProps ### `SmoothRevealOptions` -`interface` +`interface` — Define configuration options for controlling smooth text reveal animation rates ```ts interface SmoothRevealOptions @@ -1600,7 +1600,7 @@ interface SmoothRevealOptions ### `StreamChatOptions` -`interface` +`interface` — Define options for managing and resuming streaming chat interactions with callbacks ```ts interface StreamChatOptions @@ -1680,7 +1680,7 @@ interface ToolRunStep ### `useChatInteractions` -`function` +`function` — Manage chat interactions state with upsert, cancel, resolve, and restore capabilities ```ts (options?: RestoreChatInteractionsOptions) => UseChatInteractionsResult @@ -1688,7 +1688,7 @@ interface ToolRunStep ### `UseChatInteractionsOptions` -`type` +`type` — Resolve options for restoring chat interactions from previous sessions ```ts type UseChatInteractionsOptions @@ -1696,7 +1696,7 @@ type UseChatInteractionsOptions ### `UseChatInteractionsResult` -`interface` +`interface` — Resolve and manage chat interactions with methods to update, cancel, mark resolved, and restore state ```ts interface UseChatInteractionsResult @@ -1712,7 +1712,7 @@ interface UseChatInteractionsResult ### `UseComposerAttachmentsOptions` -`interface` +`interface` — Define options for configuring file upload behavior and handling in a composer component ```ts interface UseComposerAttachmentsOptions @@ -1720,7 +1720,7 @@ interface UseComposerAttachmentsOptions ### `UseComposerAttachmentsResult` -`interface` +`interface` — Provide staged file chips, ready attachments, and methods to add, retry, or drop composer files ```ts interface UseComposerAttachmentsResult @@ -1736,7 +1736,7 @@ interface UseComposerAttachmentsResult ### `UseDurablePlanFlowOptions` -`interface` +`interface` — Define options to configure durable plan flow with plan, client, and optional callbacks ```ts interface UseDurablePlanFlowOptions @@ -1744,7 +1744,7 @@ interface UseDurablePlanFlowOptions ### `UseDurablePlanFlowResult` -`interface` +`interface` — Define the result and actions for managing a durable plan flow including decisions, restoration, and error handling ```ts interface UseDurablePlanFlowResult @@ -1752,7 +1752,7 @@ interface UseDurablePlanFlowResult ### `useFileMentions` -`function` +`function` — Resolve and manage file mention data with configurable fetching and state handling ```ts (options: UseFileMentionsOptions) => UseFileMentionsResult @@ -1760,7 +1760,7 @@ interface UseDurablePlanFlowResult ### `UseFileMentionsOptions` -`interface` +`interface` — Define options for configuring file mention fetching, caching, and display behavior ```ts interface UseFileMentionsOptions @@ -1768,7 +1768,7 @@ interface UseFileMentionsOptions ### `UseFileMentionsResult` -`interface` +`interface` — Provide properties and methods to manage and refresh file mentions in a composer interface ```ts interface UseFileMentionsResult @@ -1792,7 +1792,7 @@ interface UseFileMentionsResult ### `useSandboxTerminalConnection` -`function` +`function` — Manage and maintain a sandbox terminal connection with automatic polling and token refresh handling ```ts (opts: UseSandboxTerminalConnectionOptions) => UseSandboxTerminalConnectionResult @@ -1800,7 +1800,7 @@ interface UseFileMentionsResult ### `UseSandboxTerminalConnectionOptions` -`interface` +`interface` — Define options for configuring a sandbox terminal connection including workspace ID and connection parameters ```ts interface UseSandboxTerminalConnectionOptions @@ -1808,7 +1808,7 @@ interface UseSandboxTerminalConnectionOptions ### `UseSandboxTerminalConnectionResult` -`interface` +`interface` — Resolve sandbox terminal connection status and provide a method to initiate the connection ```ts interface UseSandboxTerminalConnectionResult diff --git a/docs/api/web.md b/docs/api/web.md index c1b124e..3f19e83 100644 --- a/docs/api/web.md +++ b/docs/api/web.md @@ -40,7 +40,7 @@ Source: `src/web/index.ts` ### `CookieOptions` -`interface` +`interface` — Define options for configuring cookie attributes and behavior ```ts interface CookieOptions @@ -80,7 +80,7 @@ interface KvLike ### `RateLimitResult` -`interface` +`interface` — Describe the outcome of a rate limit check including allowance, remaining count, and reset time ```ts interface RateLimitResult @@ -96,7 +96,7 @@ interface RateLimitResult ### `RequestContext` -`interface` +`interface` — Define the context of a request including IP address, user agent, timestamp, and request ID ```ts interface RequestContext @@ -112,7 +112,7 @@ interface RequestContext ### `SecurityHeaderOptions` -`interface` +`interface` — Define options for configuring security-related HTTP headers including disclaimers and retention labels ```ts interface SecurityHeaderOptions diff --git a/src/app-auth/index.ts b/src/app-auth/index.ts index 3c212e8..65a1e47 100644 --- a/src/app-auth/index.ts +++ b/src/app-auth/index.ts @@ -45,6 +45,7 @@ export interface AppAuthEmailClient { } } +/** Define email configuration for app authentication including client, sender, verification, and warning options */ export interface AppAuthEmailConfig { /** A Resend-style client, or a lazy getter returning null when the API key * is absent (the products' dev default — mail is skipped with a warning, @@ -66,6 +67,7 @@ export interface AppAuthSocialProviderConfig { clientSecret?: string } +/** Define social authentication configuration options for GitHub and Google providers */ export interface AppAuthSocialConfig { github?: AppAuthSocialProviderConfig google?: AppAuthSocialProviderConfig @@ -99,6 +101,7 @@ export interface AppAuthSsoConfig { log?: (message: string, error?: unknown) => void } +/** Define the structure for application authentication data including users, sessions, accounts, and verifications */ export interface AppAuthSchema { users: unknown sessions: unknown @@ -106,6 +109,7 @@ export interface AppAuthSchema { verifications: unknown } +/** Define configuration settings for app authentication including app name, base URL, secrets, and trusted origins */ export interface AppAuthConfig { /** Product name — used in email subjects and as the cookie-prefix default. */ appName: string @@ -163,6 +167,7 @@ export interface AppAuthSession { user: User } +/** Define authentication guard with session retrieval and optional SSO handlers for app requests */ export interface AppAuth extends AuthGuard { auth: AppAuthInstance /** `auth.api.getSession` over a `Request` — the seam the guards consume. */ diff --git a/src/assets/schema.ts b/src/assets/schema.ts index 9241c18..d63a1d8 100644 --- a/src/assets/schema.ts +++ b/src/assets/schema.ts @@ -3,6 +3,7 @@ import type { AssetSpec, AssetFormat } from './types' // --- Brand --- +/** Validate brand token properties including colors, font, logo URL, business name, and voice */ export const BrandTokensSchema = z.object({ primaryColor: z.string(), accentColor: z.string(), @@ -64,6 +65,7 @@ const EmailSectionSchema = z.discriminatedUnion('type', [ EmailDividerSectionSchema, ]) +/** Validate and parse email content objects with subject, optional preheader, and sections */ export const EmailContentSchema = z.object({ subject: z.string(), preheader: z.string().optional(), @@ -130,6 +132,7 @@ const ImageSlideSchema = z.object({ layers: z.array(ImageLayerSchema), }) +/** Validate image content with an array of one or more slides containing background details */ export const ImageContentSchema = z.object({ slides: z.array(ImageSlideSchema).min(1), }) @@ -178,6 +181,7 @@ const VideoCaptionSchema = z.object({ text: z.string(), }) +/** Define the schema for validating video content including duration, scenes, audio, captions, and rendered URL */ export const VideoContentSchema = z.object({ durationSeconds: z.number().positive(), scenes: z.array(VideoSceneSchema).min(1), @@ -188,6 +192,7 @@ export const VideoContentSchema = z.object({ // --- Copy --- +/** Validate and parse copy content with headline, body, optional hashtags, platform, and character count */ export const CopyContentSchema = z.object({ headline: z.string(), body: z.string(), @@ -198,6 +203,7 @@ export const CopyContentSchema = z.object({ // --- Approval --- +/** Validate approval event data including asset, action, user, timestamp, and optional fields */ export const ApprovalEventSchema = z.object({ assetId: z.string(), variantId: z.string().optional(), @@ -207,6 +213,7 @@ export const ApprovalEventSchema = z.object({ timestamp: z.string(), }) +/** Validate conversion metrics with nonnegative impressions, clicks, conversions, CTR, and CVR fields */ export const ConversionMetricsSchema = z.object({ impressions: z.number().nonnegative(), clicks: z.number().nonnegative(), diff --git a/src/assets/types.ts b/src/assets/types.ts index 4ff7cb6..d642e19 100644 --- a/src/assets/types.ts +++ b/src/assets/types.ts @@ -1,3 +1,4 @@ +/** Define brand identity tokens including colors, font, logo, business name, and voice */ export interface BrandTokens { primaryColor: string accentColor: string @@ -8,6 +9,7 @@ export interface BrandTokens { voice: string } +/** Define valid asset format strings for various media and copy types */ export type AssetFormat = | 'email' | 'image:feed' @@ -19,6 +21,7 @@ export type AssetFormat = | 'copy:headline' | 'copy:sms' +/** Define possible states representing the lifecycle status of an asset */ export type AssetStatus = | 'draft' | 'pending_review' @@ -29,6 +32,7 @@ export type AssetStatus = // --- Email --- +/** Define the structure for a hero section in an email with headline, image, and call-to-action fields */ export interface EmailHeroSection { type: 'hero' headline: string @@ -38,11 +42,13 @@ export interface EmailHeroSection { ctaUrl?: string } +/** Define the structure for the body section of an email containing plain text content */ export interface EmailBodySection { type: 'body' text: string } +/** Define a feature section with headline, description, and optional image for email content */ export interface EmailFeatureSection { type: 'feature' headline: string @@ -50,6 +56,7 @@ export interface EmailFeatureSection { imageUrl?: string } +/** Define the structure for an email testimonial section with quote, author, and optional details */ export interface EmailTestimonialSection { type: 'testimonial' quote: string @@ -58,6 +65,7 @@ export interface EmailTestimonialSection { avatarUrl?: string } +/** Define a call-to-action section with label, URL, and optional subtext for email content */ export interface EmailCtaSection { type: 'cta' label: string @@ -65,10 +73,12 @@ export interface EmailCtaSection { subtext?: string } +/** Define a section representing a divider in an email layout */ export interface EmailDividerSection { type: 'divider' } +/** Define a union type representing different sections of an email template */ export type EmailSection = | EmailHeroSection | EmailBodySection @@ -77,6 +87,7 @@ export type EmailSection = | EmailCtaSection | EmailDividerSection +/** Define the structure for email content including subject, optional preheader, and sections */ export interface EmailContent { subject: string preheader?: string @@ -85,8 +96,10 @@ export interface EmailContent { // --- Image --- +/** Define image layer categories for text, image, shape, or logo elements */ export type ImageLayerType = 'text' | 'image' | 'shape' | 'logo' +/** Define properties for a text layer with position, style, and alignment options in an image */ export interface ImageTextLayer { type: 'text' text: string @@ -99,6 +112,7 @@ export interface ImageTextLayer { align?: 'left' | 'center' | 'right' } +/** Define properties for an image layer including position, size, URL, and optional opacity */ export interface ImageImageLayer { type: 'image' url: string @@ -109,6 +123,7 @@ export interface ImageImageLayer { opacity?: number } +/** Define properties for a shape layer representing rectangular or circular image elements */ export interface ImageShapeLayer { type: 'shape' shape: 'rect' | 'circle' | 'rounded-rect' @@ -120,6 +135,7 @@ export interface ImageShapeLayer { opacity?: number } +/** Define properties for positioning and sizing a logo image layer in a layout */ export interface ImageLogoLayer { type: 'logo' x: number @@ -127,24 +143,29 @@ export interface ImageLogoLayer { width?: number } +/** Resolve a union type representing different kinds of image layers */ export type ImageLayer = ImageTextLayer | ImageImageLayer | ImageShapeLayer | ImageLogoLayer +/** Define image background styles as color, gradient, or image with optional overlay settings */ export type ImageBackground = | { type: 'color'; value: string } | { type: 'gradient'; from: string; to: string; direction?: string } | { type: 'image'; url: string; overlay?: string; overlayOpacity?: number } +/** Define the structure for an image slide with a background and multiple layers */ export interface ImageSlide { background: ImageBackground layers: ImageLayer[] } +/** Define the structure for image content containing an array of image slides */ export interface ImageContent { slides: ImageSlide[] } // --- Video --- +/** Define properties for a video scene displaying animated text with optional background and effects */ export interface VideoTextAnimationScene { type: 'text-animation' durationSeconds: number @@ -154,6 +175,7 @@ export interface VideoTextAnimationScene { background?: ImageBackground } +/** Define a scene that reveals an image with optional caption over a specified duration */ export interface VideoImageRevealScene { type: 'image-reveal' durationSeconds: number @@ -161,12 +183,14 @@ export interface VideoImageRevealScene { caption?: string } +/** Define a video slide scene with duration and associated image slide details */ export interface VideoSlideScene { type: 'slide' durationSeconds: number slide: ImageSlide } +/** Define a countdown scene with duration, start time, and optional label for video sequences */ export interface VideoCountdownScene { type: 'countdown' durationSeconds: number @@ -174,18 +198,21 @@ export interface VideoCountdownScene { label?: string } +/** Resolve a video scene as one of several specific animation or reveal types */ export type VideoScene = | VideoTextAnimationScene | VideoImageRevealScene | VideoSlideScene | VideoCountdownScene +/** Define video caption segments with start and end times and associated text content */ export interface VideoCaption { startSeconds: number endSeconds: number text: string } +/** Describe video content including duration, scenes, optional audio, captions, and rendered URL */ export interface VideoContent { durationSeconds: number scenes: VideoScene[] @@ -196,8 +223,10 @@ export interface VideoContent { // --- Copy --- +/** Define platform options for copy content across various social media and communication channels */ export type CopyPlatform = 'instagram' | 'tiktok' | 'x' | 'linkedin' | 'sms' | 'email-subject' +/** Define the structure for content with headline, body, platform, and optional hashtags and character count */ export interface CopyContent { headline: string body: string @@ -208,6 +237,7 @@ export interface CopyContent { // --- Core spec --- +/** Map asset keys to their corresponding content types for various media and copy formats */ export type AssetContentMap = { email: EmailContent 'image:feed': ImageContent @@ -220,6 +250,7 @@ export type AssetContentMap = { 'copy:sms': CopyContent } +/** Define the structure and metadata for an asset including its format, brand, content, and status */ export interface AssetSpec { id: string workspaceId: string @@ -235,6 +266,7 @@ export interface AssetSpec { // --- Variants & approval --- +/** Describe an asset variant with identification, approval status, and edit history details */ export interface AssetVariant { id: string parentId: string @@ -245,6 +277,7 @@ export interface AssetVariant { editLog: ApprovalEvent[] } +/** Describe an approval event with action details, user info, and optional edited fields */ export interface ApprovalEvent { assetId: string variantId?: string @@ -254,6 +287,7 @@ export interface ApprovalEvent { timestamp: string } +/** Define metrics for tracking impressions, clicks, conversions, and related rates */ export interface ConversionMetrics { impressions: number clicks: number diff --git a/src/assistant/client.ts b/src/assistant/client.ts index ed1fbd1..ef4e30b 100644 --- a/src/assistant/client.ts +++ b/src/assistant/client.ts @@ -42,6 +42,7 @@ export interface AssistantClientConfig { headers?: () => Record; } +/** Define options for an assistant model including identifier, label, pricing, and context tokens */ export interface AssistantModelOption { slug: string; label: string; @@ -51,6 +52,7 @@ export interface AssistantModelOption { contextTokens?: number; } +/** Define the structure for assistant model options including a default model slug and available models */ export interface AssistantModels { /** The slug the server uses when a turn selects no model. */ default: string | null; @@ -90,10 +92,12 @@ export type ThreadHistoryResult = | { status: "gone" } | { status: "error" }; +/** Represent the outcome of a confirmation process with success or failure details */ export type ConfirmResult = | { ok: true; output: unknown; retryable?: boolean } | { ok: false; error: string }; +/** Represent invalid client input errors with a specific code INVALID_REQUEST */ export class AssistantClientInputError extends Error { readonly code = "INVALID_REQUEST"; } diff --git a/src/assistant/types.ts b/src/assistant/types.ts index 8183570..159baf9 100644 --- a/src/assistant/types.ts +++ b/src/assistant/types.ts @@ -7,6 +7,7 @@ import type { ReactNode } from "react"; +/** Define delivery modes for assistant interaction as either steering or queue */ export type AssistantDeliveryMode = "steering" | "queue"; /** Request body for `POST /api/v1/assistant/chat`. */ @@ -24,6 +25,7 @@ export interface ChatRequest { // --- Server SSE event payloads (one per `event:` name) ---------------------- +/** Describe the structure of data representing a thread event with optional model information */ export interface ThreadEventData { threadId: string; turnId: string; @@ -31,6 +33,7 @@ export interface ThreadEventData { model?: string | null; } +/** Define data structure representing a delta event with associated text content */ export interface DeltaEventData { text: string; } @@ -52,6 +55,7 @@ export interface ToolCallEventData { args?: Record; } +/** Describe event data emitted after a tool execution completes with success or error details */ export interface ToolResultEventData { callId: string; name: string; @@ -96,6 +100,7 @@ export interface ConnectRequirementResult { connected: boolean; } +/** Describe the data structure for events proposing tool usage with optional integration requirements */ export interface ToolProposalEventData { /** Null only if the server has no proposal store wired (tools then unusable). */ proposalId: string | null; @@ -107,6 +112,7 @@ export interface ToolProposalEventData { requirements?: ConnectionRequirement[]; } +/** Describe usage event data including tokens, cost, balance, duration, and replay status */ export interface UsageEventData { promptTokens: number | null; completionTokens: number | null; @@ -119,6 +125,7 @@ export interface UsageEventData { replayed?: boolean; } +/** Describe the data emitted when a process turn completes including status and optional flags */ export interface DoneEventData { turnId: string; status: string; @@ -128,6 +135,7 @@ export interface DoneEventData { capped?: boolean; } +/** Describe error event data including code and message fields */ export interface ErrorEventData { code: string; message: string; @@ -184,6 +192,7 @@ export interface ConfirmedResult { args?: unknown; } +/** Define the structure and properties of a chat message including optional tool activity details */ export interface ChatMessage { id: string; role: ChatRole; @@ -218,6 +227,7 @@ export interface PendingProposal { retryError?: string | null; } +/** Describe usage cost, balance, token counts, duration, and replay status for a settled turn */ export interface UsageInfo { costUsd: number | null; balanceUsd: number | null; diff --git a/src/assistant/useAssistantChat.ts b/src/assistant/useAssistantChat.ts index 133384d..daf87c6 100644 --- a/src/assistant/useAssistantChat.ts +++ b/src/assistant/useAssistantChat.ts @@ -25,6 +25,7 @@ import type { PendingProposal, } from "./types"; +/** Define options for configuring how the assistant sends messages */ export interface AssistantSendOptions { deliveryMode?: AssistantDeliveryMode; } @@ -79,6 +80,7 @@ function uuid(): string { return crypto.randomUUID(); } +/** Define the structure and behavior of an assistant chat session with state, model selection, and message handling */ export interface AssistantChat { state: AssistantState; /** Proposal ids whose confirmation is currently in flight (for disabling). */ @@ -110,6 +112,7 @@ export interface AssistantChat { restoring: boolean; } +/** Manage assistant chat state and interactions for a given user ID with optional configurations */ export function useAssistantChat( userId: string | null, options?: UseAssistantChatOptions, diff --git a/src/assistant/useAssistantModels.ts b/src/assistant/useAssistantModels.ts index d3fd3f7..53eeb28 100644 --- a/src/assistant/useAssistantModels.ts +++ b/src/assistant/useAssistantModels.ts @@ -44,6 +44,7 @@ function cacheFor(client: AssistantClient): ModelCache { return entry; } +/** Resolve and return the current assistant models from the per-client cache with immediate client swap updates */ export function useAssistantModels(): AssistantModels { const client = useAssistantClient(); // The per-client cache is the source of truth; `bump` just forces a re-read diff --git a/src/assistant/useAssistantThreads.ts b/src/assistant/useAssistantThreads.ts index 88cbf39..13b4cab 100644 --- a/src/assistant/useAssistantThreads.ts +++ b/src/assistant/useAssistantThreads.ts @@ -17,6 +17,7 @@ import { useCallback, useEffect, useRef, useState } from "react"; import type { AssistantClient, AssistantThreadSummary } from "./client"; import { useAssistantClient } from "./client-context"; +/** Manage and interact with a list of assistant threads including loading, refreshing, and removing threads */ export interface AssistantThreads { threads: AssistantThreadSummary[]; loading: boolean; @@ -44,6 +45,7 @@ interface ThreadsState { ownerClient: AssistantClient | null; } +/** Resolve and manage assistant threads state for a given user including pending deletions and refresh logic */ export function useAssistantThreads(userId: string | null): AssistantThreads { const client = useAssistantClient(); const userRef = useRef(userId); diff --git a/src/billing/index.ts b/src/billing/index.ts index f982b8e..39a753b 100644 --- a/src/billing/index.ts +++ b/src/billing/index.ts @@ -97,6 +97,7 @@ export interface KeyCrypto { decrypt(encrypted: string): Promise } +/** Define configuration options for managing workspace keys including provisioning, storage, and cryptography */ export interface WorkspaceKeyManagerOptions { provisioner: KeyProvisioner store: WorkspaceKeyStore @@ -109,6 +110,7 @@ export interface WorkspaceKeyManagerOptions { product?: string } +/** Describe usage and budget details for a workspace model key including expiration and exhaustion status */ export interface WorkspaceModelKeyUsage { keyId: string budgetUsd: number @@ -118,6 +120,7 @@ export interface WorkspaceModelKeyUsage { exhausted: boolean } +/** Manage workspace keys by ensuring, rotating, and tracking usage of active child-key secrets */ export interface WorkspaceKeyManager { /** The workspace's active child-key secret, provisioning one if absent/expired. */ ensureKey(workspaceId: string, opts?: { budgetUsd?: number }): Promise @@ -217,6 +220,7 @@ export interface PlatformBillingClient { deduct(input: { platformUserId: string; amountUsd: number; type: string; description: string; referenceId: string }): Promise } +/** Define shared billing state including user ID, plan, balances, concurrency, and overage permission */ export interface SharedBillingState { /** Platform user id, or null when the user has no Tangle SSO account. */ platformUserId: string | null @@ -228,6 +232,7 @@ export interface SharedBillingState { overageAllowed: boolean } +/** Define configuration options for managing platform balance based on billing plans */ export interface PlatformBalanceManagerOptions { client: PlatformBillingClient /** Plan → limits map (the product's pricing). */ @@ -238,6 +243,7 @@ export interface PlatformBalanceManagerOptions { productSlug: string } +/** Manage user plans and balances including state retrieval, billing authorization, deduction, and usage tracking */ export interface PlatformBalanceManager { /** Resolve the user's plan + balance. Unlinked or platform-outage users fail * CLOSED: free plan, zero remaining balance — a billable run is never started @@ -253,6 +259,7 @@ export interface PlatformBalanceManager { getProductUsage(userId: string): Promise<{ spentUsd: number; transactionCount: number }> } +/** Create a platform balance manager to handle user plan limits and state based on provided options */ export function createPlatformBalanceManager( opts: PlatformBalanceManagerOptions, ): PlatformBalanceManager { @@ -317,6 +324,7 @@ export function createPlatformBalanceManager( return { getState, canStartBillableTurn, deduct, getProductUsage } } +/** Create a workspace key manager that handles key provisioning and budget tracking */ export function createWorkspaceKeyManager(opts: WorkspaceKeyManagerOptions): WorkspaceKeyManager { const clock = opts.now ?? (() => new Date()) const product = opts.product ?? 'router' diff --git a/src/brand-extraction/map.ts b/src/brand-extraction/map.ts index a319b02..8796eb4 100644 --- a/src/brand-extraction/map.ts +++ b/src/brand-extraction/map.ts @@ -30,6 +30,7 @@ function isGreyish(hex: string): boolean { return max - min < 18 } +/** Define a color palette with background, surface, text, and accent colors for UI elements */ export interface DecidedPalette { /** Lightest neutral — page background. */ background?: string @@ -80,6 +81,7 @@ export function decidePalette(palette: BrandColor[]): DecidedPalette { return result } +/** Define font selections for display and body text with optional BrandFont properties */ export interface DecidedFonts { display?: BrandFont body?: BrandFont diff --git a/src/brand-extraction/types.ts b/src/brand-extraction/types.ts index 88b83fa..710f883 100644 --- a/src/brand-extraction/types.ts +++ b/src/brand-extraction/types.ts @@ -102,6 +102,7 @@ export type FetchLike = (url: string, init?: { signal?: AbortSignal; headers?: R headers?: { get(name: string): string | null } }> +/** Define options for extracting brand kit data including HTML input, fetch method, timeout, and list limits */ export interface ExtractBrandKitOptions { /** Raw HTML for the page. When supplied, no network fetch happens — used by * tests and by callers that already hold the HTML. */ diff --git a/src/brand/index.tsx b/src/brand/index.tsx index c373d09..a20a8e8 100644 --- a/src/brand/index.tsx +++ b/src/brand/index.tsx @@ -17,6 +17,7 @@ */ import type { ReactNode } from 'react' +/** Define properties to customize the logo variant, size, style, and icon display options */ export interface LogoProps { /** Reserved for future lockups; only the default ('sandbox') exists today. */ variant?: 'sandbox' @@ -114,6 +115,7 @@ export function Logo({ variant = 'sandbox', size = 'md', className, iconOnly = f ) } +/** Define properties for a brand header including optional title, children, and CSS class name */ export interface BrandHeaderProps { /** Product name rendered next to the knot. Omit for a mark-only header. */ title?: string diff --git a/src/chat-routes/attachment-upload.ts b/src/chat-routes/attachment-upload.ts index e2b8f80..b4806ab 100644 --- a/src/chat-routes/attachment-upload.ts +++ b/src/chat-routes/attachment-upload.ts @@ -53,6 +53,7 @@ export type AttachmentUploadAuthorization = | { ok: true; scopeId: string; writeAttachment?: WriteAttachmentFn } | { 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. */ @@ -93,6 +94,7 @@ function attachmentUploadError(status: number, code: string, message: string, pa ) } +/** Resolve an attachment upload route handler with customizable limits and validation options */ export function createAttachmentUploadRoute( options: CreateAttachmentUploadRouteOptions, ): (request: Request) => Promise { diff --git a/src/chat-routes/attachment-validation.ts b/src/chat-routes/attachment-validation.ts index ad4619d..d9cf66e 100644 --- a/src/chat-routes/attachment-validation.ts +++ b/src/chat-routes/attachment-validation.ts @@ -85,6 +85,7 @@ const EXTENSION_IMPLIES_SNIFFED_MIME: Readonly> = { pdf: 'application/pdf', } +/** Represent the result of checking an attachment's type with success or specific failure details */ export type AttachmentTypeCheckResult = | { succeeded: true } | { succeeded: false; code: 'attachment_type_mismatch' | 'attachment_type_not_allowed'; message: string } diff --git a/src/chat-routes/detached-turn.ts b/src/chat-routes/detached-turn.ts index a4ef710..0c7f22b 100644 --- a/src/chat-routes/detached-turn.ts +++ b/src/chat-routes/detached-turn.ts @@ -51,6 +51,7 @@ export interface DetachedTurnFinal { parts?: DetachedTurnParts } +/** Define options for managing and projecting a detached turn event stream in a session */ export interface DetachedTurnOptions { store: TurnEventStore turnId: string @@ -93,6 +94,7 @@ export interface DetachedTurnOptions { log?: (message: string, meta?: Record) => void } +/** Describe the result of a detached turn including state, text, parts, usage, and optional error or cache flag */ export interface DetachedTurnResult { /** `completed` — clean drain: persist + bill. `failed` — a terminal error * event, including the producer's structured `sandbox.stream_failed` event diff --git a/src/chat-routes/dispatch-parts.ts b/src/chat-routes/dispatch-parts.ts index 097b689..ffb8f87 100644 --- a/src/chat-routes/dispatch-parts.ts +++ b/src/chat-routes/dispatch-parts.ts @@ -39,6 +39,7 @@ import type { ReadAttachmentFn } from './attachment-store' export type { PromptInputPart } +/** Resolve the outcome of dispatching parts with success status and corresponding value or error message */ export type DispatchPartsOutcome = | { succeeded: true; value: PromptInputPart[] } | { succeeded: false; error: string } @@ -49,6 +50,7 @@ type SandboxMentionReadOutcome = | { succeeded: true; value: { size: number; base64?: string } } | { succeeded: false; error: string } +/** Resolve sandbox mention details by reading from a specified path with optional byte reading */ export type ReadSandboxMentionFn = ( box: SandboxExecChannel, absolutePath: string, @@ -95,6 +97,7 @@ function violatesUrlPathXor(part: PromptInputPart): boolean { return hasUrl === hasPath } +/** Build input parameters for dispatching chat message parts including text, attachments, mentions, and history */ export interface BuildDispatchPartsInput { text: string attachments: ChatAttachmentPart[] @@ -142,6 +145,7 @@ function readResultToBase64(read: { base64?: string; bytes?: Uint8Array }): stri return undefined } +/** Build dispatch parts from input by resolving mentions, paths, and applying size constraints asynchronously */ export async function buildDispatchParts(input: BuildDispatchPartsInput): Promise { const readMention = input.readSandboxMention ?? readSandboxMention const resolveMentionPath = input.resolveMentionPath ?? input.resolveAttachmentPath diff --git a/src/chat-routes/durable-projection.ts b/src/chat-routes/durable-projection.ts index ac1c07d..953974b 100644 --- a/src/chat-routes/durable-projection.ts +++ b/src/chat-routes/durable-projection.ts @@ -1,11 +1,13 @@ import { getPartKey, mergePersistedPart, type StreamEvent } from '../stream/index' import type { ChatTurnRouteProducer } from './turn-routes' +/** Resolve chat route events and materialize their durable state records */ export interface ChatRouteDurableProjection { observe(event: unknown): void | Promise materialize(): Array> | Promise>> } +/** Log chat route projection messages with optional metadata for durable processing */ export type ChatRouteDurableProjectionLogger = (message: string, meta?: Record) => void diff --git a/src/chat-routes/file-index.ts b/src/chat-routes/file-index.ts index 7a1be69..88a8d04 100644 --- a/src/chat-routes/file-index.ts +++ b/src/chat-routes/file-index.ts @@ -41,6 +41,7 @@ export interface SandboxFileTreeSource { tree(path: string, options?: { maxDepth?: number }): Promise } +/** Describe a ready file index response with workspace-relative entries and truncation status */ export interface FileIndexReadyResponse { status: 'ready' /** Workspace-relative entries. Same shape as `FileMention` (`./wire`) so a @@ -63,6 +64,7 @@ export interface FileIndexWarmingResponse { status: 'warming' } +/** Resolve a response indicating the file index is either ready or warming up */ export type FileIndexResponse = FileIndexReadyResponse | FileIndexWarmingResponse /** Short-TTL cache seam so repeat popover opens in the same session don't @@ -73,6 +75,7 @@ export interface FileIndexCache { put(key: string, value: FileIndexReadyResponse, options?: { ttlSeconds?: number }): Promise | void } +/** Define authorization details and parameters for indexing a file workspace with optional caching and ignore rules */ export type FileIndexAuthorization = | { status: 'ready' @@ -90,6 +93,7 @@ export type FileIndexAuthorization = | { status: 'warming' } | { status: 'denied'; response: Response } +/** Define options to authorize and configure sandbox file index route behavior */ export interface CreateSandboxFileIndexRouteOptions { /** Authenticate the caller, resolve the sandbox `fs` handle, and signal a * cold box — never provisions or waits. */ @@ -188,6 +192,7 @@ function escapeRegExp(value: string): string { return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') } +/** Resolve a sandbox file index route with authorization, caching, and configurable depth and entries limits */ export function createSandboxFileIndexRoute( options: CreateSandboxFileIndexRouteOptions, ): (request: Request) => Promise { diff --git a/src/chat-routes/promote-file-part.ts b/src/chat-routes/promote-file-part.ts index ee85b28..b55e182 100644 --- a/src/chat-routes/promote-file-part.ts +++ b/src/chat-routes/promote-file-part.ts @@ -32,6 +32,7 @@ import { formatBytes } from './wire' /** Default ceiling on a promoted file's raw (pre-encoding) byte size. */ export const PROMOTE_MAX_FILE_BYTES = 10 * 1024 * 1024 +/** Define the structure for a raw file part with optional metadata and media type information */ export interface RawAgentFilePart { type: 'file' id?: string @@ -43,6 +44,7 @@ export interface RawAgentFilePart { url?: string } +/** Resolve the result of promoting a file part with success status and relevant data or error details */ export type PromoteFilePartResult = | { succeeded: true; part: ChatAttachmentPart } | { succeeded: false; filename: string; reason: string } @@ -249,6 +251,7 @@ function defaultBuildAttachmentPath(args: AttachmentPathArgs): string { return `uploads/agent/${args.date}/${base}-${args.hash8}${extension}` } +/** Define options for promoting a part of an agent file within a specific session and scope */ export interface PromoteAgentFilePartOptions { raw: RawAgentFilePart /** The turn's box — required only to promote a sandbox-path part; a `data:` @@ -270,6 +273,7 @@ export interface PromoteAgentFilePartOptions { now?: () => Date } +/** Promote a part of an agent file with optional byte limits and MIME type detection */ export async function promoteAgentFilePart(options: PromoteAgentFilePartOptions): Promise { const maxBytes = options.maxBytes ?? PROMOTE_MAX_FILE_BYTES const sniffMime = options.sniffMime ?? sniffMimeFromName diff --git a/src/chat-routes/resolve-attachments.ts b/src/chat-routes/resolve-attachments.ts index beded9f..873ef90 100644 --- a/src/chat-routes/resolve-attachments.ts +++ b/src/chat-routes/resolve-attachments.ts @@ -21,6 +21,7 @@ import { attachmentInputToPart, type ChatAttachmentPart } from '../chat-store/pa import type { ReadAttachmentFn } from './attachment-store' import { ATTACHMENT_MAX_COUNT, MAX_ATTACHMENT_TOTAL_BYTES, attachmentTotalSizeErrorMessage } from './attachment-validation' +/** Resolve the result of chat attachment processing with success status and corresponding data or error */ export type ResolveChatAttachmentsResult = | { succeeded: true; value: ChatAttachmentPart[] } | { succeeded: false; error: string } @@ -126,6 +127,7 @@ function parseAttachmentInput( return { succeeded: true, value: { path, name, size, mediaType, kind } } } +/** Define options to resolve and validate chat attachments with size, count, and path constraints */ export interface ResolveChatAttachmentsOptions { /** The product's workspace/tenant key, passed to `readAttachment`. */ scopeId: string diff --git a/src/chat-routes/sandbox-producer.ts b/src/chat-routes/sandbox-producer.ts index 7469b15..100b898 100644 --- a/src/chat-routes/sandbox-producer.ts +++ b/src/chat-routes/sandbox-producer.ts @@ -62,6 +62,7 @@ export type FilePartPromotionOutcome = | { succeeded: true; part: Record; key?: string } | { succeeded: false; reason: string; part?: Record; key?: string } +/** Define options for producing sandbox chat events with rendering and interaction controls */ export interface SandboxChatProducerOptions { /** The raw sandbox event stream (e.g. `streamSandboxPrompt(...)`). */ events: AsyncIterable @@ -239,6 +240,7 @@ function sandboxStreamFailureDiagnostic(error: unknown): { return { userMessage, failureNote } } +/** Create a sandbox chat producer that manages chat turn routing with logging and interaction rendering options */ export function createSandboxChatProducer(options: SandboxChatProducerOptions): ChatTurnRouteProducer { const log = options.log ?? ((message, meta) => console.error(message, meta ?? '')) const renderable = options.isRenderableInteraction ?? isRenderableInteractionKind diff --git a/src/chat-routes/stale-turn-lock.ts b/src/chat-routes/stale-turn-lock.ts index 02da042..7d1516b 100644 --- a/src/chat-routes/stale-turn-lock.ts +++ b/src/chat-routes/stale-turn-lock.ts @@ -91,6 +91,7 @@ export const DEFAULT_STALE_TURN_LOCK_GRACE_MS = 5 * 60 * 1000 */ export const DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS = 60 * 1000 +/** Resolve options for probing and releasing stale TURN locks based on lock start time and sandbox state */ export interface ReconcileStaleTurnLockOptions { /** When the held lock was acquired (epoch ms). The grace period is measured * from here, so it must be the LOCK's start, not the turn's. */ @@ -127,6 +128,7 @@ export interface ReconcileStaleTurnLockOptions { now?(): number } +/** Describe the outcome of reconciling a stale turn lock including release status and diagnostics */ export interface ReconcileStaleTurnLockResult { released: boolean /** Why the policy decided what it did — the probe's own diagnostics on the diff --git a/src/chat-routes/turn-routes.ts b/src/chat-routes/turn-routes.ts index dcac13f..542f758 100644 --- a/src/chat-routes/turn-routes.ts +++ b/src/chat-routes/turn-routes.ts @@ -116,6 +116,7 @@ export interface ChatTurnRouteProducer extends ChatTurnProducer { model?: string } +/** Resolve authorization status and context for a chat turn including tenant and user identification */ export type ChatTurnAuthorization = | { ok: true @@ -133,6 +134,7 @@ export type ChatTurnAuthorization = } | { ok: false; response: Response } +/** Define arguments required to authorize a chat turn based on intent and request details */ export interface ChatTurnAuthorizeArgs { request: Request intent: 'turn' | 'replay' | 'running' @@ -144,6 +146,7 @@ export interface ChatTurnAuthorizeArgs { threadId?: string } +/** Define the arguments required to produce a chat turn with context and messaging details */ export interface ChatTurnProduceArgs { request: Request body: ChatTurnRequestPayload @@ -218,14 +221,17 @@ interface ChatTurnLifecycleBase { turnStreamId: string context: TContext } +/** Define lifecycle start event with context and timestamp for a chat turn */ export interface ChatTurnLifecycleStart extends ChatTurnLifecycleBase { startedAt: number } +/** Define the structure representing the completion state of a chat turn lifecycle with usage data */ export interface ChatTurnLifecycleComplete extends ChatTurnLifecycleBase { finalText: string usage: ChatTurnUsage durationMs: number } +/** Represent an error occurring during a chat turn lifecycle with context and duration information */ export interface ChatTurnLifecycleError extends ChatTurnLifecycleBase { error: unknown durationMs: number @@ -243,6 +249,7 @@ export interface ChatTurnLifecycle { onTurnError?(info: ChatTurnLifecycleError): void | Promise } +/** Define options to configure chat turn routes including authorization, storage, and event buffering */ export interface CreateChatTurnRoutesOptions { /** Names the product in `deriveExecutionId` so retries land on the same * substrate execution. */ @@ -323,6 +330,7 @@ export interface CreateChatTurnRoutesOptions { log?: (message: string, meta?: Record) => void } +/** Define routes to run, replay, and list running chat turns with streaming and reconnect support */ export interface ChatTurnRoutes { /** POST — run one turn, streaming NDJSON. First line is * `{type:'turn', turnId}` (the replay handle); the rest is the engine's @@ -479,6 +487,7 @@ async function* withStreamHeartbeat( // ── the factory ──────────────────────────────────────────────────────────── +/** Build chat turn routes to handle and validate incoming chat requests with optional logging */ export function createChatTurnRoutes( options: CreateChatTurnRoutesOptions, ): ChatTurnRoutes { diff --git a/src/chat-routes/upload.ts b/src/chat-routes/upload.ts index 1bcca3f..0c00d0c 100644 --- a/src/chat-routes/upload.ts +++ b/src/chat-routes/upload.ts @@ -41,6 +41,7 @@ export interface SandboxUploadSink { write(path: string, content: string, options?: { encoding?: 'utf8' | 'base64' }): Promise } +/** Resolve upload authorization status and provide upload destination or error response */ export type UploadAuthorization = | { ok: true @@ -52,6 +53,7 @@ export type UploadAuthorization = } | { ok: false; response: Response } +/** Define options to authorize uploads and configure file size limits and upload directory */ export interface CreateUploadRouteOptions { /** Authenticate the caller and resolve the sandbox file sink (usually * `ensureWorkspaceSandbox(...)` → `box.fs`). */ @@ -85,6 +87,7 @@ export function sanitizeUploadFilename(name: string): string { const BASE64_CHUNK = 0x8000 +/** Convert a Uint8Array of bytes into a base64-encoded string */ export function bytesToBase64(bytes: Uint8Array): string { let binary = '' for (let offset = 0; offset < bytes.length; offset += BASE64_CHUNK) { @@ -97,6 +100,7 @@ function uploadError(status: number, code: string, error: string): Response { return Response.json({ code, error }, { status }) } +/** Create an upload route handler that authorizes requests and processes file uploads with size limits */ export function createUploadRoute(options: CreateUploadRouteOptions): (request: Request) => Promise { const inlineMaxBytes = options.inlineMaxBytes ?? UPLOAD_INLINE_MAX_BYTES const maxFileBytes = options.maxFileBytes ?? UPLOAD_MAX_FILE_BYTES diff --git a/src/chat-routes/wire.ts b/src/chat-routes/wire.ts index 63aed02..2ac9e5c 100644 --- a/src/chat-routes/wire.ts +++ b/src/chat-routes/wire.ts @@ -27,20 +27,24 @@ export interface ChatTurnFilePartInput { content?: string } +/** Resolve input as either a text part or a file part of a chat turn */ export type ChatTurnPartInput = ChatTurnTextPartInput | ChatTurnFilePartInput // ── producer stream vocabulary ─────────────────────────────────────────────── +/** Represent a text event produced by a source with a fixed type and associated text content */ export interface ProducerTextEvent { type: 'text' text: string } +/** Define an event representing reasoning output with a fixed type and associated text */ export interface ProducerReasoningEvent { type: 'reasoning' text: string } +/** Represent an event triggered by a producer tool call with its identifier, name, and arguments */ export interface ProducerToolCallEvent { type: 'tool_call' call: { @@ -50,6 +54,7 @@ export interface ProducerToolCallEvent { } } +/** Describe the structure of an event representing the result of a producer tool call */ export interface ProducerToolResultEvent { type: 'tool_result' toolCallId: string @@ -61,6 +66,7 @@ export interface ProducerToolResultEvent { } } +/** Describe usage event with prompt and completion token counts for a producer */ export interface ProducerUsageEvent { type: 'usage' usage: { @@ -69,6 +75,7 @@ export interface ProducerUsageEvent { } } +/** Define the structure for a producer notice event with type, id, kind, and text fields */ export interface ProducerNoticeEvent { type: 'notice' id: string @@ -77,6 +84,7 @@ export interface ProducerNoticeEvent { text: string } +/** Represent an error event emitted by a producer containing message, code, and optional details */ export interface ProducerErrorEvent { type: 'error' data: { @@ -100,6 +108,7 @@ export type ProducerPassthroughEventType = | 'session.run.failed' | 'turn_status' +/** Define an event carrying passthrough data with flexible properties for producer communication */ export interface ProducerPassthroughEvent { type: ProducerPassthroughEventType data?: Record @@ -107,6 +116,7 @@ export interface ProducerPassthroughEvent { [key: string]: unknown } +/** Represent events emitted by a producer during its operation for processing and handling */ export type ProducerWireEvent = | ProducerTextEvent | ProducerReasoningEvent @@ -189,6 +199,7 @@ export function chatTurnRequestInit(payload: ChatTurnRequestPayload): RequestIni // (same fail-loud-at-the-choke-point style as /sandbox's provision-payload and // env-size gates). +/** Define the maximum byte size allowed for inline parts in data processing */ export const INLINE_PARTS_MAX_BYTES = 950_000 // ── dispatch (parts[]) budget vocabulary ──────────────────────────────────── @@ -253,6 +264,7 @@ export function formatBytes(bytes: number): string { return `${Math.round(bytes / 1024)}KB` } +/** Represent errors for invalid chat turn inputs with status and code properties */ export class ChatTurnInputError extends Error { constructor(message: string, readonly status = 400, readonly code = 'INVALID_CHAT_TURN') { super(message) @@ -269,6 +281,7 @@ function partByteSize(part: ChatTurnPartInput): number { return bytes } +/** Calculate the total byte size of an array of chat turn parts */ export function promptPartsByteSize(parts: ChatTurnPartInput[]): number { return parts.reduce((total, part) => total + partByteSize(part), 0) } @@ -347,6 +360,7 @@ export function mentionKindForPath(path: string): ChatMentionKind { return mediaTypeForMentionPath(path) ? 'image' : 'file' } +/** Define options to resolve mention paths when converting file mentions to parts */ export interface FileMentionsToPartsOptions { /** Resolve a mention's workspace-relative path to the absolute path the * dispatched part should carry (e.g. a host prefixing the in-box vault @@ -408,6 +422,7 @@ const MAX_MENTION_NAME_LENGTH = 256 /** Longest mention path accepted. */ const MAX_MENTION_PATH_LENGTH = 1024 +/** Represent the result of a sandbox mention path check indicating success or failure with an error message */ export type SandboxMentionPathCheck = | { succeeded: true } | { succeeded: false; error: string } diff --git a/src/chat-store/parts.ts b/src/chat-store/parts.ts index bd34a15..14f2fab 100644 --- a/src/chat-store/parts.ts +++ b/src/chat-store/parts.ts @@ -89,6 +89,7 @@ export interface ChatTextPart { id?: string } +/** Define a reasoning part of a chat with text content and optional metadata fields */ export interface ChatReasoningPart { type: 'reasoning' text: string @@ -101,6 +102,7 @@ export interface ChatReasoningPart { * terminal form `/stream`'s `normalizePersistedPart` settles on. */ export type ChatToolStatus = 'pending' | 'running' | 'completed' | 'error' | 'failed' +/** Describe the current state and data of a chat tool including status, input, output, and metadata */ export interface ChatToolState { status: ChatToolStatus input?: unknown @@ -111,6 +113,7 @@ export interface ChatToolState { time?: ChatPartTime } +/** Define a chat component representing a tool with its state and optional call identifier */ export interface ChatToolPart { type: 'tool' id: string @@ -135,6 +138,7 @@ export interface ChatFilePart { content?: string } +/** Define properties for an image part within a chat message including optional metadata fields */ export interface ChatImagePart { type: 'image' filename?: string @@ -144,6 +148,7 @@ export interface ChatImagePart { path?: string } +/** Define a subtask part of a chat with prompt, description, agent, and optional identifier */ export interface ChatSubtaskPart { type: 'subtask' prompt: string @@ -172,6 +177,7 @@ export interface ChatUsageTokens { } } +/** Define a chat step finish part indicating completion with optional reason, tokens, and cost */ export interface ChatStepFinishPart { type: 'step-finish' reason?: string @@ -193,6 +199,7 @@ export interface ChatInteractionPart { cancelReason?: string } +/** Resolve a chat plan part by aliasing it to the persisted chat plan part type */ export type ChatPlanPart = ChatPlanPersistedPart /** Persisted one-line transcript notice — byte-matches `noticePart` in @@ -236,6 +243,7 @@ type _StoredNoticePartFeedsCodec = MutuallyAssignable type _StoredPlanPartFeedsCodec = MutuallyAssignable +/** Represent parts of a chat message including text, reasoning, tools, files, images, subtasks, steps, interactions, notices, plans, and mentions */ export type ChatMessagePart = | ChatTextPart | ChatReasoningPart @@ -322,22 +330,27 @@ function toChatMessagePart(part: Record): ChatMessagePart | nul } } +/** Resolve whether a ChatMessagePart is specifically a ChatToolPart based on its type property */ export function isChatToolPart(part: ChatMessagePart): part is ChatToolPart { return part.type === 'tool' } +/** Resolve whether a chat message part is a text part based on its type property */ export function isChatTextPart(part: ChatMessagePart): part is ChatTextPart { return part.type === 'text' } +/** Resolve whether a ChatMessagePart is a ChatInteractionPart based on its type property */ export function isChatInteractionPart(part: ChatMessagePart): part is ChatInteractionPart { return part.type === 'interaction' } +/** Resolve whether a chat message part is a persisted chat plan part */ export function isChatPlanPart(part: ChatMessagePart): part is ChatPlanPart { return part.type === 'plan' } +/** Determine if a chat message part represents the completion of a chat step */ export function isChatStepFinishPart(part: ChatMessagePart): part is ChatStepFinishPart { return part.type === 'step-finish' } diff --git a/src/chat-store/schema.ts b/src/chat-store/schema.ts index b4b624e..97e4455 100644 --- a/src/chat-store/schema.ts +++ b/src/chat-store/schema.ts @@ -46,6 +46,7 @@ import type { ChatMessagePart } from './parts' /** A product table referenced by FK — only the `id` column is touched. */ export type ChatParentTable = AnySQLiteTable & { id: AnySQLiteColumn } +/** Define options to customize chat thread and message table creation including workspace and naming prefixes */ export interface CreateChatTablesOptions< TThreadExtras extends Record = {}, TMessageExtras extends Record = {}, @@ -73,6 +74,7 @@ const createdAt = () => integer('created_at', { mode: 'timestamp' }).notNull().d const updatedAt = () => integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`) +/** Build chat-related SQLite tables with customizable thread and message columns */ export function createChatTables< TThreadExtras extends Record = {}, TMessageExtras extends Record = {}, @@ -135,7 +137,11 @@ export function createChatTables< */ export type ChatTables = ReturnType> +/** Resolve the selected fields of a chat thread row from the chat threads table */ export type ChatThreadRow = ChatTables['threads']['$inferSelect'] +/** Resolve the selected structure of a chat message row from the messages table */ export type ChatMessageRow = ChatTables['messages']['$inferSelect'] +/** Resolve the type for inserting a new chat thread row into the threads table */ export type NewChatThreadRow = ChatTables['threads']['$inferInsert'] +/** Resolve the type for inserting a new chat message row into the messages table */ export type NewChatMessageRow = ChatTables['messages']['$inferInsert'] diff --git a/src/chat-store/store.ts b/src/chat-store/store.ts index 5c1a5b3..4ea80a0 100644 --- a/src/chat-store/store.ts +++ b/src/chat-store/store.ts @@ -33,6 +33,7 @@ export type ChatDatabase = BaseSQLiteDatabase<'sync' | 'async', any, any> & { * users or roles itself. */ export type WorkspaceAccessCheck = (workspaceId: string) => void | Promise +/** Define input parameters for listing threads within a workspace with pagination options */ export interface ListThreadsInput { workspaceId: string /** Clamped to 1..200; default 50 (legal's list route semantics). */ @@ -41,6 +42,7 @@ export interface ListThreadsInput { offset?: number } +/** Represent a paginated collection of chat threads with total count and pagination details */ export interface ListThreadsResult { threads: TThread[] total: number @@ -48,6 +50,7 @@ export interface ListThreadsResult { offset: number } +/** Define input parameters required to create a new thread in a workspace */ export interface CreateThreadInput { workspaceId: string /** Title source when `title` is absent: first non-empty line, 80-char cap @@ -63,6 +66,7 @@ export interface CreateThreadInput { extras?: Record } +/** Define input parameters for appending a message to a chat thread with optional metadata */ export interface AppendMessageInput { threadId: string role: 'user' | 'assistant' | 'system' | 'tool' @@ -80,17 +84,20 @@ export interface AppendMessageInput { extras?: Record } +/** Define options to configure message listing with optional limit and offset parameters */ export interface ListMessagesOptions { limit?: number offset?: number } +/** Define input for bulk deleting threads with access checks per workspace */ export interface BulkDeleteThreadsInput { ids: string[] /** Called once per distinct workspace the ids touch, before ANY delete. */ assertAccess: WorkspaceAccessCheck } +/** Manage chat threads and messages with operations for listing, creating, updating, and deleting data */ export interface ChatStore { listThreads(input: ListThreadsInput): Promise> getThread(threadId: string): Promise @@ -135,6 +142,7 @@ function clampOffset(offset: number | undefined): number { return Math.max(value, 0) } +/** Create a chat store managing threads and messages based on the provided database and tables */ export function createChatStore( db: ChatDatabase, tables: TTables, diff --git a/src/design-canvas-react/components/layer-tree.ts b/src/design-canvas-react/components/layer-tree.ts index b4ec446..6e3d2dd 100644 --- a/src/design-canvas-react/components/layer-tree.ts +++ b/src/design-canvas-react/components/layer-tree.ts @@ -6,6 +6,7 @@ import type { SceneElement, ScenePage } from '../../design-canvas/model' +/** Describe a layer row with its element, depth, grouping, ownership, and parent group details */ export interface LayerRow { element: SceneElement depth: number diff --git a/src/design-canvas-react/components/ruler-math.ts b/src/design-canvas-react/components/ruler-math.ts index 3505273..79b52e7 100644 --- a/src/design-canvas-react/components/ruler-math.ts +++ b/src/design-canvas-react/components/ruler-math.ts @@ -13,6 +13,7 @@ * values (10, 50, 100, 500…) are always available as label boundaries. */ const TICK_STEP_CANDIDATES_PX = [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000] as const +/** Define spacing and visibility rules for major and minor ticks in a coordinate system */ export interface TickStep { /** Document-coordinate step between major ticks. */ major: number @@ -58,6 +59,7 @@ export function selectTickStep(input: { return { major, minor, drawMinor } } +/** Define a ruler tick with a position and optional label for measurement markings */ export interface RulerTick { /** Position in document coordinates. */ position: number diff --git a/src/design-canvas-react/components/transform-math.ts b/src/design-canvas-react/components/transform-math.ts index c2906e9..a0f2f20 100644 --- a/src/design-canvas-react/components/transform-math.ts +++ b/src/design-canvas-react/components/transform-math.ts @@ -25,6 +25,7 @@ export interface TransformerNode { rotation: number } +/** Define baked node attributes including position, size, and rotation with collapsed scale */ export interface BakedNodeAttrs { x: number y: number diff --git a/src/design-canvas-react/contracts.ts b/src/design-canvas-react/contracts.ts index e0943e9..481a014 100644 --- a/src/design-canvas-react/contracts.ts +++ b/src/design-canvas-react/contracts.ts @@ -19,6 +19,7 @@ import type { CanvasRenderPalette } from '../theme/theme' // Engine: state + command stack // --------------------------------------------------------------------------- +/** Define the state of the editor scene including document, view settings, and selection details */ export interface EditorSceneState { document: SceneDocument activePageId: string @@ -35,6 +36,7 @@ export interface EditorSceneState { showBleed: boolean } +/** Define a command with execution, undo, and operation methods for scene editing and persistence */ export interface SceneCommand { label: string execute(state: EditorSceneState): EditorSceneState @@ -49,6 +51,7 @@ export interface SceneCommand { inverseOperations(): SceneOperation[] } +/** Manage and track scene commands with undo, redo, and state subscription capabilities */ export interface SceneCommandStack { execute(command: SceneCommand): void /** Apply the top-of-done-stack inverse and return the command (callers use @@ -88,19 +91,23 @@ export interface SceneCommandStack { // Engine: snapping // --------------------------------------------------------------------------- +/** Define snap target categories for aligning elements within a layout system */ export type SnapTargetKind = 'grid' | 'element-edge' | 'element-center' | 'page-edge' | 'page-center' | 'guide' +/** Define a target position and kind for snapping elements on a page */ export interface SnapTarget { /** Page-coordinate position of the snap line. */ position: number kind: SnapTargetKind } +/** Define vertical and horizontal collections of snap targets for alignment purposes */ export interface SnapTargets { vertical: SnapTarget[] horizontal: SnapTarget[] } +/** Define the result of a snap operation including coordinates and active snap lines */ export interface SnapResult { x: number y: number @@ -109,6 +116,7 @@ export interface SnapResult { activeHorizontal: SnapTarget | null } +/** Resolve snapping targets and apply snapping logic to moving elements within the editor scene */ export interface SnapEngine { /** Collect targets for a gesture: other elements' edges/centers, page * edges/center, saved guides, and grid lines when enabled. `excludeIds` @@ -122,6 +130,7 @@ export interface SnapEngine { // Engine: zoom + pan // --------------------------------------------------------------------------- +/** Define methods and properties to calculate zoom and pan transformations between document and screen coordinates */ export interface ZoomPanMath { minZoom: number maxZoom: number @@ -138,6 +147,7 @@ export interface ZoomPanMath { // Components: the editor's public props // --------------------------------------------------------------------------- +/** Resolve the result of applying a scene update including revision and optional normalized document */ export interface ApplySceneResult { rev: number /** Present when the server re-minted ids or normalized the document; the @@ -171,6 +181,7 @@ export interface ExportTriggerOptions { */ export type DesignCanvasMode = 'edit' | 'review' +/** Define properties and callbacks for configuring and controlling the design canvas editor */ export interface DesignCanvasProps { document: SceneDocument /** Revision the document was loaded at; threaded through saves. */ diff --git a/src/design-canvas-react/engine/command-stack.ts b/src/design-canvas-react/engine/command-stack.ts index 5a341bf..e772038 100644 --- a/src/design-canvas-react/engine/command-stack.ts +++ b/src/design-canvas-react/engine/command-stack.ts @@ -43,6 +43,7 @@ export interface SceneCommandStackWithReapply extends SceneCommandStack { reundo(command: SceneCommand): void } +/** Create a command stack for scene editing with reapply capabilities based on the given document and page ID */ export function createSceneCommandStack(document: SceneDocument, activePageId: string): SceneCommandStackWithReapply { let state: EditorSceneState = { document, diff --git a/src/design-canvas-react/engine/commands.ts b/src/design-canvas-react/engine/commands.ts index 9a27918..fb06272 100644 --- a/src/design-canvas-react/engine/commands.ts +++ b/src/design-canvas-react/engine/commands.ts @@ -43,6 +43,7 @@ function applyOp(state: EditorSceneState, op: SceneOperation): EditorSceneState // add_element / inverse = delete_element // --------------------------------------------------------------------------- +/** Define input parameters for adding a scene element with optional index and parent group ID */ export interface AddElementInput { pageId: string element: SceneElement @@ -52,6 +53,7 @@ export interface AddElementInput { parentGroupId?: string } +/** Create a command to add an element to a scene with optional positioning and grouping */ export function addElementCommand(input: AddElementInput): SceneCommand { const addOp: SceneOperation = { type: 'add_element', @@ -79,6 +81,7 @@ export function addElementCommand(input: AddElementInput): SceneCommand { // set_attrs — THE gesture command (one undo step per drag/transform) // --------------------------------------------------------------------------- +/** Define input parameters for setting element attributes within a specific page context */ export interface SetAttrsInput { pageId: string elementId: string @@ -88,6 +91,7 @@ export interface SetAttrsInput { priorAttrs: SceneAttrsPatch } +/** Create a command to set attributes on a scene element with undo capability */ export function setAttrsCommand(input: SetAttrsInput): SceneCommand { const forwardOp: SceneOperation = { type: 'set_attrs', @@ -115,6 +119,7 @@ export function setAttrsCommand(input: SetAttrsInput): SceneCommand { // multi-select set_attrs — N set_attrs ops, one undo step // --------------------------------------------------------------------------- +/** Define an entry linking page and element IDs with current and prior scene attribute patches */ export interface MultiSetAttrsEntry { pageId: string elementId: string @@ -122,6 +127,7 @@ export interface MultiSetAttrsEntry { priorAttrs: SceneAttrsPatch } +/** Build a scene command to set multiple attributes on elements across pages */ export function multiSetAttrsCommand(entries: MultiSetAttrsEntry[]): SceneCommand { if (entries.length === 0) throw new Error('multiSetAttrsCommand: entries must not be empty') @@ -151,12 +157,14 @@ export function multiSetAttrsCommand(entries: MultiSetAttrsEntry[]): SceneComman // reorder_element // --------------------------------------------------------------------------- +/** Define input parameters to reorder an element within a page */ export interface ReorderElementInput { pageId: string elementId: string toIndex: number } +/** Resolve a command to reorder an element within a scene by moving it to a specified index */ export function reorderElementCommand(input: ReorderElementInput): SceneCommand { // Capture the element's current index at construction for the inverse let capturedFromIndex: number | null = null @@ -210,12 +218,14 @@ export function reorderElementCommand(input: ReorderElementInput): SceneCommand // delete_element / inverse = add_element (full snapshot + index + parent) // --------------------------------------------------------------------------- +/** Define input parameters required to delete an element from a specific page in a document */ export interface DeleteElementInput { document: SceneDocument pageId: string elementId: string } +/** Resolve a command to delete an element from a specified page in the document */ export function deleteElementCommand(input: DeleteElementInput): SceneCommand { const page = requirePage(input.document, input.pageId) const { element, owner, index } = requireElement(page, input.elementId) @@ -273,6 +283,7 @@ function findGroupWithChildren(elements: SceneElement[], target: SceneElement[]) // group_elements / inverse = ungroup_element // --------------------------------------------------------------------------- +/** Define input parameters for grouping elements within a scene document on a specific page */ export interface GroupElementsInput { document: SceneDocument pageId: string @@ -281,6 +292,7 @@ export interface GroupElementsInput { name?: string } +/** Create a command to group multiple elements into a single group within a scene */ export function groupElementsCommand(input: GroupElementsInput): SceneCommand { if (input.elementIds.length < 2) { throw new Error('groupElementsCommand: requires ≥ 2 elementIds') @@ -321,12 +333,14 @@ export function groupElementsCommand(input: GroupElementsInput): SceneCommand { // ungroup_element / inverse = group_elements (re-using original ids) // --------------------------------------------------------------------------- +/** Define input parameters required to ungroup elements within a specific page and group */ export interface UngroupElementInput { document: SceneDocument pageId: string groupId: string } +/** Resolve a command to ungroup a group element into its child elements within a scene */ export function ungroupElementCommand(input: UngroupElementInput): SceneCommand { const page = requirePage(input.document, input.pageId) const { element } = requireElement(page, input.groupId) @@ -367,12 +381,14 @@ export function ungroupElementCommand(input: UngroupElementInput): SceneCommand // Page commands // --------------------------------------------------------------------------- +/** Define input parameters for adding a new page with optional settings and position index */ export interface AddPageInput { pageId: string options?: import('../../design-canvas/model').NewPageOptions index?: number } +/** Create a command to add a page with optional settings and index in the scene */ export function addPageCommand(input: AddPageInput): SceneCommand { const addOp: SceneOperation = { type: 'add_page', @@ -399,6 +415,7 @@ export function addPageCommand(input: AddPageInput): SceneCommand { } } +/** Define input parameters required to duplicate a page within a scene document */ export interface DuplicatePageInput { document: SceneDocument sourcePageId: string @@ -406,6 +423,7 @@ export interface DuplicatePageInput { pageId: string } +/** Create a command to duplicate a page and prepare its deletion operation in the scene */ export function duplicatePageCommand(input: DuplicatePageInput): SceneCommand { requirePage(input.document, input.sourcePageId) @@ -432,11 +450,13 @@ export function duplicatePageCommand(input: DuplicatePageInput): SceneCommand { } } +/** Define input parameters required to delete a page from a scene document */ export interface DeletePageInput { document: SceneDocument pageId: string } +/** Delete a page from a document ensuring it is not the last remaining page */ export function deletePageCommand(input: DeletePageInput): SceneCommand { if (input.document.pages.length <= 1) { throw new Error('deletePageCommand: cannot delete the last page') @@ -501,11 +521,13 @@ export function deletePageCommand(input: DeletePageInput): SceneCommand { } } +/** Define input parameters to reorder a page by specifying its ID and target index */ export interface ReorderPageInput { pageId: string toIndex: number } +/** Create a command to reorder a page to a specified index within a scene */ export function reorderPageCommand(input: ReorderPageInput): SceneCommand { let capturedFromIndex: number | null = null @@ -541,6 +563,7 @@ export function reorderPageCommand(input: ReorderPageInput): SceneCommand { } } +/** Define input parameters for setting properties on a specific page within a scene document */ export interface SetPagePropsInput { document: SceneDocument pageId: string @@ -553,6 +576,7 @@ export interface SetPagePropsInput { } } +/** Build a command to update page properties based on the provided input */ export function setPagePropsCommand(input: SetPagePropsInput): SceneCommand { const page = requirePage(input.document, input.pageId) const prior: NonNullable = { @@ -580,12 +604,14 @@ export function setPagePropsCommand(input: SetPagePropsInput): SceneCommand { } } +/** Define input parameters for setting guides on a specific page within a document */ export interface SetPageGuidesInput { document: SceneDocument pageId: string guides: import('../../design-canvas/model').PageGuides } +/** Create a command to update page guides with undo support */ export function setPageGuidesCommand(input: SetPageGuidesInput): SceneCommand { const page = requirePage(input.document, input.pageId) const priorGuides = structuredClone(page.guides) @@ -614,6 +640,7 @@ export function setPageGuidesCommand(input: SetPageGuidesInput): SceneCommand { // bind_slot // --------------------------------------------------------------------------- +/** Define input parameters for binding a slot within a scene document element */ export interface BindSlotInput { document: SceneDocument pageId: string @@ -621,6 +648,7 @@ export interface BindSlotInput { slot: string | null } +/** Bind a slot to an element within a page and generate the corresponding scene command */ export function bindSlotCommand(input: BindSlotInput): SceneCommand { const page = requirePage(input.document, input.pageId) const { element } = requireElement(page, input.elementId) @@ -652,11 +680,13 @@ export function bindSlotCommand(input: BindSlotInput): SceneCommand { // set_document_title // --------------------------------------------------------------------------- +/** Define input parameters for setting the title of a scene document */ export interface SetDocumentTitleInput { document: SceneDocument title: string } +/** Resolve a command to rename a document title with undo and redo operations */ export function setDocumentTitleCommand(input: SetDocumentTitleInput): SceneCommand { const priorTitle = input.document.title diff --git a/src/design-canvas-react/engine/selection.ts b/src/design-canvas-react/engine/selection.ts index c05e15c..1f1fd04 100644 --- a/src/design-canvas-react/engine/selection.ts +++ b/src/design-canvas-react/engine/selection.ts @@ -62,6 +62,7 @@ function pointInBounds(b: Bounds, x: number, y: number): boolean { return x >= b.x && x <= b.x + b.width && y >= b.y && y <= b.y + b.height } +/** Define options to configure marquee selection behavior including containment requirements */ export interface MarqueeSelectOptions { /** When true, the element's AABB must be fully inside the marquee; default is * intersection (any overlap selects). */ @@ -120,6 +121,7 @@ function boundsContain(outer: Bounds, inner: Bounds): boolean { const NUDGE_NORMAL_PX = 1 const NUDGE_SHIFT_PX = 10 +/** Represent horizontal and vertical displacement values for nudging elements */ export interface NudgeDelta { dx: number dy: number diff --git a/src/design-canvas-react/engine/snap.ts b/src/design-canvas-react/engine/snap.ts index 46d9c72..baa1abc 100644 --- a/src/design-canvas-react/engine/snap.ts +++ b/src/design-canvas-react/engine/snap.ts @@ -26,6 +26,7 @@ const KIND_PRIORITY: Record = { 'grid': 5, } +/** Build a SnapEngine instance to manage snapping targets and behavior within an editor scene */ export function createSnapEngine(): SnapEngine { return { collectTargets(state: EditorSceneState, excludeIds: string[]): SnapTargets { diff --git a/src/design-canvas-react/engine/zoom-pan.ts b/src/design-canvas-react/engine/zoom-pan.ts index e05f594..ecf2df7 100644 --- a/src/design-canvas-react/engine/zoom-pan.ts +++ b/src/design-canvas-react/engine/zoom-pan.ts @@ -11,11 +11,13 @@ import type { ZoomPanMath } from '../contracts' +/** Define configuration options for minimum and maximum zoom levels in a zoom-pan interface */ export interface ZoomPanConfig { minZoom: number maxZoom: number } +/** Create zoom and pan math utilities enforcing valid zoom range constraints */ export function createZoomPanMath(config: ZoomPanConfig): ZoomPanMath { const { minZoom, maxZoom } = config if (!Number.isFinite(minZoom) || minZoom <= 0) { diff --git a/src/design-canvas-react/export-math.ts b/src/design-canvas-react/export-math.ts index 0b5d8d8..4a8df43 100644 --- a/src/design-canvas-react/export-math.ts +++ b/src/design-canvas-react/export-math.ts @@ -37,6 +37,7 @@ export function isExportHiddenNodeName(name: string): boolean { // Crop rect + pixel ratio resolution // --------------------------------------------------------------------------- +/** Define parameters required to resolve export settings including crop, pixel ratio, type, and quality */ export interface ResolvedExportParams { cropRect: ExportCropRect pixelRatio: number diff --git a/src/design-canvas-react/export.ts b/src/design-canvas-react/export.ts index 2f93ae0..ce500ac 100644 --- a/src/design-canvas-react/export.ts +++ b/src/design-canvas-react/export.ts @@ -59,6 +59,7 @@ interface KonvaStageLike { // Raster export // --------------------------------------------------------------------------- +/** Define options to export a page as a data URL with format, pixel ratio, bleed, and preset settings */ export interface ExportPageDataUrlOptions { format: 'png' | 'jpeg' pixelRatio?: number diff --git a/src/design-canvas/apply.ts b/src/design-canvas/apply.ts index a2e47c9..8539ae1 100644 --- a/src/design-canvas/apply.ts +++ b/src/design-canvas/apply.ts @@ -64,6 +64,7 @@ import { validateSceneOperations } from './validate' // Result types // --------------------------------------------------------------------------- +/** Represent the result of applying changes to a scene as an element, page, or entire document */ export type SceneApplyResult = | { kind: 'element'; pageId: string; element: SceneElement } | { kind: 'page'; page: ScenePage } @@ -73,6 +74,7 @@ export type SceneApplyResult = // Options // --------------------------------------------------------------------------- +/** Resolve element ID conflicts by providing fresh unique identifiers during scene application */ export interface ApplySceneOptions { /** * Provides fresh ids when duplicate_page re-mints element ids. Never called @@ -144,6 +146,7 @@ function isStaleRevError(err: unknown): boolean { return err instanceof Error && /stale rev/i.test(err.message) } +/** Resolve and apply a scene plan to the store with specified actor context and generate results */ export async function storeApplyScenePlan( store: SceneStore, plan: ScenePlan, diff --git a/src/design-canvas/drizzle-store.ts b/src/design-canvas/drizzle-store.ts index ed209d8..d579e4c 100644 --- a/src/design-canvas/drizzle-store.ts +++ b/src/design-canvas/drizzle-store.ts @@ -37,6 +37,7 @@ import type { * and schema generics so better-sqlite3, D1, and libsql handles all fit. */ export type DesignCanvasDatabase = BaseSQLiteDatabase<'sync' | 'async', any, any> +/** Define options for creating a Drizzle scene store including database, tables, and scope */ export interface CreateDrizzleSceneStoreOptions { db: DesignCanvasDatabase tables: DesignCanvasTables @@ -45,6 +46,7 @@ export interface CreateDrizzleSceneStoreOptions { const DEFAULT_LIST_LIMIT = 50 +/** Create a scene store configured with database tables and scoped to a specific document and workspace */ export function createDrizzleSceneStore(options: CreateDrizzleSceneStoreOptions): SceneStore { const { db, tables, scope } = options const { designDocuments, designDecisions, designExports } = tables diff --git a/src/design-canvas/export-presets.ts b/src/design-canvas/export-presets.ts index 8bf6b73..0afebce 100644 --- a/src/design-canvas/export-presets.ts +++ b/src/design-canvas/export-presets.ts @@ -14,6 +14,7 @@ import type { Bounds, PageBleed, ScenePage } from './model' +/** Define size presets with identifiers, labels, categories, and dimensions for various media types */ export interface SizePreset { id: string label: string @@ -22,6 +23,7 @@ export interface SizePreset { height: number } +/** Provide predefined size presets for social, presentation, and print categories */ export const SIZE_PRESETS: readonly SizePreset[] = [ // Social { id: 'instagram-square', label: 'Instagram — Square', category: 'social', width: 1080, height: 1080 }, @@ -42,6 +44,7 @@ export const SIZE_PRESETS: readonly SizePreset[] = [ { id: 'us-letter-portrait', label: 'US Letter Portrait', category: 'print', width: 850, height: 1100 }, ] as const +/** Resolve a size preset by its identifier or return null if not found */ export function findPreset(id: string): SizePreset | null { return SIZE_PRESETS.find((p) => p.id === id) ?? null } @@ -56,6 +59,7 @@ export function matchPreset(width: number, height: number): SizePreset | null { // Export quality presets // --------------------------------------------------------------------------- +/** Define supported image export formats as PNG or JPEG */ export type ExportFormat = 'png' | 'jpeg' /** @@ -78,6 +82,7 @@ export interface ExportPreset { format: ExportFormat } +/** Provide predefined export configurations for various social media and image formats */ export const EXPORT_PRESETS: Record = { 'instagram-square': { name: 'Instagram square (1080×1080)', @@ -133,6 +138,7 @@ export const EXPORT_PRESETS: Record = { // Crop + scale math (pure, no canvas context) // --------------------------------------------------------------------------- +/** Define crop rectangle coordinates and dimensions for exporting content within page bounds */ export interface ExportCropRect { /** Page-coordinate origin. Negative when bleed extends outside page bounds. */ x: number @@ -185,6 +191,7 @@ export function scaleForPreset(preset: ExportPreset, cropRect: ExportCropRect): // Channel-size presets (fixed output resolutions for the export UI) // --------------------------------------------------------------------------- +/** Define a preset configuration for a channel including its id, label, width, and height */ export interface ChannelPreset { id: string label: string @@ -208,6 +215,7 @@ export const CHANNEL_PRESETS: readonly ChannelPreset[] = [ { id: 'a4_print_2480x3508', label: 'A4 Print (2480×3508 · 300 dpi)', width: 2480, height: 3508 }, ] as const +/** Resolve a valid channel preset identifier from the predefined channel presets array */ export type ChannelPresetId = (typeof CHANNEL_PRESETS)[number]['id'] /** Throws when the id is unknown — callers should only pass ids sourced from @@ -226,6 +234,7 @@ export function requireChannelPreset(id: string): ChannelPreset { // Letterbox scale math (page → channel preset, centered contain) // --------------------------------------------------------------------------- +/** Define the pixel ratio and horizontal offset for scaling a Konva stage to a channel preset size */ export interface ChannelScaleResult { /** * Konva stage pixelRatio: the stage logical size stays at page dimensions; diff --git a/src/design-canvas/mcp-entry.ts b/src/design-canvas/mcp-entry.ts index d8598a4..432313e 100644 --- a/src/design-canvas/mcp-entry.ts +++ b/src/design-canvas/mcp-entry.ts @@ -10,9 +10,11 @@ import { buildScopedMcpServerEntry } from '../tools/mcp' import type { AppToolMcpServer, ScopedMcpServerEntryOptions } from '../tools/mcp' +/** Describe the live visual asset editor capabilities for the current design document using CSS pixel coordinates */ export const DEFAULT_DESIGN_CANVAS_MCP_DESCRIPTION = 'Live visual asset editor for the current design document: read scene state, add/move/resize/delete elements, manage pages, bind template slots, apply data, and queue exports. All coordinates are CSS pixels.' +/** Build scoped MCP server entry options for the design canvas environment */ export type BuildDesignCanvasMcpServerEntryOptions = ScopedMcpServerEntryOptions /** Build the `AgentProfileMcpServer`-shaped entry for the design-canvas channel. */ diff --git a/src/design-canvas/mcp-handler.ts b/src/design-canvas/mcp-handler.ts index 00ceaba..9051415 100644 --- a/src/design-canvas/mcp-handler.ts +++ b/src/design-canvas/mcp-handler.ts @@ -20,11 +20,13 @@ import { CANVAS_MCP_TOOLS } from './mcp-tools' import type { DesignCanvasMcpToolEnv } from './mcp-tools' import { createMcpToolHandler } from '../tools/mcp-rpc' +/** Describe design canvas MCP server information including name and version */ export interface DesignCanvasMcpServerInfo { name: string version: string } +/** Define options for creating a design canvas MCP handler including store, ID minting, and optional server info */ export interface CreateDesignCanvasMcpHandlerOptions { /** Already scoped + authorized for one (workspace, document, actor). */ store: SceneStore @@ -35,6 +37,7 @@ export interface CreateDesignCanvasMcpHandlerOptions { serverInfo?: DesignCanvasMcpServerInfo } +/** Create a request handler for the design canvas MCP tool with specified options */ export function createDesignCanvasMcpHandler( opts: CreateDesignCanvasMcpHandlerOptions, ): (request: Request) => Promise { diff --git a/src/design-canvas/mcp-tools.ts b/src/design-canvas/mcp-tools.ts index bc24c98..f974196 100644 --- a/src/design-canvas/mcp-tools.ts +++ b/src/design-canvas/mcp-tools.ts @@ -34,6 +34,7 @@ import type { McpToolDefinition } from '../tools/mcp-rpc' // Tool env // --------------------------------------------------------------------------- +/** Define the environment for MCP tool with a scene store and ID minting function */ export interface DesignCanvasMcpToolEnv { store: SceneStore mintId: () => string @@ -220,6 +221,7 @@ const colorProp = (label: string) => ({ type: 'string', description: `${label} // Tool implementations // --------------------------------------------------------------------------- +/** Provide a collection of MCP tool definitions for manipulating and querying the design canvas environment */ const CANVAS_MCP_TOOLS: McpToolDefinition[] = [ // ─── read ──────────────────────────────────────────────────────────────── @@ -1003,11 +1005,14 @@ const CANVAS_MCP_TOOLS: McpToolDefinition[] = [ export { CANVAS_MCP_TOOLS } +/** Find the canvas MCP tool definition matching the given name or return undefined */ export function findCanvasMcpTool( name: string, ): McpToolDefinition | undefined { return CANVAS_MCP_TOOLS.find((tool) => tool.name === name) } +/** Extract names of all tools from the CANVAS_MCP_TOOLS array */ export const CANVAS_MCP_TOOL_NAMES = CANVAS_MCP_TOOLS.map((t) => t.name) +/** Provide a readonly array of string identifiers representing canvas element kinds */ export const CANVAS_ELEMENT_KINDS: readonly string[] = SCENE_ELEMENT_KINDS diff --git a/src/design-canvas/model.ts b/src/design-canvas/model.ts index 2c0a2a0..e49d2f7 100644 --- a/src/design-canvas/model.ts +++ b/src/design-canvas/model.ts @@ -15,8 +15,10 @@ import { assertMediaUrl } from '../web' +/** Define the current version number of the scene schema */ export const SCENE_SCHEMA_VERSION = 1 +/** Define the structure and properties of a scene document including version, title, pages, settings, and metadata */ export interface SceneDocument { schemaVersion: typeof SCENE_SCHEMA_VERSION title: string @@ -25,6 +27,7 @@ export interface SceneDocument { metadata: Record } +/** Define settings for scene export including print conversion factor for unit calculations */ export interface SceneSettings { /** Print conversion factor for mm↔px math at export; 96 = CSS default. */ dpi: number @@ -45,6 +48,7 @@ export interface PageGuides { horizontal: number[] } +/** Define the structure and properties of a scene page including layout, background, and elements */ export interface ScenePage { id: string name: string @@ -78,6 +82,7 @@ export interface SceneElementBase { slot?: string } +/** Define a rectangular scene element with size, fill, optional stroke, and corner radius properties */ export interface RectElement extends SceneElementBase { kind: 'rect' width: number @@ -88,6 +93,7 @@ export interface RectElement extends SceneElementBase { cornerRadius?: number } +/** Define properties for an ellipse element including dimensions, fill, and optional stroke details */ export interface EllipseElement extends SceneElementBase { kind: 'ellipse' width: number @@ -97,6 +103,7 @@ export interface EllipseElement extends SceneElementBase { strokeWidth?: number } +/** Define a line element with points, stroke, stroke width, and optional dash pattern */ export interface LineElement extends SceneElementBase { kind: 'line' /** Flat [x0, y0, x1, y1, ...] relative to (x, y); ≥ 2 points. */ @@ -106,6 +113,7 @@ export interface LineElement extends SceneElementBase { dash?: number[] } +/** Define properties for a text element including content, style, alignment, and layout parameters */ export interface TextElement extends SceneElementBase { kind: 'text' text: string @@ -120,6 +128,7 @@ export interface TextElement extends SceneElementBase { letterSpacing: number } +/** Define properties for an image element including source, dimensions, and fit mode */ export interface ImageElement extends SceneElementBase { kind: 'image' width: number @@ -141,11 +150,13 @@ export interface VideoElement extends SceneElementBase { posterSrc?: string } +/** Define a group element that contains multiple child scene elements */ export interface GroupElement extends SceneElementBase { kind: 'group' children: SceneElement[] } +/** Represent a graphical element in a scene including shapes, text, media, or groups */ export type SceneElement = | RectElement | EllipseElement @@ -155,8 +166,10 @@ export type SceneElement = | VideoElement | GroupElement +/** Extract the kind property from a SceneElement to identify its element type */ export type SceneElementKind = SceneElement['kind'] +/** Define all valid kinds of scene elements used in the application */ export const SCENE_ELEMENT_KINDS: readonly SceneElementKind[] = [ 'rect', 'ellipse', 'line', 'text', 'image', 'video', 'group', ] as const @@ -165,6 +178,7 @@ export const SCENE_ELEMENT_KINDS: readonly SceneElementKind[] = [ // Geometry // --------------------------------------------------------------------------- +/** Define rectangular boundaries with position and size properties */ export interface Bounds { x: number y: number @@ -214,6 +228,7 @@ export function elementExtent(element: SceneElement): { width: number; height: n } } +/** Estimate the height of multiline text based on font size and line height */ export function estimateTextHeight(element: Pick): number { const lines = element.text.length === 0 ? 1 : element.text.split('\n').length return lines * element.fontSize * element.lineHeight @@ -243,6 +258,7 @@ export function elementAabb(element: SceneElement): Bounds { return { x: element.x + minX, y: element.y + minY, width: maxX - minX, height: maxY - minY } } +/** Determine if two rectangular bounds overlap or intersect each other */ export function boundsIntersect(a: Bounds, b: Bounds): boolean { return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y } @@ -251,6 +267,7 @@ export function boundsIntersect(a: Bounds, b: Bounds): boolean { // Lookup + traversal // --------------------------------------------------------------------------- +/** Resolve and return a page by ID from a document or throw an error if not found */ export function requirePage(document: SceneDocument, pageId: string): ScenePage { const page = document.pages.find((candidate) => candidate.id === pageId) if (!page) throw new Error(`page ${pageId} not found in document`) @@ -273,6 +290,7 @@ export function findElement(page: ScenePage, elementId: string): { element: Scen return null } +/** Resolve and return the element, its owner array, and index from the page by element ID */ export function requireElement(page: ScenePage, elementId: string): { element: SceneElement; owner: SceneElement[]; index: number } { const found = findElement(page, elementId) if (!found) throw new Error(`element ${elementId} not found on page ${page.id}`) @@ -301,6 +319,7 @@ export function collectSlots(document: SceneDocument): Map } +/** Define an operation to set the document title to a specified string */ export interface SetDocumentTitleOperation { type: 'set_document_title' title: string } +/** Represent operations that modify scenes by adding, updating, reordering, grouping, or deleting elements and pages */ export type SceneOperation = | AddElementOperation | SetAttrsOperation @@ -166,13 +181,16 @@ export type SceneOperation = | ApplyDataOperation | SetDocumentTitleOperation +/** Define a plan summarizing a scene with its description and associated operations */ export interface ScenePlan { summary: string operations: SceneOperation[] } +/** Extract the type property from a SceneOperation to represent its operation type */ export type SceneOperationType = SceneOperation['type'] +/** Define all valid operation types for scene manipulation in the application */ export const SCENE_OPERATION_TYPES: readonly SceneOperationType[] = [ 'add_element', 'set_attrs', diff --git a/src/design-canvas/schema.ts b/src/design-canvas/schema.ts index 35b3d05..61ec548 100644 --- a/src/design-canvas/schema.ts +++ b/src/design-canvas/schema.ts @@ -21,6 +21,7 @@ import type { SceneDocument } from './model' /** A product table referenced by FK — only the `id` column is touched. */ export type DesignCanvasParentTable = AnySQLiteTable & { id: AnySQLiteColumn } +/** Define options for creating design canvas tables including workspace and user table configurations */ export interface CreateDesignCanvasTablesOptions { workspaceTable: DesignCanvasParentTable userTable: DesignCanvasParentTable @@ -34,6 +35,7 @@ const createdAt = () => integer('created_at', { mode: 'timestamp' }).notNull().d const updatedAt = () => integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`) +/** Build SQLite tables for design documents with workspace and user references */ export function createDesignCanvasTables(opts: CreateDesignCanvasTablesOptions) { const { workspaceTable, userTable } = opts @@ -88,8 +90,12 @@ export function createDesignCanvasTables(opts: CreateDesignCanvasTablesOptions) return { designDocuments, designDecisions, designExports } } +/** Resolve the structure and data of design canvas tables for rendering and manipulation */ export type DesignCanvasTables = ReturnType +/** Resolve the selected structure of a design document row from design canvas tables */ export type DesignDocumentRow = DesignCanvasTables['designDocuments']['$inferSelect'] +/** Resolve a design decision row from the design decisions table selection */ export type DesignDecisionRow = DesignCanvasTables['designDecisions']['$inferSelect'] +/** Resolve the selected fields of designExports from DesignCanvasTables */ export type DesignExportRow = DesignCanvasTables['designExports']['$inferSelect'] diff --git a/src/design-canvas/store.ts b/src/design-canvas/store.ts index 80ce448..d1239d5 100644 --- a/src/design-canvas/store.ts +++ b/src/design-canvas/store.ts @@ -14,12 +14,14 @@ import type { SceneDocument } from './model' +/** Represent a scene document with its current revision number for version tracking */ export interface SceneDocumentRecord { document: SceneDocument /** Monotonic revision; increments on every successful save. */ rev: number } +/** Define the structure for decisions made within a scene including type, instructions, and metadata */ export interface SceneDecision { id: string kind: 'human_edit' | 'agent_edit' | 'agent_proposal' | 'export' | 'note' @@ -29,6 +31,7 @@ export interface SceneDecision { createdAt: Date } +/** Define the structure for decisions related to creating a new scene with instructions and optional details */ export interface NewSceneDecision { kind: SceneDecision['kind'] instruction: string @@ -36,8 +39,10 @@ export interface NewSceneDecision { metadata?: Record } +/** Define supported formats for exporting a scene including image and JSON options */ export type SceneExportFormat = 'png' | 'jpeg' | 'json' +/** Describe a scene export with its status, format, metadata, and result information */ export interface SceneExportRecord { id: string format: SceneExportFormat @@ -47,6 +52,7 @@ export interface SceneExportRecord { createdAt: Date } +/** Manage scene documents, decisions, and exports with atomic save and revision control */ export interface SceneStore { /** Current document + revision. */ getDocument(): Promise diff --git a/src/design-canvas/templates.ts b/src/design-canvas/templates.ts index 0acd535..b10cfad 100644 --- a/src/design-canvas/templates.ts +++ b/src/design-canvas/templates.ts @@ -27,8 +27,10 @@ import { // Slot surface // --------------------------------------------------------------------------- +/** Define allowed string literals representing different slot fill kinds */ export type SlotFillKind = 'text' | 'src' | 'color' +/** Define a slot template specifying its name, page, element, and fill characteristics */ export interface TemplateSlot { name: string pageId: string @@ -94,6 +96,7 @@ export function validateBindings( // Template instantiation // --------------------------------------------------------------------------- +/** Define options for instantiating a document with title, optional bindings, and custom id minting */ export interface InstantiateOptions { /** Human-readable title for the new document. */ title: string diff --git a/src/design-canvas/validate.ts b/src/design-canvas/validate.ts index 4b98f66..c3ea04c 100644 --- a/src/design-canvas/validate.ts +++ b/src/design-canvas/validate.ts @@ -54,6 +54,7 @@ import type { // Public entry // --------------------------------------------------------------------------- +/** Validate each scene operation against the document and throw detailed errors for invalid operations */ export function validateSceneOperations(document: SceneDocument, operations: SceneOperation[]): void { operations.forEach((operation, index) => { try { @@ -65,6 +66,7 @@ export function validateSceneOperations(document: SceneDocument, operations: Sce }) } +/** Validate a scene operation against the document to ensure it meets required constraints */ export function validateSceneOperation(document: SceneDocument, operation: SceneOperation): void { switch (operation.type) { case 'add_element': diff --git a/src/durable-chat/adapters.ts b/src/durable-chat/adapters.ts index 08c7029..07d59e4 100644 --- a/src/durable-chat/adapters.ts +++ b/src/durable-chat/adapters.ts @@ -30,6 +30,7 @@ import { planToPersistedPart, } from '../plans/index' +/** Define methods to manage durable interaction projections including upsert, cancel, and materialize operations */ export interface DurableInteractionProjectionAdapter { upsertAsk(request: InteractionRequestWire): Promise cancel(cancel: InteractionCancelData): Promise @@ -81,6 +82,7 @@ export function createDurableInteractionProjectionAdapter(options: { } } +/** Resolve chat events and materialize their state into durable records */ export interface DurableChatEventProjection { observe(event: unknown): void | Promise materialize(): Array> | Promise>> @@ -152,6 +154,7 @@ export function createDurableChatEventProjection(options: { } } +/** Define a structured response containing scope, settlement, and intent for durable interactions */ export interface PreparedDurableInteractionAnswer { scope: DurableChatScope settlement: DurableInteractionSettlement @@ -164,6 +167,7 @@ interface DurableInteractionRoutePersistenceBase { now?: () => string } +/** Define options for durable interaction route persistence with reconciliation guarantees and authority functions */ export type CreateDurableInteractionRoutePersistenceOptions = | (DurableInteractionRoutePersistenceBase & { guarantee: 'reconciled' diff --git a/src/durable-chat/errors.ts b/src/durable-chat/errors.ts index 80d32b8..bd5d36a 100644 --- a/src/durable-chat/errors.ts +++ b/src/durable-chat/errors.ts @@ -1,3 +1,4 @@ +/** Define error codes representing possible Durable Chat failure scenarios */ export type DurableChatErrorCode = | 'DURABLE_CHAT_BAD_REQUEST' | 'DURABLE_CHAT_UNAUTHORIZED' @@ -21,6 +22,7 @@ export class DurableChatError extends Error { } } +/** Represent conflict errors occurring in durable chat state management */ export class DurableChatConflictError extends DurableChatError { constructor(message = 'durable chat state conflict', details?: unknown) { super('DURABLE_CHAT_CONFLICT', message, 409, details) @@ -28,6 +30,7 @@ export class DurableChatConflictError extends DurableChatError { } } +/** Represent unavailable durable chat authority errors with status code 503 */ export class DurableChatUnavailableError extends DurableChatError { constructor(message = 'durable chat authority unavailable', details?: unknown) { super('DURABLE_CHAT_UNAVAILABLE', message, 503, details) @@ -35,6 +38,7 @@ export class DurableChatUnavailableError extends DurableChatError { } } +/** Represent durable chat errors indicating the chat plan is no longer available */ export class DurableChatGoneError extends DurableChatError { constructor(message = 'durable chat plan is gone', details?: unknown) { super('DURABLE_CHAT_GONE', message, 410, details) diff --git a/src/durable-chat/interactions.ts b/src/durable-chat/interactions.ts index f7609eb..25bf542 100644 --- a/src/durable-chat/interactions.ts +++ b/src/durable-chat/interactions.ts @@ -120,6 +120,7 @@ export async function recordDurableInteractionAnswer( }) } +/** Define options for creating durable interaction settlement factories including store and optional reconcile authority */ export interface DurableInteractionSettlementFactoryOptions extends DurableInteractionSettlementOptions { store: DurablePlanStore /** Optional authority lookup used by `reconcile`; returning null leaves the @@ -199,6 +200,9 @@ export function durableInteractionIntentKey(scope: DurableChatScope, interaction return intentKey(scope, interactionId, attemptKey) } +/** Resolve and upsert a durable interaction ask in the store with optional event and timing parameters */ export const applyDurableInteractionAsk = upsertDurableInteractionAsk +/** Resolve cancellation of a durable interaction with optional reason and event details */ export const applyDurableInteractionCancel = recordDurableInteractionCancel +/** Resolve and record the outcome and answers of a durable interaction within the given store and scope */ export const applyDurableInteractionAnswer = recordDurableInteractionAnswer diff --git a/src/durable-chat/memory.ts b/src/durable-chat/memory.ts index 0c5f5a8..61b46dd 100644 --- a/src/durable-chat/memory.ts +++ b/src/durable-chat/memory.ts @@ -289,6 +289,7 @@ export class InMemoryDurableChatStateStore implements DurablePlanStore { * store rather than a state store. Both names refer to the same non-production * reference implementation. */ export const InMemoryDurableChatStore = InMemoryDurableChatStateStore +/** Create an in-memory durable chat state store for managing chat session data efficiently */ export function createInMemoryDurableChatStateStore(): InMemoryDurableChatStateStore { return new InMemoryDurableChatStateStore() } diff --git a/src/durable-chat/plan-routes.ts b/src/durable-chat/plan-routes.ts index 5139e5d..431873a 100644 --- a/src/durable-chat/plan-routes.ts +++ b/src/durable-chat/plan-routes.ts @@ -21,6 +21,7 @@ import { } from './types' import { canTransitionPlanStatus, planFollowUpTurnId } from '../plans/index' +/** Resolve authorization status for durable plans using scopes, responses, or nullish values */ export type DurablePlanAuthorization = | DurableChatScope | { scope: DurableChatScope } @@ -28,12 +29,14 @@ export type DurablePlanAuthorization = | null | undefined +/** Define arguments for authorizing durable plan route requests with operation and optional plan ID */ export interface DurablePlanRouteAuthorizeArgs { request: Request operation: 'current' | 'decide' planId?: string } +/** Define options for durable plan routing including store, authority, authorization, and idempotent side effect handling */ export interface DurablePlanRouteOptions { store: DurablePlanStore authority: DurablePlanAuthority @@ -52,6 +55,7 @@ export interface DurablePlanRouteOptions { logger?: Pick } +/** Define routes handling durable plan requests with current and decide methods */ export interface DurablePlanRoutes { current(request: Request): Promise decide(request: Request): Promise @@ -132,6 +136,7 @@ function recoverReceipt( }) } +/** Build durable plan routes with authorization and effect handling based on provided options */ export function createDurablePlanRoutes(options: DurablePlanRouteOptions): DurablePlanRoutes { const now = options.now ?? (() => new Date().toISOString()) const logger = options.logger ?? console diff --git a/src/durable-chat/types.ts b/src/durable-chat/types.ts index a03fe6c..0a58884 100644 --- a/src/durable-chat/types.ts +++ b/src/durable-chat/types.ts @@ -12,17 +12,21 @@ import type { ChatPlan, ChatPlanStatus } from '../plans/index' * an identity or scope from the request body. */ export type DurableChatScope = string & { readonly __durableChatScope: unique symbol } +/** Create a durable chat scope from a non-empty string value */ export function createDurableChatScope(value: string): DurableChatScope { if (typeof value !== 'string' || value.trim() === '') throw new TypeError('durable chat scope must be a non-empty string') return value as DurableChatScope } +/** Resolve a valid durable chat scope key from the given scope input */ export function durableChatScopeKey(scope: DurableChatScope): string { if (typeof scope !== 'string' || scope.length === 0) throw new TypeError('durable chat scope is required') return scope } +/** Represent durable plan outcomes as either approved or rejected */ export type DurablePlanDecision = 'approved' | 'rejected' +/** Resolve durable plan authority decisions including approval, rejection, or predefined durable decisions */ export type DurablePlanAuthorityDecision = DurablePlanDecision | 'approve' | 'reject' /** Projection retained by a durable store. It is intentionally compatible @@ -32,14 +36,17 @@ export type DurablePlanProjection = ChatPlan & { decidedBy?: string } +/** Represent a unique identifier key for durable plan commands */ export type DurablePlanCommandKey = string +/** Define possible states for a durable plan command in its lifecycle */ export type DurablePlanCommandState = | 'claimed' | 'authority_committed' | 'finalized' | 'conflicted' +/** Define the structure for recording durable plan commands with associated metadata and state information */ export interface DurablePlanCommandRecord { scope: DurableChatScope planId: string @@ -54,12 +61,14 @@ export interface DurablePlanCommandRecord { conflict?: string } +/** Represent the current authoritative state and optional receipt of a durable plan authority */ export interface DurablePlanAuthorityCurrentResult { /** Authoritative state. `null` means the authority has forgotten the plan. */ plan: DurablePlanProjection | null receipt?: DurableFollowUpReceipt } +/** Define a durable receipt capturing stable identifiers and state for follow-up decisions */ export interface DurableFollowUpReceipt { /** Stable for a scope + plan + revision + decision. */ receiptId: string @@ -72,6 +81,7 @@ export interface DurableFollowUpReceipt { authorityIdempotencyKey: string } +/** Describe the outcome of an authority's durable plan decision including follow-up and metadata */ export interface DurablePlanAuthorityResult { /** Authority's final plan projection. */ plan: DurablePlanProjection @@ -101,6 +111,7 @@ export interface DurablePlanAuthority { }): Promise } +/** Define the structure for recording the state and metadata of a durable plan effect */ export interface DurablePlanEffectRecord { effectKey: string scope: DurableChatScope @@ -113,6 +124,7 @@ export interface DurablePlanEffectRecord { error?: string } +/** Manage durable storage and retrieval of plan projections, commands, and effects within a scoped context */ export interface DurablePlanStore { getPlanProjection(scope: DurableChatScope, planId: string, revision?: number): Promise putPlanProjection(scope: DurableChatScope, projection: DurablePlanProjection): Promise @@ -151,10 +163,14 @@ export interface DurablePlanStore { /** Alias used by adapters that store all durable chat state in one port. */ export type DurableChatStateStore = DurablePlanStore +/** Represent durable storage for plan state management with persistence and reliability guarantees */ export type DurablePlanStateStore = DurablePlanStore +/** Pick essential methods to manage and record durable plan command operations */ export type DurablePlanCommandJournal = Pick +/** Provide durable methods to manage the lifecycle of answer intents in a plan store */ export type DurableAnswerIntentJournal = Pick +/** Define a durable chat interaction projection with idempotent event tracking and optional tombstone flag */ export interface DurableInteractionProjection extends ChatInteraction { /** Sequence/event identity used to make ask replays idempotent. */ eventId?: string @@ -164,8 +180,10 @@ export interface DurableInteractionProjection extends ChatInteraction { updatedAt?: string } +/** Define possible states for a durable answer intent lifecycle */ export type DurableAnswerIntentState = 'prepared' | 'acknowledged' | 'finalized' | 'aborted' +/** Define the structure for recording durable answer intent details and their states */ export interface DurableAnswerIntentRecord { scope: DurableChatScope interactionId: string @@ -181,6 +199,7 @@ export interface DurableAnswerIntentRecord { error?: string } +/** Represent durable acknowledgement of an interaction with optional authority, status, and timestamp fields */ export interface DurableInteractionAcknowledgement { acknowledged: true authorityId?: string @@ -188,8 +207,10 @@ export interface DurableInteractionAcknowledgement { at?: string } +/** Define interaction durability levels to specify reconciliation or best-effort guarantees */ export type DurableInteractionGuarantee = 'reconciled' | 'best-effort' +/** Define options for durable interaction settlement including attempt key, guarantee, and timestamp provider */ export interface DurableInteractionSettlementOptions { /** Caller-created and stable across retries/reconnects. */ attemptKey: string @@ -197,6 +218,7 @@ export interface DurableInteractionSettlementOptions { now?: () => string } +/** Manage durable interaction lifecycles by preparing, acknowledging, finalizing, aborting, and reconciling intents */ export interface DurableInteractionSettlement { prepare(scope: DurableChatScope, interactionId: string, outcome: 'accepted' | 'declined', data?: Record): Promise acknowledge(scope: DurableChatScope, intentKey: string, acknowledgement?: Omit): Promise @@ -205,24 +227,29 @@ export interface DurableInteractionSettlement { reconcile(scope: DurableChatScope, intentKey: string): Promise } +/** Normalize input value to a standardized DurablePlanDecision or return null for invalid inputs */ export function normalizePlanDecision(value: unknown): DurablePlanDecision | null { if (value === 'approved' || value === 'approve') return 'approved' if (value === 'rejected' || value === 'reject') return 'rejected' return null } +/** Generate a unique key string for a plan command using plan ID, revision, and decision */ export function planCommandKey(planId: string, revision: number, decision: DurablePlanDecision): string { return `plan:${encodeURIComponent(planId)}:${revision}:${decision}` } +/** Generate a unique idempotency key for a plan authority based on scope, plan, revision, and decision */ export function planAuthorityIdempotencyKey(scope: DurableChatScope, planId: string, revision: number, decision: DurablePlanDecision): string { return `durable-plan:${encodeURIComponent(durableChatScopeKey(scope))}:${encodeURIComponent(planId)}:${revision}:${decision}` } +/** Generate a unique string key representing the effect of a plan decision within a given scope and revision */ export function planEffectKey(scope: DurableChatScope, planId: string, revision: number, decision: DurablePlanDecision): string { return `after-decision:${encodeURIComponent(durableChatScopeKey(scope))}:${encodeURIComponent(planId)}:${revision}:${decision}` } +/** Resolve a durable follow-up receipt ensuring idempotency for a given plan decision and revision */ export function stablePlanReceipt( scope: DurableChatScope, planId: string, diff --git a/src/harness/index.ts b/src/harness/index.ts index fa990b9..c341258 100644 --- a/src/harness/index.ts +++ b/src/harness/index.ts @@ -47,12 +47,15 @@ export const KNOWN_HARNESSES = [ 'cli-base', ] as const +/** Resolve a valid harness identifier from the predefined KNOWN_HARNESSES array */ export type Harness = (typeof KNOWN_HARNESSES)[number] +/** Define the default harness to use for code execution and testing environments */ export const DEFAULT_HARNESS: Harness = 'opencode' const HARNESS_SET: ReadonlySet = new Set(KNOWN_HARNESSES) +/** Determine if a value is a recognized harness string identifier */ export function isHarness(value: unknown): value is Harness { return typeof value === 'string' && HARNESS_SET.has(value) } @@ -62,6 +65,7 @@ export function coerceHarness(value: unknown, fallback: Harness = DEFAULT_HARNES return isHarness(value) ? value : fallback } +/** Resolve input options to determine the appropriate session harness to use */ export interface ResolveSessionHarnessInput { /** The harness already locked to this session (recorded at its first turn). */ sessionHarness?: unknown @@ -73,6 +77,7 @@ export interface ResolveSessionHarnessInput { fallback?: Harness } +/** Represent resolved session state including harness, lock status, and swap attempt flag */ export interface ResolvedSessionHarness { /** The harness to actually run — the locked one when the session already has it. */ harness: Harness diff --git a/src/intakes-react/contracts.ts b/src/intakes-react/contracts.ts index c63215c..e336407 100644 --- a/src/intakes-react/contracts.ts +++ b/src/intakes-react/contracts.ts @@ -19,6 +19,7 @@ export interface IntakeView { progress: { answered: number; total: number } } +/** Define properties and callbacks for managing the intake interview flow and user interactions */ export interface IntakeInterviewProps { view: IntakeView /** diff --git a/src/intakes-react/lazy.tsx b/src/intakes-react/lazy.tsx index a1bc9a9..264206a 100644 --- a/src/intakes-react/lazy.tsx +++ b/src/intakes-react/lazy.tsx @@ -10,6 +10,7 @@ import type { IntakeInterviewProps } from './contracts' export type { IntakeInterviewProps } +/** Load IntakeInterview component lazily to optimize initial application rendering */ export const IntakeInterviewLazy = lazy( () => import('./components/IntakeInterview').then((m) => ({ default: m.IntakeInterview })), ) diff --git a/src/intakes/api.ts b/src/intakes/api.ts index 4c6e083..5e0724f 100644 --- a/src/intakes/api.ts +++ b/src/intakes/api.ts @@ -40,6 +40,7 @@ export interface CurrentIntakeView { progress: { answered: number; total: number } } +/** Define configuration options for initializing the intake API with store and graph components */ export interface IntakeApiOptions { store: IntakeStore graph: IntakeGraph diff --git a/src/intakes/drizzle/schema.ts b/src/intakes/drizzle/schema.ts index 83bc912..c605c96 100644 --- a/src/intakes/drizzle/schema.ts +++ b/src/intakes/drizzle/schema.ts @@ -29,6 +29,7 @@ import type { AnySQLiteColumn, AnySQLiteTable } from 'drizzle-orm/sqlite-core' /** A product table referenced by FK — only the `id` column is touched. */ export type IntakeParentTable = AnySQLiteTable & { id: AnySQLiteColumn } +/** Define options for creating intake tables including user and optional workspace references */ export interface CreateIntakeTablesOptions { /** The product's user table — user-intake rows reference `userTable.id`. */ userTable: IntakeParentTable @@ -98,7 +99,9 @@ export function createIntakeTables( return result as IntakeTables } +/** Resolve the structure and data of a user intake table based on the createUserIntakeTable function */ export type UserIntakeTable = ReturnType +/** Resolve the structure and data of the project intake table from the factory function */ export type ProjectIntakeTable = ReturnType /** @@ -113,5 +116,7 @@ export type IntakeTables = /** The union table shape, for code that handles either scope generically. */ export type AnyIntakeTables = { userIntake: UserIntakeTable; projectIntake?: ProjectIntakeTable } +/** Infer and represent a selected row from the UserIntakeTable data structure */ export type UserIntakeRow = UserIntakeTable['$inferSelect'] +/** Resolve the selected data structure for a project intake table row */ export type ProjectIntakeRow = ProjectIntakeTable['$inferSelect'] diff --git a/src/intakes/drizzle/store.ts b/src/intakes/drizzle/store.ts index b2709b4..5f25a5a 100644 --- a/src/intakes/drizzle/store.ts +++ b/src/intakes/drizzle/store.ts @@ -50,6 +50,7 @@ export interface IntakeState { completedAt: Date | null } +/** Define error codes representing specific intake validation failures */ export type IntakeErrorCode = 'invalid-answer' | 'unknown-question' | 'incomplete' | 'stale-graph' /** Thrown by store mutations on a refused write — callers map it to a 4xx. */ @@ -172,6 +173,7 @@ function createScopedStore(opts: ScopedStoreOptions): IntakeStore { return { get, save, complete } } +/** Define options required to create a user intake store for onboarding data collection */ export interface CreateUserIntakeStoreOptions { db: IntakeDatabase /** The user-intake table from createIntakeTables. */ @@ -194,6 +196,7 @@ export function createUserIntakeStore(opts: CreateUserIntakeStoreOptions): Intak }) } +/** Define options required to create a project intake store including database, table, graph, and workspace ID */ export interface CreateProjectIntakeStoreOptions { db: IntakeDatabase /** The project-intake table from createIntakeTables (workspace scope). */ diff --git a/src/intakes/model.ts b/src/intakes/model.ts index 183e3ed..9258201 100644 --- a/src/intakes/model.ts +++ b/src/intakes/model.ts @@ -96,6 +96,7 @@ export type AnswerRejectionReason = | 'invalid-email' | 'unknown-question' +/** Describe validation outcome of an answer including success status and optional rejection reason */ export interface AnswerValidationResult { ok: boolean reason?: AnswerRejectionReason diff --git a/src/integrations/index.ts b/src/integrations/index.ts index 4946c7e..9a09d2b 100644 --- a/src/integrations/index.ts +++ b/src/integrations/index.ts @@ -29,6 +29,7 @@ export type HubExecResult = | { succeeded: true; result: unknown } | { succeeded: false; code: HubExecErrorCode; message: string; approval?: unknown } +/** Define configuration options for initializing a Hub execution client */ export interface HubExecClientOptions { /** Platform base URL (e.g. `TANGLE_PLATFORM_URL`). */ baseUrl: string @@ -116,16 +117,19 @@ export class HubExecClient { } } +/** Define input parameters for invoking a hub tool with user ID, tool name, and optional arguments */ export interface HubInvokeInput { userId: string /** The MCP tool name the agent called (`int___`). */ toolName: string args?: Record } +/** Describe the outcome of a hub invocation including status and response body */ export interface HubInvokeOutcome { status: number body: Record } +/** Define dependencies for invoking hub operations including API key resolution and optional configuration */ export interface HubInvokeDeps { /** Resolve the user's Tangle API key (the hub principal bearer). Required — * the product binds its own session-key resolver. Null → user not linked. */ diff --git a/src/interactions/contract.ts b/src/interactions/contract.ts index 2bd9da6..5f4e269 100644 --- a/src/interactions/contract.ts +++ b/src/interactions/contract.ts @@ -35,6 +35,7 @@ export const INTERACTION_RESOLVED_EVENT = 'interaction.resolved' as const * A pure default; a product may substitute its own renderable set. */ const RENDERABLE_INTERACTION_KINDS: ReadonlySet = new Set(['question', 'plan']) +/** Resolve if the given interaction kind is renderable within the application context */ export function isRenderableInteractionKind(kind: string): boolean { return RENDERABLE_INTERACTION_KINDS.has(kind) } @@ -54,9 +55,11 @@ export function isSafeInteractionFieldKey(key: string): boolean { // its write-in input, and `parseInteractionRequest` returns the RAW payload // (schema-validated, not schema-parsed) so the flag survives. +/** Extract select-type interaction fields and optionally allow custom values */ export type ChatSelectField = Extract & { allowCustom?: boolean } +/** Resolve a chat interaction field excluding select types or including chat select fields */ export type ChatInteractionField = Exclude | ChatSelectField /** `InteractionRequest` whose select fields may carry `allowCustom`. */ @@ -67,6 +70,7 @@ export type InteractionRequestWire = Omit & { // --------------------------------------------------------------------------- // Interaction lifecycle +/** Define possible statuses representing the state of a chat interaction */ export type ChatInteractionStatus = 'pending' | 'answered' | 'declined' | 'cancelled' | 'expired' /** Accepted field selections keyed by answer-spec field name. */ @@ -74,8 +78,10 @@ export type ChatInteractionStatus = 'pending' | 'answered' | 'declined' | 'cance * wider scalar union is additive and lets durable stores preserve text, * numeric, and boolean answer fields without coercion. */ export type InteractionAnswerValue = string | number | boolean | string[] +/** Map interaction identifiers to their corresponding answer values */ export type InteractionAnswers = Record +/** Resolve the result of parsing interaction answers with success status and corresponding data or error message */ export type ParseInteractionAnswersResult = | { succeeded: true; value: InteractionAnswers } | { succeeded: false; error: string } @@ -114,6 +120,7 @@ export interface ChatInteraction { cancelReason?: string } +/** Resolve if the interaction status is a terminal state excluding pending */ export function isTerminalInteractionStatus(status: ChatInteractionStatus): boolean { return status !== 'pending' } @@ -157,6 +164,7 @@ export function questionInteractionContentSignature(interaction: ChatInteraction })) } +/** Remove duplicate question interactions based on their content signature to ensure uniqueness */ export function dedupeQuestionInteractionsByContent(interactions: ChatInteraction[]): ChatInteraction[] { const seen = new Set() return interactions.filter((interaction) => { @@ -172,6 +180,7 @@ export function dedupeQuestionInteractionsByContent(interactions: ChatInteractio // Wire parsing — typed outcomes, fail loud at the caller (log + skip; never a // half-rendered card). +/** Resolve interaction parsing outcome as success with value or failure with error message */ export type ParseInteractionResult = | { succeeded: true; value: InteractionRequestWire } | { succeeded: false; error: string } @@ -191,11 +200,13 @@ export function parseInteractionRequest(data: Record | undefine return { succeeded: true, value: request as InteractionRequestWire } } +/** Describe data required to cancel an interaction including its identifier and optional reason */ export interface InteractionCancelData { id: string reason?: string } +/** Parse interaction cancel data and return success status with parsed value or error message */ export function parseInteractionCancel( data: Record | undefined, ): { succeeded: true; value: InteractionCancelData } | { succeeded: false; error: string } { @@ -211,12 +222,14 @@ export function parseInteractionCancel( // decides what it means. No interpretation here; the sidecar validates answers // fail-closed (invalid free text on an option-only ask → 400). +/** Determine if a chat interaction field allows free text input */ export function fieldAcceptsFreeText(field: ChatInteractionField): boolean { if (field.type === 'text') return true if (field.type === 'select') return (field as ChatSelectField).allowCustom === true return false } +/** Define the structure for delivering answers linked to a specific chat interaction and field */ export interface ComposerAnswerDelivery { interactionId: string field: ChatInteractionField @@ -249,14 +262,17 @@ export function composerAnswerData(field: ChatInteractionField, text: string): I // Part keys + codecs (persisted `messages.parts` entries and live stream parts // share these shapes). +/** Generate a unique key string for an interaction using the given identifier */ export function interactionPartKey(id: string): string { return `interaction:${id}` } +/** Generate a unique key string for a notice using the given identifier */ export function noticePartKey(id: string): string { return `notice:${id}` } +/** Define specific string literals representing different kinds of notices */ export type NoticeKind = 'warning' | 'auto-declined' /** @@ -279,6 +295,7 @@ export type InteractionPersistedPart = { cancelReason?: string } +/** Define a persisted notice part with type, id, kind, and text properties */ export type NoticePersistedPart = { type: 'notice' id: string diff --git a/src/interactions/route.ts b/src/interactions/route.ts index 03b058b..928dd3c 100644 --- a/src/interactions/route.ts +++ b/src/interactions/route.ts @@ -41,8 +41,10 @@ import { // A client resolves an ask by answering (`accepted`) or refusing (`declined`). // Withdrawal (`cancelled`) is an agent/broker outcome delivered via the // `interaction.cancel` event, never a client POST, so it is not accepted here. +/** Define possible outcomes for an interaction client as accepted or declined */ export type InteractionClientOutcome = 'accepted' | 'declined' +/** Validate interaction answer body and return success with data or failure with error message */ export type InteractionAnswerBodyValidation = | { ok: true; id: string; outcome: InteractionClientOutcome; data?: InteractionData } | { ok: false; error: string } @@ -76,6 +78,7 @@ export function validateInteractionAnswerBody(body: Record): In return { ok: true, id, outcome, data } } +/** Provide logging methods for warnings and errors in interaction routes */ export type InteractionRouteLogger = Pick /** Sidecar error → the client-actionable contract. Every "the ask is gone" @@ -119,6 +122,7 @@ export type InteractionConnectionResolution = | { ok: false; response: Response } | { ok: false; unavailable: string } +/** Define arguments required to resolve interaction connections based on request and intent */ export interface ResolveInteractionConnectionArgs { request: Request intent: 'list' | 'answer' @@ -127,6 +131,7 @@ export interface ResolveInteractionConnectionArgs { body?: Record } +/** Describe the arguments provided before processing an interaction answer including request, body, and connection details */ export interface BeforeInteractionAnswerArgs { request: Request /** Original parsed body, including product routing fields. */ @@ -141,6 +146,7 @@ export interface BeforeInteractionAnswerArgs { duplicateRequests: InteractionRequestWire[] } +/** Define arguments for durable interaction routes including a stable caller-created attempt key */ export interface DurableInteractionRouteArgs extends BeforeInteractionAnswerArgs { /** Caller-created opaque identifier, stable across an ambiguous retry. */ attemptKey: string @@ -170,6 +176,7 @@ export interface DurableInteractionRoutePersistence { fail?(args: DurableInteractionRouteArgs & { prepared: TPrepared; error: unknown }): void | Promise } +/** Define options to authenticate, authorize, and manage persistence for interaction answer routes */ export interface InteractionAnswerRouteOptions { /** Authenticate + authorize the caller and resolve the sidecar connection. * This is the only product-supplied step: session auth, workspace/thread @@ -184,6 +191,7 @@ export interface InteractionAnswerRouteOptions { logger?: InteractionRouteLogger } +/** Define routes to list outstanding interactions and resolve answers for live turns */ export interface InteractionAnswerRoute { /** GET — outstanding interactions for a live turn. Failures return an empty * list with an explicit `unavailable` code: the caller is a best-effort @@ -196,6 +204,7 @@ export interface InteractionAnswerRoute { answer: (request: Request) => Promise } +/** Create an interaction answer route that handles listing and resolving interaction requests */ export function createInteractionAnswerRoute(options: InteractionAnswerRouteOptions): InteractionAnswerRoute { const logger = options.logger ?? console diff --git a/src/interactions/sidecar.ts b/src/interactions/sidecar.ts index 5883fcd..7cf80a0 100644 --- a/src/interactions/sidecar.ts +++ b/src/interactions/sidecar.ts @@ -12,6 +12,7 @@ import type { InteractionData, InteractionOutcome, InteractionRequestWire } from './contract' +/** Describe error details including code, message, and upstream HTTP status for sidecar interactions */ export interface SidecarInteractionsError { code: string message: string @@ -19,6 +20,7 @@ export interface SidecarInteractionsError { status: number } +/** Represent the outcome of sidecar interactions with success or error details */ export type SidecarInteractionsResult = | { succeeded: true; value: T } | { succeeded: false; error: SidecarInteractionsError } diff --git a/src/knowledge-loop/index.ts b/src/knowledge-loop/index.ts index fa9d425..99e0b89 100644 --- a/src/knowledge-loop/index.ts +++ b/src/knowledge-loop/index.ts @@ -110,6 +110,7 @@ export interface KnowledgeDecider { (input: KnowledgeDeciderInput): Promise | KnowledgeDecision } +/** Define the input parameters required to decide knowledge proposals within an agent-knowledge loop */ export interface KnowledgeDeciderInput { /** The agent-knowledge loop context for this iteration. */ context: KnowledgeResearchLoopContext @@ -125,6 +126,7 @@ export interface KnowledgeDeciderInput { driver?: KnowledgeLoopDriver } +/** Define a decision containing a candidate and the gate's verdict on that candidate */ export interface KnowledgeDecision { /** The candidate the policy produced (may be empty to end the loop). */ candidate: KnowledgeCandidate @@ -146,6 +148,7 @@ export interface KnowledgeLoopDriver { }): Promise<{ finalText: string }> } +/** Define dependencies required to create and run a knowledge processing loop */ export interface CreateKnowledgeLoopDeps { /** * The knowledge-base root the loop reads/writes (an agent-knowledge layout). diff --git a/src/knowledge/index.ts b/src/knowledge/index.ts index c9b2a24..17735d2 100644 --- a/src/knowledge/index.ts +++ b/src/knowledge/index.ts @@ -38,6 +38,7 @@ export type SatisfiedByRule = | { anyOf: SatisfiedByRule[] } | { allOf: SatisfiedByRule[] } +/** Define the criteria and conditions required to satisfy a specific knowledge requirement */ export interface KnowledgeRequirementSpec { id: string description: string @@ -66,6 +67,7 @@ export interface KnowledgeStateAccessor { count: (query: { table: string; where?: string; statusIn?: string[] }) => number | Promise } +/** Define a signal representing knowledge with confidence level and optional supporting evidence */ export interface KnowledgeSignal { confidence: number evidence?: string diff --git a/src/missions/engine.ts b/src/missions/engine.ts index de89969..d734fb1 100644 --- a/src/missions/engine.ts +++ b/src/missions/engine.ts @@ -43,12 +43,14 @@ import { noopEventSink, type MissionEventSink, type MissionStreamEvent } from '. */ export type SandboxDispatch = (input: SandboxDispatchInput) => Promise +/** Define input parameters for dispatching a mission step in the sandbox environment */ export interface SandboxDispatchInput { mission: MissionRecord step: MissionStep stepIndex: number } +/** Define the result of a completed sandbox dispatch including artifact reference and optional cost details */ export interface SandboxDispatchDoneResult { kind?: 'done' /** Small pointer at the produced artifact/output (vault path, asset id, exec @@ -78,6 +80,7 @@ export interface SandboxDispatchInProgressResult { sublabel?: string } +/** Resolve the result of a sandbox dispatch as done or in progress */ export type SandboxDispatchResult = SandboxDispatchDoneResult | SandboxDispatchInProgressResult /** Outcome of running a single step. `cached` distinguishes a replay/skip @@ -102,6 +105,7 @@ type StepGateOutcome = | { kind: 'continue' } | { kind: 'halted'; status: MissionStatus; reason: string } +/** Define options to control mission plan execution with optional pre-step veto logic */ export interface MissionPlanRunOptions { /** Pre-step veto (kill switch, schedule window). A non-null return pauses the * mission with that reason before the step's side effect starts. */ @@ -138,6 +142,7 @@ export class RetryableStepError extends Error { * the gated step; everything else keeps the mission parked. */ export type MissionProposalResolution = 'pending' | 'approved' | 'rejected' | 'executed' | 'ignored' +/** Define mission gate categories as step, budget, or volume */ export type MissionGateKind = 'step' | 'budget' | 'volume' /** Product classification of one step. Returned by @@ -184,6 +189,7 @@ export interface MissionApprovalsPort { countExternalActionProposals(missionId: string): Promise } +/** Define configuration options for mission gating including approvals, step classification, and action limits */ export interface MissionGateOptions { approvals: MissionApprovalsPort /** Which steps need human approval, and as what. Return null for an ungated @@ -194,6 +200,7 @@ export interface MissionGateOptions { externalActionCap?: number } +/** Define configuration options for initializing and controlling the mission engine behavior */ export interface MissionEngineOptions { service: MissionService /** Per-step USD estimate. Load-bearing twice: the budget gate parks on it @@ -216,6 +223,7 @@ export interface MissionEngineOptions { nonFatalStepKinds?: readonly string[] } +/** Resolve mission plan steps with concurrency control and durable state management */ export interface MissionEngine { /** Run exactly one plan step. Idempotent: re-invoking for a step already * `done` returns the cached pointer without re-dispatching. A lost guarded @@ -299,6 +307,7 @@ function terminalMissionEvent( } } +/** Create a mission engine configured with options to manage mission execution and error handling */ export function createMissionEngine(options: MissionEngineOptions): MissionEngine { const { service, estimateStepCostUsd, gates } = options const sink = options.sink ?? noopEventSink diff --git a/src/missions/events.ts b/src/missions/events.ts index a27ddb0..c29d838 100644 --- a/src/missions/events.ts +++ b/src/missions/events.ts @@ -19,6 +19,7 @@ import type { StepAgentActivity } from './agent-activity' +/** Handle mission stream events by processing emitted MissionStreamEvent objects */ export interface MissionEventSink { emit(event: MissionStreamEvent): void } @@ -41,6 +42,7 @@ export interface MissionStreamStep { status: MissionStreamStepStatus } +/** Define possible status values for a mission stream step */ export type MissionStreamStepStatus = | 'pending' | 'running' @@ -48,6 +50,7 @@ export type MissionStreamStepStatus = | 'failed' | 'waiting_approval' +/** Define possible statuses representing the current state of a mission stream */ export type MissionStreamStatus = | 'scheduled' | 'running' diff --git a/src/missions/plan-parse.ts b/src/missions/plan-parse.ts index d177321..d69679a 100644 --- a/src/missions/plan-parse.ts +++ b/src/missions/plan-parse.ts @@ -26,17 +26,20 @@ export const DEFAULT_MISSION_STEP_KINDS: readonly string[] = [ 'best-effort', ] +/** Define the structure representing a parsed mission step with id, kind, and intent fields */ export interface ParsedMissionStep { id: string kind: string intent: string } +/** Describe a mission with a title and an ordered list of parsed steps */ export interface ParsedMission { title: string steps: ParsedMissionStep[] } +/** Define options to specify allowed lowercase step kinds for parsing mission blocks */ export interface ParseMissionBlocksOptions { /** Allowed step kinds (lowercase). Default {@link DEFAULT_MISSION_STEP_KINDS}. */ kinds?: readonly string[] diff --git a/src/missions/service.ts b/src/missions/service.ts index 0f8a145..28b3d8d 100644 --- a/src/missions/service.ts +++ b/src/missions/service.ts @@ -29,8 +29,10 @@ export type MissionStatus = | 'aborted' | 'cancelled' +/** Define possible statuses for a mission step during its execution lifecycle */ export type MissionStepStatus = 'pending' | 'running' | 'waiting_approval' | 'done' | 'failed' +/** Define the structure and state details of a mission step within a workflow system */ export interface MissionStep { id: string /** What the step should accomplish — an intent, never an implementation. */ @@ -49,6 +51,7 @@ export interface MissionStep { resultRef?: string } +/** Define the structure for tracking mission token usage, cost, duration, and LLM call counts */ export interface MissionCostLedger { tokensIn: number tokensOut: number @@ -209,6 +212,7 @@ const ZERO_LEDGER: MissionCostLedger = { llmCalls: 0, } +/** Define input parameters for creating a mission including optional deterministic id and unique plan steps */ export interface CreateMissionInput { /** Explicit row id. Omit to use the service's id generator. Pass a * DETERMINISTIC id (derived from the originating turn) when the caller may @@ -239,6 +243,7 @@ export interface CreateMissionInput { extras?: Record } +/** Define a patch to update the status and optional metadata of a step in a process */ export interface SetStepStatusPatch { sublabel?: string resultRef?: string @@ -257,11 +262,13 @@ export interface SetStepStatusPatch { } } +/** Define input parameters to complete a mission with status and optional summary */ export interface CompleteMissionInput { ok: boolean summary?: string } +/** Define methods to create, retrieve, and update missions with controlled engine binding and metadata merging */ export interface MissionService { createMission(input: CreateMissionInput): Promise getMission(id: string): Promise @@ -302,6 +309,7 @@ export interface MissionService { complete(id: string, input: CompleteMissionInput): Promise> } +/** Define options for configuring mission service behavior including storage, time, and ID generation */ export interface MissionServiceOptions { store: MissionStorePort /** Injectable clock (epoch ms). Default `Date.now`. */ @@ -325,6 +333,7 @@ function lostRace(id: string): MissionOutcome { return { succeeded: false, error: `Mission ${id} changed concurrently`, conflict: true } } +/** Create a mission service that manages mission records and audit events with customizable options */ export function createMissionService(options: MissionServiceOptions): MissionService { const { store } = options const now = options.now ?? (() => Date.now()) @@ -658,6 +667,7 @@ export function createMissionService(options: MissionServiceOptions): MissionSer // ── in-memory store ────────────────────────────────────────────────────────── +/** Define an in-memory mission store that tracks events and allows direct record writes */ export interface InMemoryMissionStore extends MissionStorePort { /** The full audit trail, append order. */ events(): MissionAuditEvent[] diff --git a/src/model-resolution/index.ts b/src/model-resolution/index.ts index 8e46dee..67a1465 100644 --- a/src/model-resolution/index.ts +++ b/src/model-resolution/index.ts @@ -33,28 +33,34 @@ function canonicalModelId(model: ModelInfo): string { return provider ? `${provider}/${model.id}` : model.id } +/** Define possible origins for the chat model configuration values */ export type ChatModelSource = 'request' | 'workspace' | 'env' | 'default' +/** Resolve a chat model with its identifier and source information */ export interface ResolvedChatModel { model: string source: ChatModelSource } +/** Represent successful chat model validation with a true status and a validated string value */ export interface ChatModelValidationSuccess { succeeded: true value: string } +/** Describe a failed chat model validation result with an error message */ export interface ChatModelValidationFailure { succeeded: false error: string } +/** Resolve the outcome of validating a chat model as either success or failure */ export type ChatModelValidationResult = ChatModelValidationSuccess | ChatModelValidationFailure /** The catalog-fetch boundary: maps a router base URL to the raw model list. */ export type LoadModels = (routerBaseUrl: string) => Promise +/** Resolve the effective chat model input by prioritizing request, workspace, environment, and default models */ export interface ResolveChatModelInput { /** Per-request override (highest precedence). */ requestModel?: string @@ -79,6 +85,7 @@ export function resolveChatModel(input: ResolveChatModelInput): ResolvedChatMode return { model: input.defaultModel, source: 'default' } } +/** Define input parameters for validating chat model IDs with optional allowlist and catalog access details */ export interface ValidateChatModelIdInput { /** Ids accepted without a catalog round-trip (defaults + operator-trusted). */ allowlist?: Iterable @@ -144,17 +151,20 @@ export async function validateChatModelId( return { succeeded: false, error: `Model is not available: ${cleaned}` } } +/** Resolve and return a trimmed string model ID or undefined for invalid or empty input */ export function cleanModelId(value: unknown): string | undefined { if (typeof value !== 'string') return undefined const trimmed = value.trim() return trimmed.length > 0 ? trimmed : undefined } +/** Validate if a model ID string conforms to length and character format requirements */ export function isWellFormedModelId(modelId: string): boolean { if (modelId.length > 200) return false return /^[A-Za-z0-9._/@:-]+$/.test(modelId) } +/** Resolve unique catalog IDs associated with a given model including its canonical form if applicable */ export function catalogIdsForModel(model: ModelInfo): string[] { const ids = new Set() if (typeof model.id === 'string' && model.id.trim()) ids.add(model.id.trim()) diff --git a/src/plans/index.ts b/src/plans/index.ts index e2c68fc..e94c192 100644 --- a/src/plans/index.ts +++ b/src/plans/index.ts @@ -39,6 +39,7 @@ export type ChatPlan = ChatPlanBase & ( /** Canonical transcript part for one durable plan. */ export type ChatPlanPersistedPart = ChatPlan & { type: 'plan' } +/** Resolve the result of parsing a plan submission into success with value or failure with error */ export type ParsePlanSubmittedResult = | { succeeded: true; value: ChatPlan } | { succeeded: false; error: string } @@ -120,14 +121,17 @@ function parsePlan(record: Record, defaultStatus?: ChatPlanStat : null } +/** Generate a unique key string for a given plan identifier */ export function planPartKey(planId: string): string { return `plan:${planId}` } +/** Generate a unique key string for a plan based on its ID and revision number */ export function planRevisionKey(planId: string, revision: number): string { return `plan:${planId}:revision:${revision}` } +/** Generate a unique follow-up turn ID based on the plan ID and its outcome */ export function planFollowUpTurnId(planId: string, outcome: 'approved' | 'rejected'): string { return `plan:${planId}:${outcome}` } @@ -140,10 +144,12 @@ export function canTransitionPlanStatus(from: ChatPlanStatus, to: ChatPlanStatus return false } +/** Resolve a ChatPlan into its persisted part representation for storage or transmission */ export function planToPersistedPart(plan: ChatPlan): ChatPlanPersistedPart { return { type: 'plan', ...plan } } +/** Resolve a persisted part object into a ChatPlan or return null if the type is not 'plan */ export function persistedPartToPlan(part: Record): ChatPlan | null { if (String(part.type ?? '') !== 'plan') return null return parsePlan(part) diff --git a/src/platform/billing.ts b/src/platform/billing.ts index ba581e2..0e6ec5e 100644 --- a/src/platform/billing.ts +++ b/src/platform/billing.ts @@ -11,6 +11,7 @@ import type { PlatformBillingClient, PlatformIdentity } from '../billing/index' +/** Define available subscription tiers for the TanglePlan service */ export type TanglePlanTier = 'free' | 'pro' | 'enterprise' /** 'pro' | 'enterprise' pass through; anything else (null, unknown) → 'free'. */ @@ -18,6 +19,7 @@ export function normalizeTanglePlanTier(plan: string | null | undefined): Tangle return plan === 'pro' || plan === 'enterprise' ? plan : 'free' } +/** Represent platform billing HTTP errors with status code and detailed message */ export class PlatformBillingHttpError extends Error { constructor( readonly status: number, @@ -37,6 +39,7 @@ export function isPlatformBillingHttpError(error: unknown): error is PlatformBil ) } +/** Define HTTP options for platform billing including base URL, service token, product slug, fetch implementation, and timeout */ export interface PlatformBillingHttpOptions { /** Platform root, e.g. https://id.tangle.tools (trailing slashes stripped). */ baseUrl: string @@ -50,17 +53,20 @@ export interface PlatformBillingHttpOptions { timeoutMs?: number } +/** Describe subscription tier and status information for a platform user */ export interface PlatformSubscriptionInfo { tier: TanglePlanTier status: string | null } +/** Describe the platform balance and lifetime spending with an optional update timestamp */ export interface PlatformBalanceSnapshot { balance: number lifetimeSpent: number updatedAt?: string } +/** Describe a product's usage and spending metrics on the platform */ export interface PlatformUsageProductRow { product: string | null totalSpent: number @@ -93,6 +99,7 @@ export interface ProductEntitlement { onFreeTier: boolean } +/** Define methods to interact with platform billing endpoints using user or service authentication */ export interface PlatformBillingHttp { /** GET /v1/plans/current (user bearer). */ getSubscription(userApiKey: string): Promise @@ -116,6 +123,7 @@ export interface PlatformBillingHttp { seatCheckoutUrl(productId: string): string } +/** Create a PlatformBillingHttp instance configured with given options and default behaviors */ export function createPlatformBillingHttp(opts: PlatformBillingHttpOptions): PlatformBillingHttp { const baseUrl = opts.baseUrl.replace(/\/+$/, '') if (!baseUrl) throw new Error('PlatformBillingHttpOptions.baseUrl is required') @@ -247,17 +255,20 @@ export function seatCheckoutUrl(baseUrl: string, productId: string): string { // ── Tier policy + composed state ──────────────────────────────────────────── +/** Define policy settings for concurrency and overage allowance in a tangle tier */ export interface TangleTierPolicy { concurrency: number overageAllowed: boolean } +/** Define default concurrency and overage policies for each TanglePlanTier level */ export const DEFAULT_TANGLE_TIER_POLICY: Record = { free: { concurrency: 1, overageAllowed: false }, pro: { concurrency: Number.POSITIVE_INFINITY, overageAllowed: true }, enterprise: { concurrency: Number.POSITIVE_INFINITY, overageAllowed: true }, } +/** Describe the state of a Tangle plan tier including subscription, balance, spending, and concurrency details */ export interface TangleTierState { tier: TanglePlanTier subscriptionStatus: string | null @@ -313,6 +324,7 @@ export const FREE_TIER_SPEND_CAP_USD = 2 */ export const DEFAULT_SEAT_BILLING_ENABLED_ENV_VAR = 'SEAT_BILLING_ENABLED' +/** Define options to configure seat billing flag environment variables and override flag name */ export interface SeatBillingFlagOptions { env?: Record /** Override the flag name; default {@link DEFAULT_SEAT_BILLING_ENABLED_ENV_VAR}. */ @@ -378,6 +390,7 @@ export function isProductEntitled(ent: ProductEntitlement): boolean { // ── Bridge onto the /billing seam ─────────────────────────────────────────── +/** Define a contract for resolving platform identities based on user identifiers */ export interface PlatformIdentityStore { resolveIdentity(userId: string): Promise } diff --git a/src/platform/guards.ts b/src/platform/guards.ts index 6a817fe..a0cd511 100644 --- a/src/platform/guards.ts +++ b/src/platform/guards.ts @@ -8,6 +8,7 @@ import { isTangleBillingEnforcementDisabled } from '../runtime/model' +/** Define options for configuring authentication guard behavior and session retrieval */ export interface AuthGuardOptions { /** e.g. a better-auth `auth.api.getSession` wrapped by the app. */ getSession(request: Request): Promise @@ -15,6 +16,7 @@ export interface AuthGuardOptions { loginPath?: string } +/** Resolve user authentication and session requirements for page and API requests */ export interface AuthGuard { /** Page guard — throws a 302 redirect Response to `loginPath`. */ requireUser(request: Request): Promise @@ -25,6 +27,7 @@ export interface AuthGuard { getOptionalSession(request: Request): Promise } +/** Create an authentication guard that enforces session presence and handles unauthorized access responses */ export function createAuthGuard(opts: AuthGuardOptions): AuthGuard { const loginPath = opts.loginPath ?? '/login' @@ -47,6 +50,7 @@ export function createAuthGuard(opts: AuthGuardOptions): AuthG } } +/** Resolve a value or an HTTP response indicating failure in a guarded operation */ export type GuardResolution = { ok: true; value: T } | { ok: false; response: Response } /** @@ -73,6 +77,7 @@ export function parseAdminEmails(raw: string | null | undefined): string[] { .filter(Boolean) } +/** Define options to resolve user session and control access based on allowed admin emails */ export interface AdminGuardOptions { requireUser(request: Request): Promise emailOf(session: Session): string | null | undefined @@ -93,11 +98,13 @@ export function createAdminGuard(opts: AdminGuardOptions): (re } } +/** Describe the billable balance state including overage permission and remaining USD balance */ export interface BillableBalanceState { overageAllowed: boolean remainingBalanceUsd: number } +/** Define options to assert and customize billable balance enforcement behavior */ export interface AssertBillableBalanceOptions { env?: Record /** App-specific enforcement override flag (e.g. 'GTM_BILLING_ENFORCEMENT'), diff --git a/src/platform/hub.ts b/src/platform/hub.ts index bfac09a..a9e4d3c 100644 --- a/src/platform/hub.ts +++ b/src/platform/hub.ts @@ -15,11 +15,13 @@ import { /** Hub bearer provenance mirrors the execution-key source union. */ export type TangleHubBearerSource = TangleExecutionKeySource +/** Represent a resolved bearer token with its associated TangleHub bearer source */ export interface ResolvedTangleHubBearer { bearer: string source: TangleHubBearerSource } +/** Resolve options required to obtain a user's TangleHub bearer token including environment and API key retrieval */ export interface ResolveUserTangleHubBearerOptions { userId: string /** Deployment context. Only local development may use env credentials. */ @@ -30,6 +32,7 @@ export interface ResolveUserTangleHubBearerOptions { getUserApiKey: () => string | null | undefined | Promise } +/** Resolve options for retrieving a TangleHub bearer token for a specified user */ export interface ResolveUserTangleHubBearerForUserOptions { userId: UserId environment?: TangleExecutionEnvironment @@ -37,6 +40,7 @@ export interface ResolveUserTangleHubBearerForUserOptions { getUserApiKey: (userId: UserId) => string | null | undefined | Promise } +/** Represent missing Tangle platform link error for a specified user ID */ export class TangleBearerMissingError extends Error { constructor(readonly userId: string) { super(`No Tangle platform link for user ${userId}`) @@ -64,6 +68,7 @@ export async function resolveUserTangleHubBearer( throw new TangleBearerMissingError(opts.userId) } +/** Resolve the TangleHub bearer token for a specified user based on provided options */ export async function resolveUserTangleHubBearerForUser( opts: ResolveUserTangleHubBearerForUserOptions, ): Promise { @@ -108,6 +113,7 @@ export interface HubClientLike { listHealthchecks(): Promise } +/** Define methods to require user ID, get bearer token, and create a hub client bound to the bearer */ export interface HubProxyContext { /** Resolve the authenticated user id. Throw the app's own auth Response / * redirect to reject — it propagates untouched. */ @@ -118,11 +124,13 @@ export interface HubProxyContext { createHubClient(bearer: string): HubClientLike } +/** Define arguments for configuring a proxy route with request and optional parameters */ export interface HubProxyRouteArgs { request: Request params?: Record } +/** Define routes for hub proxy handling catalog, connections, healthchecks, and authorization actions */ export interface HubProxyRoutes { /** GET → `{ catalog }`. */ catalog(args: HubProxyRouteArgs): Promise @@ -144,6 +152,7 @@ interface StartAuthBody { requestedScopes?: string[] } +/** Resolve hub proxy routes with authentication and error handling based on the given context */ export function createHubProxyRoutes(ctx: HubProxyContext): HubProxyRoutes { /** Auth runs OUTSIDE the proxy try/catch so the app's auth throw (redirect * Response etc.) is never swallowed; bearer + platform errors are mapped. */ diff --git a/src/platform/sso.ts b/src/platform/sso.ts index d589b04..dc929bf 100644 --- a/src/platform/sso.ts +++ b/src/platform/sso.ts @@ -17,6 +17,7 @@ const DEFAULT_SESSION_COOKIE = 'better-auth.session_token' // ── Signed state ──────────────────────────────────────────────────────────── +/** Define configuration options for managing SSO state including secret, lifetime, and clock injection */ export interface SsoStateConfig { /** HMAC-SHA256 secret (e.g. the app's auth secret). */ secret: string @@ -81,6 +82,7 @@ export async function verifySignedSsoState(state: string, config: SsoStateConfig // ── Seams ─────────────────────────────────────────────────────────────────── +/** Describe the result of exchanging SSO credentials including API key, user info, and optional plan details */ export interface TangleSsoExchangeResult { apiKey: string user: { id: string; email: string; name?: string | null } @@ -191,6 +193,7 @@ export interface BetterAuthSessionCookieSource { }> } +/** Define options to customize warning behavior for shadowed cookie names in authentication sessions */ export interface BetterAuthSessionCookieMinterOptions { /** Receives the shadowed-cookie-name warning (see below). Default * console.warn. */ @@ -261,6 +264,7 @@ export function createBetterAuthSessionCookieMinter( // ── Handlers ──────────────────────────────────────────────────────────────── +/** Define configuration options for handling Tangle SSO authentication and session management */ export interface TangleSsoHandlerOptions { auth: TangleSsoAuthClient store: TangleSsoAccountStore @@ -306,6 +310,7 @@ export interface TangleSsoHandlerOptions { now?: () => number } +/** Define handlers for SSO start and callback routes managing authentication flow and session cookies */ export interface TangleSsoHandlers { /** GET start route: mint + sign state, set the state cookie, 302 to the * platform authorize URL. `?redirect=` carries the post-login path. */ @@ -357,6 +362,7 @@ function parseStateCookiePayload(raw: string | null): StateCookiePayload | null } } +/** Create Tangle SSO handlers to manage authentication state, callbacks, and session cookies */ export function createTangleSsoHandlers(opts: TangleSsoHandlerOptions): TangleSsoHandlers { if (!opts.stateSecret) throw new Error('TangleSsoHandlerOptions.stateSecret is required') if (!opts.callbackUrl) throw new Error('TangleSsoHandlerOptions.callbackUrl is required') diff --git a/src/preflight/index.ts b/src/preflight/index.ts index 1787c79..b2353c5 100644 --- a/src/preflight/index.ts +++ b/src/preflight/index.ts @@ -179,6 +179,7 @@ function trimTrailingSlash(url: string): string { // --- Standard probe builders -------------------------------------------------- +/** Define configuration options for probing an LLM router with authentication and model details */ export interface RouterChatProbeConfig { /** LLM router base URL (LiteLLM / OpenAI-compatible), e.g. `https://router…`. */ baseUrl: string @@ -233,6 +234,7 @@ export function routerChatProbe(config: RouterChatProbeConfig): PreflightProbe { } } +/** Define configuration options for probing sandbox authentication endpoints */ export interface SandboxAuthProbeConfig { /** Sandbox API base URL. */ baseUrl: string @@ -277,6 +279,7 @@ export function sandboxAuthProbe(config: SandboxAuthProbeConfig): PreflightProbe } } +/** Define configuration options for performing an HTTP HEAD probe to check URL availability */ export interface HttpHeadProbeConfig { /** Probe name in the report. */ name: string diff --git a/src/preset-cloudflare/index.ts b/src/preset-cloudflare/index.ts index 9a7f3bd..925f5ff 100644 --- a/src/preset-cloudflare/index.ts +++ b/src/preset-cloudflare/index.ts @@ -285,6 +285,7 @@ export function createPresetDrizzleSchema(d: DrizzleSqliteCoreLike) { * Cloudflare `KVNamespace` satisfies it. Artifacts are stored under their path. */ export type VaultKv = KvLike +/** Define configuration options for handling preset tools including database, vault, and optional utilities */ export interface PresetToolHandlerOptions { /** The D1 database (Cloudflare `D1Database` satisfies {@link D1Like}). */ db: D1Like @@ -405,6 +406,7 @@ export function createPresetToolHandlers(opts: PresetToolHandlerOptions): AppToo // D1-backed KnowledgeStateAccessor // --------------------------------------------------------------------------- +/** Define options for accessing preset knowledge scoped to a specific workspace and configuration */ export interface PresetKnowledgeAccessorOptions { db: D1Like /** The active workspace — every `count` is scoped to it. */ @@ -523,6 +525,7 @@ export function createPresetWorkspaceKeyStore(db: D1Like): WorkspaceKeyStore { } } +/** Define preset billing options including database, provisioner, encryption key, budget, and optional settings */ export interface PresetBillingOptions { db: D1Like /** The key provisioner (`@tangle-network/tcloud`'s client satisfies it structurally). */ diff --git a/src/redact/index.ts b/src/redact/index.ts index 4eb75cf..cf81fc3 100644 --- a/src/redact/index.ts +++ b/src/redact/index.ts @@ -51,6 +51,7 @@ const SENSITIVE_KEYS = new Set([ 'phone', ]) +/** Define options to customize sensitive data redaction patterns and key names for ingestion */ export interface RedactForIngestionOptions { /** Extra patterns appended to {@link DEFAULT_REDACTION_PATTERNS} for the * string-level scrub (e.g. credit-card). Additive — defaults still apply. */ @@ -203,10 +204,12 @@ export type RedactedDocSegment = | { type: 'text'; text: string } | { type: 'redacted'; id: string; kind: string; cipher: string } +/** Define a document composed of multiple redacted content segments */ export interface RedactedDocument { segments: RedactedDocSegment[] } +/** Define options to encrypt text and specify patterns for redacting sensitive document content */ export interface BuildRedactedDocumentOptions { /** Encrypt one original span value. Wire it to `agent-app/crypto` * (`encryptWithKey` / `createFieldCrypto`). The cipher is what's stored. */ @@ -237,6 +240,7 @@ export async function buildRedactedDocument( return { segments } } +/** Define options to decrypt, authorize, and audit the reveal of a span segment */ export interface RevealSpanOptions { /** Decrypt a span cipher. Wire to `agent-app/crypto` (`decryptWithKey`). */ decrypt: (cipher: string) => string | Promise @@ -246,6 +250,7 @@ export interface RevealSpanOptions { onReveal?: (segment: { id: string; kind: string }) => void | Promise } +/** Describe the outcome of a reveal operation including success status, value, and failure reason */ export interface RevealResult { ok: boolean value?: string diff --git a/src/run/index.ts b/src/run/index.ts index 9599747..404766f 100644 --- a/src/run/index.ts +++ b/src/run/index.ts @@ -18,13 +18,16 @@ import { KNOWN_HARNESSES, type Harness } from '../harness/index' +/** Define execution mode as either router or sandbox */ export type ExecutionMode = 'router' | 'sandbox' /** The router pseudo-harness — the absence of a sandbox backend. Not a member * of `KNOWN_HARNESSES`; callers may pass it explicitly instead of null. */ export const ROUTER_HARNESS = 'router' as const +/** Provide a type alias for the ROUTER_HARNESS constant to enable consistent router harness usage */ export type RouterHarness = typeof ROUTER_HARNESS +/** Resolve a ProfileHarness as a Harness, RouterHarness, null, or undefined value */ export type ProfileHarness = Harness | RouterHarness | null | undefined /** diff --git a/src/runtime/agent.ts b/src/runtime/agent.ts index 64ea899..97c1111 100644 --- a/src/runtime/agent.ts +++ b/src/runtime/agent.ts @@ -73,6 +73,7 @@ export interface ResolvedAgentProfile { extraTools: unknown[] } +/** Define options for creating an agent runtime including model config and optional profile transformation */ export interface CreateAgentRuntimeOptions { /** The model endpoint the turns stream from. */ model: AgentRuntimeModelConfig @@ -105,6 +106,7 @@ export interface CreateAgentRuntimeOptions { isOtherExecutableTool?: (toolName: string) => boolean } +/** Define options for configuring a single agent turn including context, prior messages, prompts, and event handlers */ export interface AgentTurnOptions { /** The trusted per-turn context (who/where the turn runs as). */ ctx: AppToolContext @@ -116,6 +118,7 @@ export interface AgentTurnOptions { onProduced?: (event: AppToolProducedEvent) => void } +/** Resolve and stream tool execution loops with final results and intermediate events for agent runtime */ export interface AgentRuntime { /** Run the bounded tool loop to completion; resolve with final text + every * executed tool outcome. */ diff --git a/src/runtime/certified-delivery.ts b/src/runtime/certified-delivery.ts index 22793f9..5c93c86 100644 --- a/src/runtime/certified-delivery.ts +++ b/src/runtime/certified-delivery.ts @@ -32,6 +32,7 @@ import type { ResolvedAgentProfile } from './agent' const defaultRefreshMs = 300_000 +/** Define configuration options for delivering certified artifacts to a specified tenant target */ export interface CertifiedDeliveryConfig { /** The tenant target whose certified artifacts to deliver (the agent id). */ target: string @@ -45,6 +46,7 @@ export interface CertifiedDeliveryConfig { fetchImpl?: typeof fetch } +/** Resolve and manage certified profiles with refresh and composition capabilities */ export interface CertifiedDelivery { /** The `composeProfile` transform to pass to `createAgentRuntime`. Applies the * cached certified profile to the base surfaces; refreshes on the cadence. */ diff --git a/src/runtime/model-catalog.ts b/src/runtime/model-catalog.ts index 07edbde..d3b459b 100644 --- a/src/runtime/model-catalog.ts +++ b/src/runtime/model-catalog.ts @@ -40,6 +40,7 @@ export interface RouterModel { } } +/** Define the structure and capabilities of a catalog item with optional pricing and feature flags */ export interface CatalogModel { id: string name: string @@ -52,6 +53,7 @@ export interface CatalogModel { featured: boolean } +/** Define a catalog containing models with a default ID and fetch timestamp */ export interface ModelCatalog { defaultModelId: string | null fetchedAt: string diff --git a/src/runtime/model.ts b/src/runtime/model.ts index 505163e..9a2501c 100644 --- a/src/runtime/model.ts +++ b/src/runtime/model.ts @@ -17,12 +17,16 @@ export interface TangleModelConfig { baseUrl: string } +/** Define the environment context for executing Tangle operations */ export type TangleExecutionEnvironment = 'development' | 'staging' | 'production' | 'test' +/** Resolve the source of the Tangle execution key as either local environment or user input */ export type TangleExecutionKeySource = 'local-env' | 'user' +/** Define error codes for Tangle execution key issues related to API key and account connection */ export type TangleExecutionKeyErrorCode = | 'local_tangle_api_key_required' | 'tangle_account_not_connected' +/** Resolve options for model configuration including environment variables and default router base URL */ export interface ResolveModelOptions { /** Env to read (defaults to process.env). */ env?: Record @@ -30,6 +34,7 @@ export interface ResolveModelOptions { defaultRouterBaseUrl?: string } +/** Resolve options for retrieving user API keys within a specific Tangle execution environment */ export interface ResolveUserTangleExecutionKeyOptions { /** Deployment context. Only local development may fall back to env keys. */ environment?: TangleExecutionEnvironment @@ -39,6 +44,7 @@ export interface ResolveUserTangleExecutionKeyOptions { getUserApiKey: () => string | null | undefined | Promise } +/** Resolve options for retrieving a user's Tangle execution key with environment and API key access parameters */ export interface ResolveUserTangleExecutionKeyForUserOptions { userId: UserId environment?: TangleExecutionEnvironment @@ -46,11 +52,13 @@ export interface ResolveUserTangleExecutionKeyForUserOptions { getUserApiKey: (userId: UserId) => string | null | undefined | Promise } +/** Define a resolved key combining an API key with its Tangle execution source */ export interface ResolvedTangleExecutionKey { apiKey: string source: TangleExecutionKeySource } +/** Resolve options for retrieving a Tangle developer or user API key based on environment and context */ export interface ResolveTangleDevOrUserKeyOptions { /** Deployment context. Only local development may use the env key. */ environment?: TangleExecutionEnvironment @@ -60,6 +68,7 @@ export interface ResolveTangleDevOrUserKeyOptions { getUserApiKey: () => string | null | undefined | Promise } +/** Represent HTTP error response containing status, error message, and specific error code */ export interface TangleExecutionKeyHttpError { status: number body: { @@ -68,12 +77,14 @@ export interface TangleExecutionKeyHttpError { } } +/** Define configuration options for creating a Tangle router model including API key and model details */ export interface CreateTangleRouterModelConfigOptions { apiKey: string model: string baseUrl?: string } +/** Define options for configuring billing enforcement environment variables and overrides */ export interface TangleBillingEnforcementOptions { /** Env to read (defaults to process.env). */ env?: Record @@ -84,7 +95,9 @@ export interface TangleBillingEnforcementOptions { enforcementEnvVar?: string } +/** Provide the default base URL for the Tangle router API endpoint */ export const DEFAULT_TANGLE_ROUTER_BASE_URL = 'https://router.tangle.tools/v1' +/** Define the default environment variable name for Tangle billing enforcement */ export const DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR = 'TANGLE_BILLING_ENFORCEMENT' function requireEnv(env: Record, name: string): string { @@ -93,6 +106,7 @@ function requireEnv(env: Record, name: string): stri return value } +/** Resolve a string by trimming whitespace or returning null if empty or undefined */ export function trimOrNull(value: string | null | undefined): string | null { const trimmed = value?.trim() return trimmed ? trimmed : null @@ -102,6 +116,7 @@ function isTangleExecutionKeyErrorCode(value: unknown): value is TangleExecution return value === 'local_tangle_api_key_required' || value === 'tangle_account_not_connected' } +/** Represent execution key errors with specific codes and HTTP status information */ export class TangleExecutionKeyError extends Error { readonly code: TangleExecutionKeyErrorCode readonly status: number @@ -114,6 +129,7 @@ export class TangleExecutionKeyError extends Error { } } +/** Identify whether an error is a TangleExecutionKeyError based on its properties and type */ export function isTangleExecutionKeyError(error: unknown): error is TangleExecutionKeyError { return error instanceof TangleExecutionKeyError || ( @@ -126,6 +142,7 @@ export function isTangleExecutionKeyError(error: unknown): error is TangleExecut ) } +/** Resolve the current Tangle execution environment based on provided or process environment variables */ export function resolveTangleExecutionEnvironment( env: Record = process.env as Record, ): TangleExecutionEnvironment { @@ -158,6 +175,7 @@ export function isTangleBillingEnforcementDisabled( return resolveTangleExecutionEnvironment(env) === 'development' } +/** Resolve and format TangleExecutionKey HTTP errors into a standardized error object or return null */ export function tangleExecutionKeyHttpError(error: unknown): TangleExecutionKeyHttpError | null { if (!isTangleExecutionKeyError(error)) return null return { @@ -223,6 +241,7 @@ export async function resolveUserTangleExecutionKey( ) } +/** Resolve the Tangle execution key for a specified user using provided environment and API key options */ export async function resolveUserTangleExecutionKeyForUser( opts: ResolveUserTangleExecutionKeyForUserOptions, ): Promise { diff --git a/src/runtime/openai-stream.ts b/src/runtime/openai-stream.ts index b3cc0ac..5242957 100644 --- a/src/runtime/openai-stream.ts +++ b/src/runtime/openai-stream.ts @@ -96,6 +96,7 @@ function safeParse(s: string): Record { } } +/** Define options for configuring an OpenAI-compatible streaming chat turn including API details and tools */ export interface OpenAICompatStreamTurnOptions { /** OpenAI-compat base URL (e.g. the Tangle Router `https://router.tangle.tools/v1`). */ baseUrl: string diff --git a/src/runtime/surface-profile.ts b/src/runtime/surface-profile.ts index d387d8f..03d3c4f 100644 --- a/src/runtime/surface-profile.ts +++ b/src/runtime/surface-profile.ts @@ -83,6 +83,7 @@ export function defineSurfaceKind(opts: { return { kind: opts.kind, build: opts.build } } +/** Resolve and build the overlay for a given surface kind within a turn context */ export 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 diff --git a/src/sandbox/binary-read.ts b/src/sandbox/binary-read.ts index 8902ca5..aff0ed1 100644 --- a/src/sandbox/binary-read.ts +++ b/src/sandbox/binary-read.ts @@ -23,15 +23,18 @@ export interface SandboxExecChannel { ): Promise<{ stdout: string; stderr: string; exitCode: number }> } +/** Define options to execute code within a sandbox environment with optional session control */ export interface SandboxExecOptions { /** Run inside a named session rather than the box's default one. */ sessionId?: string } +/** Resolve the outcome of a sandbox file size check with success status and value or error message */ export type SandboxFileSizeOutcome = | { succeeded: true; value: number } | { succeeded: false; error: string } +/** Represent the outcome of reading sandbox file bytes with success status and corresponding data or error */ export type SandboxFileBytesOutcome = | { succeeded: true; value: { bytes: Uint8Array; size: number } } | { succeeded: false; error: string } diff --git a/src/sandbox/index.ts b/src/sandbox/index.ts index ff53466..9609e1d 100644 --- a/src/sandbox/index.ts +++ b/src/sandbox/index.ts @@ -29,6 +29,7 @@ import { ok, fail, type Outcome } from './outcome' export type { Outcome } from './outcome' export * from './binary-read' +/** Define client credentials for accessing the sandbox environment with API key and base URL */ export interface SandboxClientCredentials { apiKey: string baseUrl: string @@ -41,6 +42,7 @@ export interface SandboxClientCredentials { */ export type SandboxCredentialEnvironment = TangleExecutionEnvironment +/** Resolve options for obtaining sandbox client credentials from environment variables and classification */ export interface ResolveSandboxClientCredentialsOptions { /** * Environment object to read from. Defaults to process.env when available. @@ -141,6 +143,7 @@ function resolveDirectSandboxCredentials( return null } +/** Resolve sandbox client credentials based on environment and provided options asynchronously */ export async function resolveSandboxClientCredentials( options: ResolveSandboxClientCredentialsOptions = {}, ): Promise { @@ -178,6 +181,7 @@ export async function resolveSandboxClientCredentials( ) } +/** Define configuration parameters for sandbox resource allocation and lifecycle management */ export interface SandboxResourceConfig { image: string cpuCores: number @@ -187,6 +191,7 @@ export interface SandboxResourceConfig { idleTimeoutSeconds: number } +/** Define configuration options for resolving a provider and its model with optional API keys and routing details */ export interface ProviderResolutionConfig { routerBaseUrl?: string apiKey?: string @@ -204,6 +209,7 @@ export interface ProviderResolutionConfig { allowKeylessModel?: boolean } +/** Define the context for building a sandbox including workspace, integrations, and optional user ID */ export interface SandboxBuildContext { workspaceId: string connectedIntegrationIds: string[] @@ -215,17 +221,20 @@ export type { StorageConfig } // Scope handed to per-identity seams. workspaceId is always present; userId is // present when the lifecycle op carries one. Workspace-keyed products ignore userId. +/** Define a scope containing workspace and optional user identifiers for sandbox environments */ export interface SandboxScope { workspaceId: string userId?: string } // Snapshot RESTORE-on-create. Returned alongside storage; undefined => fresh box. +/** Define the specification for restoring a sandbox from a snapshot or another sandbox ID */ export interface SandboxRestoreSpec { fromSnapshot: string fromSandboxId: string } +/** Describe the failure details when resuming a stopped sandbox instance */ export interface StoppedSandboxResumeFailure { box: SandboxInstance error: Error @@ -233,6 +242,7 @@ export interface StoppedSandboxResumeFailure { boxKey: string } +/** Define the structure for resuming a stopped sandbox with replacement key and optional restore options */ export interface StoppedSandboxResumeRecovery { // Used for both the replacement sandbox name and idempotency key. replacementBoxKey: string @@ -243,12 +253,14 @@ export interface StoppedSandboxResumeRecovery { // Reuse health gate + sidecar liveness. The exec+timeout-race is generic; the // sidecarProcessPattern is harness-specific (which process is the live sidecar), // so it is a closure. Absent => no liveness probe (reuse on metadata.harness match). +/** Define configuration for liveness probes including sidecar process pattern and optional timeouts */ export interface LivenessProbeConfig { sidecarProcessPattern: (harness: Harness) => string execTimeoutMs?: number psTimeoutMs?: number } +/** Define options for composing a user profile including prompts, files, servers, and name */ export interface ProfileComposeOptions { systemPrompt?: string extraFiles?: AgentProfileFileMount[] @@ -256,6 +268,7 @@ export interface ProfileComposeOptions { name?: string } +/** Define runtime configuration methods for sandbox environments including credentials, metadata, and permissions */ export interface SandboxRuntimeConfig { // Widened to accept an optional scope and be async so a per-user key can be // minted. The sync, no-arg form still satisfies the type (back-compat). @@ -316,6 +329,7 @@ export interface SandboxRuntimeConfig { deferProfileFiles?: boolean } +/** Define default resource limits and settings for sandbox environments */ export const DEFAULT_SANDBOX_RESOURCES: SandboxResourceConfig = { image: 'universal', cpuCores: 2, @@ -344,6 +358,7 @@ function getClientFromCreds(creds: SandboxClientCredentials): Sandbox { // Sync client for non-scoped callers (secretStoreFromClient etc.). Resolves // credentials with no scope; throws if the seam returns a Promise — scoped // products must use the async ensureWorkspaceSandbox path. +/** Resolve a synchronous sandbox client from provided runtime configuration credentials */ export function getClient(shell: SandboxRuntimeConfig): Sandbox { const creds = shell.credentials() if (creds && typeof (creds as Promise).then === 'function') { @@ -353,16 +368,19 @@ export function getClient(shell: SandboxRuntimeConfig): Sandbox { return getClientFromCreds(creds as SandboxClientCredentials) } +/** Reset the client cache to clear stored data and force fresh retrieval */ export function resetClientCache(): void { _cached = null } +/** Describe an application tool with its name, unique key, and description */ export interface AppToolDescriptor { tool: AppToolName key: string description: string } +/** Define options for building MCP server configurations in the app tool environment */ export interface BuildAppToolMcpServersOptions { tools: AppToolDescriptor[] baseUrl: string @@ -371,6 +389,7 @@ export interface BuildAppToolMcpServersOptions { headerNames?: ToolHeaderNames } +/** Build a mapping of MCP server profiles keyed by tool identifiers from provided options */ export function buildAppToolMcpServers( options: BuildAppToolMcpServersOptions, ): Record { @@ -388,6 +407,7 @@ export function buildAppToolMcpServers( return entries } +/** Define options for ensuring a workspace sandbox with provisioning and progress handling */ export interface EnsureWorkspaceSandboxOptions { workspaceId: string userId?: string @@ -414,18 +434,21 @@ function shellSingleQuote(value: string): string { return `'${value.replace(/'/g, `'\\''`)}'` } +/** Define the specification for a sandbox tool including its name, content, and optional executability */ export interface SandboxToolSpec { name: string content: string executable?: boolean } +/** Define options for resolving sandbox tool paths including appName, baseDir, and binDir */ export interface SandboxToolPathOptions { appName: string baseDir?: string binDir?: string } +/** Define options for building sandbox tool file mounts including tool specifications and paths */ export interface BuildSandboxToolFileMountsOptions extends SandboxToolPathOptions { tools: readonly SandboxToolSpec[] } @@ -449,6 +472,7 @@ function normalizeSandboxToolDir(value: string, label: string): string { return dir === '' ? '/' : dir } +/** Resolve the root directory path for a sandbox tool based on provided options */ export function sandboxToolRootDir(options: SandboxToolPathOptions): string { const appName = normalizeSandboxToolSegment(options.appName, 'sandbox tool appName') const baseDir = normalizeSandboxToolDir( @@ -458,17 +482,20 @@ export function sandboxToolRootDir(options: SandboxToolPathOptions): string { return `${baseDir}/${appName}` } +/** Resolve the binary directory path for a sandbox tool based on provided options */ export function sandboxToolBinDir(options: SandboxToolPathOptions): string { normalizeSandboxToolSegment(options.appName, 'sandbox tool appName') if (options.binDir) return normalizeSandboxToolDir(options.binDir, 'sandbox tool binDir') return `${sandboxToolRootDir(options)}/bin` } +/** Resolve the file system path to a specified sandbox tool based on given options */ export function sandboxToolPath(options: SandboxToolPathOptions & { toolName: string }): string { const toolName = normalizeSandboxToolSegment(options.toolName, 'sandbox tool name') return `${sandboxToolBinDir(options)}/${toolName}` } +/** Build file mounts for sandbox tools based on provided options and tool configurations */ export function buildSandboxToolFileMounts( options: BuildSandboxToolFileMountsOptions, ): AgentProfileFileMount[] { @@ -482,6 +509,7 @@ export function buildSandboxToolFileMounts( }) } +/** Build a shell script that sets up and exports the sandbox tool binary directory in user profiles */ export function buildSandboxToolPathSetupScript(options: SandboxToolPathOptions): string { const binDir = sandboxToolBinDir(options) const exportLine = `export PATH=${binDir}:$PATH` @@ -498,6 +526,7 @@ export function buildSandboxToolPathSetupScript(options: SandboxToolPathOptions) ].join('\n') } +/** Resolve the sandbox environment PATH setup by executing the configuration script with given options */ export async function runSandboxToolPathSetup( box: SandboxInstance, options: SandboxToolPathOptions, @@ -537,6 +566,7 @@ function shellPath(path: string): string { // written into a running box and the rest (non-inline refs that the // orchestrator must resolve, so they stay in the create payload). Returns the // inline set to defer and a profile copy with those inline files removed. +/** Split profile files into inline deferred files and a lean profile without them */ export function splitDeferredProfileFiles( profile: AgentProfile, ): { leanProfile: AgentProfile; deferredFiles: AgentProfileFileMount[] } { @@ -741,6 +771,7 @@ function deferredProfileWriteFailed(stage: 'new' | 'reused' | 'resumed', name: s type ExistingBoxStage = 'reused' | 'resumed' +/** Represent an error thrown when sandbox runtime authentication refresh fails for a specific stage and name */ export class SandboxRuntimeAuthRefreshError extends Error { constructor(stage: ExistingBoxStage, name: string, detail: string, cause?: unknown) { super(`${stage} sandbox auth refresh failed for ${name}: ${detail}`, { cause }) @@ -765,6 +796,7 @@ export class SandboxRuntimeAuthRefreshError extends Error { // exec-plane request can never park the caller (and thus never park provisioning). // A small pace between execs keeps the burst rate below the proxy throttle that // triggers the hang. +/** Define options to control execution timeout, pacing, and retry behavior when writing profile files */ export interface WriteProfileFilesOptions { // Hard ceiling per exec (ms). A hung/wedged exec is abandoned and retried. execTimeoutMs?: number @@ -809,6 +841,7 @@ function fileApiSupportsMode(box: SandboxInstance): boolean { return fs?.supportsWriteMode === true } +/** Write profile files to a sandbox with pacing, retries, and optional execution timeout handling */ export async function writeProfileFilesToBox( box: SandboxInstance, files: AgentProfileFileMount[], @@ -1477,6 +1510,7 @@ export async function peekWorkspaceSandbox( return { status: 'running', box: match } } +/** Resolve or create a workspace sandbox instance with optional reuse and progress tracking */ export async function ensureWorkspaceSandbox( shell: SandboxRuntimeConfig, options: EnsureWorkspaceSandboxOptions, @@ -1704,6 +1738,7 @@ export async function ensureWorkspaceSandbox( return box } +/** Represent a fully configured model with optional API key and base URL for sandbox platform integration */ export interface ResolvedModel { model: string provider: string @@ -1713,6 +1748,7 @@ export interface ResolvedModel { baseUrl?: string } +/** Resolve and return the appropriate model configuration based on provider settings and optional overrides */ export function resolveModel( config: ProviderResolutionConfig | undefined, override?: { model?: string; modelApiKey?: string }, @@ -1741,6 +1777,7 @@ export function resolveModel( // but the published package does not re-export the PromptInputPart type by name from // any of its entry points, so it's derived structurally off the method signature // itself — this stays in lockstep with the SDK's actual accepted shape. +/** Extract a single element type from the array parameter of SandboxInstance's streamPrompt method */ export type PromptInputPart = Extract< Parameters[0], readonly unknown[] @@ -1754,6 +1791,7 @@ function historyTranscript( .join('\n\n') } +/** Build a single string combining conversation history and the current user message */ export function flattenHistory( message: string, history?: Array<{ role: 'user' | 'assistant'; content: string }>, @@ -1782,6 +1820,7 @@ export function mergeHistoryIntoParts( return merged } +/** Resolve conflicts and merge extra MCP profiles into the app tool MCP without overwriting existing keys */ export function mergeExtraMcp( appToolMcp: Record, baseProfileMcp: Record, @@ -1795,6 +1834,7 @@ export function mergeExtraMcp( return { ...appToolMcp, ...(extra ?? {}) } } +/** Attach a specified reasoning effort level to an agent profile for a given harness */ export function attachReasoningEffort( profile: AgentProfile, harness: Harness, @@ -1813,6 +1853,7 @@ export function attachReasoningEffort( } } +/** Define options for configuring and controlling a streaming sandbox prompt session */ export interface StreamSandboxPromptOptions { sessionId?: string executionId?: string @@ -1850,6 +1891,7 @@ export interface StreamSandboxPromptOptions { type StreamPromptOptions = Parameters[1] +/** Resolve and stream AI-generated responses from a sandboxed environment based on input messages and options */ export async function* streamSandboxPrompt( shell: SandboxRuntimeConfig, box: SandboxInstance, @@ -1918,6 +1960,7 @@ export async function* streamSandboxPrompt( } } +/** Resolve a sandbox prompt by streaming and aggregating message parts into a complete string */ export async function runSandboxPrompt( shell: SandboxRuntimeConfig, box: SandboxInstance, @@ -1955,12 +1998,15 @@ export async function runSandboxPrompt( // @tangle-network/sandbox). The product's role-mapping seam must produce one of // these; binding the seam's return type to the union makes a wrong mapping a // compile error rather than a runtime 400 from the orchestrator. +/** Define permission levels for sandbox access and control */ export type SandboxPermissionLevel = 'owner' | 'admin' | 'developer' | 'viewer' +/** Map workspace roles to corresponding sandbox permission levels */ export interface MemberSyncSeam { roleToSandboxRole: (workspaceRole: string) => SandboxPermissionLevel } +/** Resolve adding a user with a specific role to a sandbox and return the operation outcome */ export async function syncSandboxMemberAdd( box: SandboxInstance, seam: MemberSyncSeam, @@ -1975,6 +2021,7 @@ export async function syncSandboxMemberAdd( } } +/** Remove a member from the sandbox while preserving their home directory and handle the outcome */ export async function syncSandboxMemberRemove( box: SandboxInstance, userId: string, @@ -1987,6 +2034,7 @@ export async function syncSandboxMemberRemove( } } +/** Synchronize a sandbox member's role by updating permissions based on the provided role mapping */ export async function syncSandboxMemberRole( box: SandboxInstance, seam: MemberSyncSeam, @@ -2001,6 +2049,7 @@ export async function syncSandboxMemberRole( } } +/** Define methods to create, update, retrieve, and delete secrets asynchronously */ export interface SecretStore { create: (name: string, value: string) => Promise update: (name: string, value: string) => Promise @@ -2008,6 +2057,7 @@ export interface SecretStore { delete: (name: string) => Promise } +/** Resolve a SecretStore interface using the provided SandboxRuntimeConfig shell */ export function secretStoreFromClient(shell: SandboxRuntimeConfig): SecretStore { const client = getClient(shell) return { @@ -2024,6 +2074,7 @@ export function secretStoreFromClient(shell: SandboxRuntimeConfig): SecretStore } } +/** Resolve storing a secret by creating or updating it in the given SecretStore */ export async function storeSecret( store: SecretStore, name: string, @@ -2042,6 +2093,7 @@ export async function storeSecret( } } +/** Resolve a secret value from the store by its name and return the outcome asynchronously */ export async function readSecret(store: SecretStore, name: string): Promise> { try { return ok(await store.get(name)) @@ -2050,6 +2102,7 @@ export async function readSecret(store: SecretStore, name: string): Promise> { try { await store.delete(name) @@ -2059,6 +2112,7 @@ export async function deleteSecret(store: SecretStore, name: string): Promise | null { return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record) : null } +/** Resolve the severed stream event to a corresponding sandbox step transition or null */ export function classifySeveredStream(event: unknown): SandboxStepTransition | null { const root = asPlainRecord(event) if (!root || root.type !== 'message.part.updated') return null @@ -2183,6 +2241,7 @@ export function classifySeveredStream(event: unknown): SandboxStepTransition | n return { kind: 'step-finish', reason, severed: SEVERED_FINISH_REASONS.has(reason) } } +/** Determine if an event is a terminal prompt event with type 'result' or 'done */ export function isTerminalPromptEvent(event: unknown): boolean { const t = asPlainRecord(event)?.type return t === 'result' || t === 'done' @@ -2190,6 +2249,7 @@ export function isTerminalPromptEvent(event: unknown): boolean { // Interactive-question detector. Returns the question text or null. Used by // streamSandboxPrompt when disallowQuestions is set. +/** Resolve the interactive question text from a structured event or return null if none found */ export function detectInteractiveQuestion(event: unknown): string | null { const root = asPlainRecord(event) if (!root) return null diff --git a/src/sandbox/outcome.ts b/src/sandbox/outcome.ts index a848891..4f23e1e 100644 --- a/src/sandbox/outcome.ts +++ b/src/sandbox/outcome.ts @@ -2,6 +2,7 @@ // leaf so both index.ts and terminal-proxy-token.ts import it instead of // re-declaring the type (index.ts re-exports * from terminal-proxy-token, so // the token module cannot import from index without a cycle). +/** Represent success or failure of an operation with corresponding value or error information */ export type Outcome = | { succeeded: true; value: T } | { succeeded: false; error: Error } diff --git a/src/sandbox/terminal-proxy-token.ts b/src/sandbox/terminal-proxy-token.ts index 13050cc..f560035 100644 --- a/src/sandbox/terminal-proxy-token.ts +++ b/src/sandbox/terminal-proxy-token.ts @@ -8,6 +8,7 @@ import { ok, fail, type Outcome } from './outcome' // Terminal-proxy HMAC token. Identity tuple is generic; the secret comes from a // closure (fail-loud if absent). +/** Define identity details for a terminal proxy including user, workspace, and sandbox identifiers */ export interface TerminalProxyIdentity { userId: string workspaceId: string @@ -16,6 +17,7 @@ export interface TerminalProxyIdentity { const TERMINAL_PROXY_TOKEN_TTL_MS = 15 * 60 * 1000 +/** Generate a signed token for TerminalProxyIdentity with an expiration based on TTL milliseconds */ export async function mintTerminalProxyToken( secret: string, identity: TerminalProxyIdentity, @@ -33,6 +35,7 @@ export async function mintTerminalProxyToken( return ok({ token: `${encoded}.${sig}`, expiresAt }) } +/** Verify the authenticity and validity of a terminal proxy token against expected identity and timestamp */ export async function verifyTerminalProxyToken( secret: string, token: string, diff --git a/src/sandbox/workspace-terminal.ts b/src/sandbox/workspace-terminal.ts index c729dd7..ab3154e 100644 --- a/src/sandbox/workspace-terminal.ts +++ b/src/sandbox/workspace-terminal.ts @@ -5,6 +5,7 @@ import { type TerminalProxyIdentity, } from './terminal-proxy-token' +/** Define the shape of a workspace sandbox instance including its connection details and status */ export interface WorkspaceSandboxInstanceLike { id: string name?: string @@ -23,11 +24,13 @@ export interface WorkspaceSandboxInstanceLike { // concrete `ensureWorkspaceSandbox` in ./index, which is bound to the // @tangle-network/sandbox client). Kept as a public export — external // consumers compose it; removing it would be a breaking change. +/** Define the context containing workspace and user identifiers for sandbox environment operations */ export interface WorkspaceSandboxEnsureContext { workspaceId: string userId: string } +/** Define configuration options for managing and interacting with workspace sandboxes */ export interface WorkspaceSandboxManagerOptions { getClient: (ctx: WorkspaceSandboxEnsureContext) => Promise | TClient nameForWorkspace: (workspaceId: string, ctx: WorkspaceSandboxEnsureContext) => string @@ -45,6 +48,7 @@ export interface WorkspaceSandboxManagerOptions void } +/** Manage workspace sandboxes by ensuring their creation and retrieval for specified users */ export interface WorkspaceSandboxManager { ensureWorkspaceSandbox: ( workspaceId: string, @@ -53,6 +57,7 @@ export interface WorkspaceSandboxManager Promise } +/** Create a manager to handle workspace sandbox instances with client and options configuration */ export function createWorkspaceSandboxManager( opts: WorkspaceSandboxManagerOptions, ): WorkspaceSandboxManager { @@ -91,14 +96,17 @@ export function createWorkspaceSandboxManager number } +/** Resolve the identity type used for sandbox terminal token subjects */ export type SandboxTerminalTokenSubject = TerminalProxyIdentity +/** Provide token and expiration details for a sandbox terminal session */ export interface SandboxTerminalTokenResult { token: string expiresAt: Date @@ -113,6 +121,7 @@ const BEARER_SUBPROTOCOL_PREFIX = 'bearer.' // in-flight browser terminal sessions right after rollout. const LEGACY_TERMINAL_TOKEN_PREFIX = 'sbxt_' +/** Generate a sandbox terminal token for a given subject with specified options */ export async function createSandboxTerminalToken( subject: SandboxTerminalTokenSubject, opts: SandboxTerminalTokenOptions, @@ -128,6 +137,7 @@ export async function createSandboxTerminalToken( return minted.value } +/** Verify the validity of a sandbox terminal token against the expected identity and options */ export async function verifySandboxTerminalToken( token: string, expected: SandboxTerminalTokenSubject, @@ -142,10 +152,12 @@ export async function verifySandboxTerminalToken( return verifyTerminalProxyToken(secret ?? '', normalized, expected, now) } +/** Represent an authenticated user within a sandbox environment with a unique identifier */ export interface AuthenticatedSandboxUser { id: string } +/** Define options to handle workspace sandbox connections with user authentication and access control */ export interface WorkspaceSandboxConnectionHandlerOptions { requireUser: (request: Request) => Promise requireWorkspaceAccess: (args: { request: Request; userId: string; workspaceId: string }) => Promise @@ -156,6 +168,7 @@ export interface WorkspaceSandboxConnectionHandlerOptions( opts: WorkspaceSandboxConnectionHandlerOptions, ) { @@ -235,17 +249,20 @@ export function createWorkspaceSandboxConnectionHandler Promise requireWorkspaceAccess: (args: { request: Request; userId: string; workspaceId: string; sandboxId: string }) => Promise @@ -256,6 +273,7 @@ export interface WorkspaceSandboxRuntimeProxyHandlerOptions { forwardHeaders?: string[] } +/** Define arguments for proxying runtime requests within a workspace sandbox environment */ export interface WorkspaceSandboxRuntimeProxyArgs { request: Request params: { @@ -265,6 +283,7 @@ export interface WorkspaceSandboxRuntimeProxyArgs { } } +/** Create a proxy handler to resolve sandbox runtime requests with user and workspace access validation */ export function createWorkspaceSandboxRuntimeProxyHandler(opts: WorkspaceSandboxRuntimeProxyHandlerOptions) { return async function handleWorkspaceSandboxRuntimeProxy({ request, params }: WorkspaceSandboxRuntimeProxyArgs): Promise { const user = await opts.requireUser(request) @@ -348,6 +367,7 @@ export function createWorkspaceSandboxRuntimeProxyHandler(opts: WorkspaceSandbox const SANDBOX_TERMINAL_WS_PATHNAME = /^\/api\/workspaces\/([^/]+)\/sandbox\/runtime\/([^/]+)\/(terminals\/[^/]+\/ws)$/ +/** Define the structure for matching a sandbox terminal WebSocket with workspace and path details */ export interface SandboxTerminalWsMatch { workspaceId: string sandboxId: string @@ -383,6 +403,7 @@ export function isSandboxTerminalWsUpgrade(request: Request): boolean { } } +/** Define options to handle user authentication, workspace access, and sandbox API credential retrieval */ export interface WorkspaceSandboxTerminalUpgradeHandlerOptions { requireUser: (request: Request) => Promise requireWorkspaceAccess: (args: { request: Request; userId: string; workspaceId: string; sandboxId: string }) => Promise @@ -458,6 +479,7 @@ export function createWorkspaceSandboxTerminalUpgradeHandler(opts: WorkspaceSand const DEFAULT_RUNTIME_PROXY_HEADERS = ['accept', 'content-type', 'last-event-id', 'x-session-id'] +/** Build proxy headers for sandbox runtime including authorization and forwarded headers */ export function buildSandboxRuntimeProxyHeaders(source: Headers, sandboxApiKey: string, forwardHeaders = DEFAULT_RUNTIME_PROXY_HEADERS): Headers { const headers = new Headers() headers.set('Authorization', `Bearer ${sandboxApiKey}`) @@ -468,12 +490,14 @@ export function buildSandboxRuntimeProxyHeaders(source: Headers, sandboxApiKey: return headers } +/** Encode a runtime path by URI-encoding each valid segment and returning null for invalid segments */ export function encodeSandboxRuntimePath(runtimePath: string): string | null { const segments = runtimePath.split('/') if (segments.some((segment) => !segment || segment === '.' || segment === '..')) return null return segments.map((segment) => encodeURIComponent(segment)).join('/') } +/** Extract the token from a bearer authorization string or return null if invalid or missing */ export function bearerToken(value: string | null): string | null { if (!value) return null const trimmed = value.trim() @@ -486,6 +510,7 @@ export function bearerToken(value: string | null): string | null { return trimmed } +/** Resolve and decode a bearer token from a comma-separated subprotocol string or return null */ export function bearerSubprotocolToken(value: string | null): string | null { if (!value) return null for (const part of value.split(',')) { @@ -503,6 +528,7 @@ export function bearerSubprotocolToken(value: string | null): string | null { return null } +/** Resolve the terminal token from request headers using Authorization or Sec-WebSocket-Protocol fields */ export function terminalTokenFromRequest(headers: Headers): string | null { return bearerToken(headers.get('Authorization')) ?? bearerSubprotocolToken(headers.get('Sec-WebSocket-Protocol')) } diff --git a/src/sequences-react/contracts.ts b/src/sequences-react/contracts.ts index a8494f5..10e17ce 100644 --- a/src/sequences-react/contracts.ts +++ b/src/sequences-react/contracts.ts @@ -42,6 +42,7 @@ export interface EditorTimelineState { scrollLeft: number } +/** Manage and track command execution with undo, redo, state subscription, and timeline reset capabilities */ export interface CommandStack { execute(command: TimelineCommand): void undo(): void @@ -68,11 +69,13 @@ export interface ZoomMath { maxZoom: number } +/** Define a point in a timeline where snapping occurs based on frame and kind */ export interface SnapPoint { frame: number kind: 'clip-start' | 'clip-end' | 'playhead' | 'sequence-end' } +/** Describe the result of snapping a point to a frame including success status and snapped point details */ export interface SnapResult { frame: number snapped: boolean @@ -120,6 +123,7 @@ export interface WaveformData { durationSeconds: number } +/** Represent a segment of transcription with text and start and end times in seconds */ export interface TranscriptionSegment { text: string startSeconds: number @@ -169,6 +173,7 @@ export interface TimelineEditorLabels { ghostCaptionLane?: string } +/** Define properties and callbacks for editing and applying operations on a sequence timeline */ export interface TimelineEditorProps { timeline: SequenceTimeline canWrite: boolean @@ -206,6 +211,7 @@ export interface TimelineEditorProps { className?: string } +/** Provide default labels and accessibility text for timeline editor UI elements */ export const DEFAULT_TIMELINE_LABELS: Required = { splitClip: 'Split here', splitClipAriaLabel: 'Split clip at playhead', diff --git a/src/sequences-react/engine/command-stack.ts b/src/sequences-react/engine/command-stack.ts index d5335b2..c18fe26 100644 --- a/src/sequences-react/engine/command-stack.ts +++ b/src/sequences-react/engine/command-stack.ts @@ -17,6 +17,7 @@ import type { CommandStack, EditorTimelineState, TimelineCommand } from '../cont /** Oldest entries are dropped past this bound; redo is cleared on execute. */ export const COMMAND_HISTORY_LIMIT = 200 +/** Create a command stack managing undo and redo operations for a given timeline */ export function createCommandStack(initial: SequenceTimeline): CommandStack { /** View fields start at their neutral values; the host layer owns volatile * view state and treats these as initials, not a live channel. */ diff --git a/src/sequences-react/engine/commands.ts b/src/sequences-react/engine/commands.ts index 0b385df..7a08101 100644 --- a/src/sequences-react/engine/commands.ts +++ b/src/sequences-react/engine/commands.ts @@ -99,6 +99,7 @@ function removeClip(state: EditorTimelineState, clipId: string, context: string) // move_clip // --------------------------------------------------------------------------- +/** Define input parameters to move a clip within a timeline including optional track and resolver */ export interface MoveClipInput { timeline: SequenceTimeline clipId: string @@ -145,6 +146,7 @@ export function moveClipCommand(input: MoveClipInput): TimelineCommand { // trim_clip // --------------------------------------------------------------------------- +/** Define input parameters for trimming a clip within a sequence timeline */ export interface TrimClipInput { timeline: SequenceTimeline clipId: string @@ -197,6 +199,7 @@ export function trimClipCommand(input: TrimClipInput): TimelineCommand { // place_clip // --------------------------------------------------------------------------- +/** Define input parameters required to place a clip within a sequence timeline */ export interface PlaceClipInput { timeline: SequenceTimeline /** Caller-minted optimistic id for the local clip (see module header). */ @@ -214,6 +217,7 @@ export interface PlaceClipInput { resolveClipId?: ClipIdResolver } +/** Resolve and validate clip placement parameters to create a timeline command */ export function placeClipCommand(input: PlaceClipInput): TimelineCommand { const context = 'place_clip' assertNewClipId(input.timeline, input.clipId, context) @@ -271,6 +275,7 @@ export function placeClipCommand(input: PlaceClipInput): TimelineCommand { // delete_clip // --------------------------------------------------------------------------- +/** Define input parameters required to delete a clip from a sequence timeline */ export interface DeleteClipInput { timeline: SequenceTimeline clipId: string @@ -336,6 +341,7 @@ export function deleteClipCommand(input: DeleteClipInput): TimelineCommand { // split_clip // --------------------------------------------------------------------------- +/** Define input parameters for splitting a clip at a specific frame within a timeline */ export interface SplitClipInput { timeline: SequenceTimeline clipId: string @@ -409,6 +415,7 @@ export function splitClipCommand(input: SplitClipInput): TimelineCommand { // add_caption // --------------------------------------------------------------------------- +/** Define input parameters for adding a caption clip to a sequence timeline */ export interface AddCaptionInput { timeline: SequenceTimeline /** Caller-minted optimistic id for the local caption clip. */ @@ -423,6 +430,7 @@ export interface AddCaptionInput { resolveClipId?: ClipIdResolver } +/** Resolve a command to add a caption to a specified caption track within a timeline */ export function addCaptionCommand(input: AddCaptionInput): TimelineCommand { const context = 'add_caption' assertNewClipId(input.timeline, input.clipId, context) @@ -477,6 +485,7 @@ export function addCaptionCommand(input: AddCaptionInput): TimelineCommand { // set_clip_text // --------------------------------------------------------------------------- +/** Define input parameters for setting text and optional language on a specific clip in a timeline */ export interface SetClipTextInput { timeline: SequenceTimeline clipId: string @@ -542,6 +551,7 @@ export function setClipTextCommand(input: SetClipTextInput): TimelineCommand { // set_clip_disabled (toggle) // --------------------------------------------------------------------------- +/** Define input parameters to toggle the disabled state of a clip within a timeline */ export interface ToggleClipDisabledInput { timeline: SequenceTimeline clipId: string diff --git a/src/sequences-react/engine/playback.ts b/src/sequences-react/engine/playback.ts index 99c4368..6cb97b2 100644 --- a/src/sequences-react/engine/playback.ts +++ b/src/sequences-react/engine/playback.ts @@ -11,6 +11,7 @@ import type { PlaybackClock } from '../contracts' +/** Define configuration settings for playback clock including frames per second and total duration frames */ export interface PlaybackClockConfig { fps: number durationFrames: number @@ -43,6 +44,7 @@ function now(): number { return perf.now() } +/** Create a playback clock that manages frame timing and playback state based on configuration */ export function createPlaybackClock(config: PlaybackClockConfig): PlaybackClock { if (!Number.isInteger(config.fps) || config.fps <= 0) { throw new Error(`fps must be a positive integer, got ${config.fps}`) diff --git a/src/sequences-react/engine/snap.ts b/src/sequences-react/engine/snap.ts index 616921f..23fca1f 100644 --- a/src/sequences-react/engine/snap.ts +++ b/src/sequences-react/engine/snap.ts @@ -30,6 +30,7 @@ export function collectSnapPoints(timeline: SequenceTimeline, playheadFrame: num return points.sort((a, b) => a.frame - b.frame || a.kind.localeCompare(b.kind)) } +/** Define options to configure snapping behavior including zoom, threshold, and exclusion criteria */ export interface ApplySnapOptions { /** Pixels per frame — converts the pixel threshold into frames. */ zoom: number diff --git a/src/sequences-react/engine/zoom.ts b/src/sequences-react/engine/zoom.ts index ab5b03c..b684321 100644 --- a/src/sequences-react/engine/zoom.ts +++ b/src/sequences-react/engine/zoom.ts @@ -7,11 +7,13 @@ import type { ZoomMath } from '../contracts' +/** Define configuration settings for minimum and maximum zoom levels */ export interface ZoomMathConfig { minZoom: number maxZoom: number } +/** Create a ZoomMath object that validates config and calculates zoom ratio within bounds */ export function createZoomMath(config: ZoomMathConfig): ZoomMath { const { minZoom, maxZoom } = config if (!Number.isFinite(minZoom) || minZoom <= 0) { diff --git a/src/sequences-react/media/frame-provider.ts b/src/sequences-react/media/frame-provider.ts index 621592c..9330e1b 100644 --- a/src/sequences-react/media/frame-provider.ts +++ b/src/sequences-react/media/frame-provider.ts @@ -11,6 +11,7 @@ import type { VideoFrameProvider } from '../contracts' +/** Define the default maximum number of media elements allowed in a collection */ export const DEFAULT_MAX_MEDIA_ELEMENTS = 4 /** Half a frame at 30fps. Seeks closer than this repaint the decoder's @@ -21,6 +22,7 @@ export const SEEK_TOLERANCE_SECONDS = 1 / 60 * the draw REJECTS rather than painting whatever frame happens to be up. */ export const SEEK_TIMEOUT_MS = 5_000 +/** Define a rectangular frame with position and size properties x, y, width, and height */ export interface FrameRect { x: number y: number @@ -52,6 +54,7 @@ export function containFitRect( } } +/** Determine if seeking is required based on the difference between current and target times */ export function needsSeek(currentTimeSeconds: number, targetSeconds: number): boolean { return Math.abs(currentTimeSeconds - targetSeconds) >= SEEK_TOLERANCE_SECONDS } @@ -60,12 +63,14 @@ export function needsSeek(currentTimeSeconds: number, targetSeconds: number): bo // LRU element pool // --------------------------------------------------------------------------- +/** Manage a leased element from a pool and release it to enable LRU eviction */ export interface PooledElementLease { element: T /** Unpins the element; idle elements become LRU-evictable. Idempotent. */ release(): void } +/** Manage a pool of media elements to acquire, check, count, and dispose resources efficiently */ export interface MediaElementPool { acquire(url: string): PooledElementLease has(url: string): boolean diff --git a/src/sequences-react/media/transcription.ts b/src/sequences-react/media/transcription.ts index e982801..c95783c 100644 --- a/src/sequences-react/media/transcription.ts +++ b/src/sequences-react/media/transcription.ts @@ -10,6 +10,7 @@ import type { TranscriptionProvider, TranscriptionSegment } from '../contracts' import type { AudioBufferLike } from './waveform' +/** Provide the default Whisper model identifier for ONNX community large v3 turbo */ export const DEFAULT_WHISPER_MODEL = 'onnx-community/whisper-large-v3-turbo' /** Whisper models are trained on 16 kHz mono — decoding through a 16 kHz @@ -24,6 +25,7 @@ interface WhisperChunk { timestamp: [number, number | null] } +/** Define the structure for transcribed text output with optional segmented chunks */ export interface WhisperOutput { text: string chunks?: WhisperChunk[] @@ -124,6 +126,7 @@ async function fetchMonoAudio(mediaUrl: string): Promise<{ samples: Float32Array return { samples: mixdownToMono(decoded), durationSeconds: decoded.duration } } +/** Create a Whisper-based transcription provider with optional model configuration */ export function createWhisperTranscriptionProvider(opts?: { model?: string }): TranscriptionProvider { const model = opts?.model ?? DEFAULT_WHISPER_MODEL let availability: boolean | null = null diff --git a/src/sequences/apply.ts b/src/sequences/apply.ts index e176748..9bfc28a 100644 --- a/src/sequences/apply.ts +++ b/src/sequences/apply.ts @@ -72,6 +72,7 @@ export async function applySequenceOperations( return results } +/** Apply a sequence operation to update the store and timeline asynchronously */ export async function applySequenceOperation( store: SequenceStore, timeline: SequenceTimeline, diff --git a/src/sequences/captions.ts b/src/sequences/captions.ts index cd7c471..732212f 100644 --- a/src/sequences/captions.ts +++ b/src/sequences/captions.ts @@ -33,6 +33,7 @@ export interface CaptionChunk { durationFrames: number } +/** Define options to configure caption chunk size, duration, and frame rate constraints */ export interface BuildCaptionChunksOptions { /** Upper bound on words per caption; segments split on word boundaries. */ maxWordsPerChunk?: number @@ -147,6 +148,7 @@ export function normalizeLanguageTag(tag: string): string { return normalized } +/** Define options to specify target languages and an optional source language for fan-out operations */ export interface LanguageFanoutOptions { languages: string[] /** Excluded from the plan (exact normalized match only — 'en' does not diff --git a/src/sequences/drizzle-store.ts b/src/sequences/drizzle-store.ts index cdadefe..0c022a3 100644 --- a/src/sequences/drizzle-store.ts +++ b/src/sequences/drizzle-store.ts @@ -54,6 +54,7 @@ export type SequenceDatabase = BaseSQLiteDatabase<'sync' | 'async', any, any> * of clip rows. Keyed by clip id; clips absent from the map carry no media. */ export type SequenceMediaResolver = (clipRows: SequenceClipRow[]) => Promise> +/** Define options for creating a Drizzle sequence store including database, tables, scope, and media resolver */ export interface CreateDrizzleSequenceStoreOptions { db: SequenceDatabase tables: SequenceTables @@ -63,6 +64,7 @@ export interface CreateDrizzleSequenceStoreOptions { const DEFAULT_LIST_LIMIT = 50 +/** Create a sequence store scoped to a specific sequence and workspace with database access and media resolution */ export function createDrizzleSequenceStore(options: CreateDrizzleSequenceStoreOptions): SequenceStore { const { db, tables, scope, resolveMedia } = options const { sequences, sequenceTracks, sequenceClips, sequenceDecisions, sequenceExports } = tables diff --git a/src/sequences/exports.ts b/src/sequences/exports.ts index 83ad9e8..895fc29 100644 --- a/src/sequences/exports.ts +++ b/src/sequences/exports.ts @@ -29,6 +29,7 @@ import { // Captions: SRT / WebVTT // --------------------------------------------------------------------------- +/** Define options to export captions filtered by an optional BCP-47 language tag */ export interface CaptionExportOptions { /** BCP-47 tag; matched case-insensitively against `clip.language`. Clips * with no language never match a language-scoped export. */ @@ -167,18 +168,21 @@ function frameToEdlTimecode(frame: number, fps: number): string { // OpenTimelineIO // --------------------------------------------------------------------------- +/** Represent a rational time value with a specific rate and numeric value for OTIO schema */ export interface OtioRationalTime { OTIO_SCHEMA: 'RationalTime.1' rate: number value: number } +/** Define a time range with a start time and duration using OtioRationalTime values */ export interface OtioTimeRange { OTIO_SCHEMA: 'TimeRange.1' start_time: OtioRationalTime duration: OtioRationalTime } +/** Define the structure for an external media reference with schema, URL, and optional time range */ export interface OtioExternalReference { OTIO_SCHEMA: 'ExternalReference.1' target_url: string @@ -186,16 +190,19 @@ export interface OtioExternalReference { available_range: OtioTimeRange | null } +/** Represent missing references in OTIO with a fixed schema identifier */ export interface OtioMissingReference { OTIO_SCHEMA: 'MissingReference.1' } +/** Define the structure for a gap element with schema, name, and source time range properties */ export interface OtioGap { OTIO_SCHEMA: 'Gap.1' name: string source_range: OtioTimeRange } +/** Define a clip object with metadata, source range, and media reference according to OTIO schema */ export interface OtioClip { OTIO_SCHEMA: 'Clip.2' name: string @@ -204,6 +211,7 @@ export interface OtioClip { metadata: Record } +/** Define a track containing video or audio clips with metadata and child elements */ export interface OtioTrack { OTIO_SCHEMA: 'Track.1' name: string @@ -212,12 +220,14 @@ export interface OtioTrack { children: Array } +/** Represent a stack container holding a named collection of OtioTrack children */ export interface OtioStack { OTIO_SCHEMA: 'Stack.1' name: string children: OtioTrack[] } +/** Define the structure of a timeline with metadata, tracks, and global start time in OTIO format */ export interface OtioTimeline { OTIO_SCHEMA: 'Timeline.1' name: string @@ -342,6 +352,7 @@ function timeRange(startValue: number, durationValue: number, rate: number): Oti // Contact-sheet manifest // --------------------------------------------------------------------------- +/** Describe a single entry in a contact sheet with timing and media source details */ export interface ContactSheetEntry { clipId: string trackId: string @@ -358,6 +369,7 @@ export interface ContactSheetEntry { mediaKind: SequenceMediaKind } +/** Define the structure for a contact sheet manifest including metadata and entries */ export interface ContactSheetManifest { sequenceId: string title: string diff --git a/src/sequences/mcp-entry.ts b/src/sequences/mcp-entry.ts index b9cead9..a8a9b61 100644 --- a/src/sequences/mcp-entry.ts +++ b/src/sequences/mcp-entry.ts @@ -10,9 +10,11 @@ import { buildScopedMcpServerEntry } from '../tools/mcp' import type { AppToolMcpServer, ScopedMcpServerEntryOptions } from '../tools/mcp' +/** Describe live timeline editor features for current video sequence including clip and caption management */ export const DEFAULT_SEQUENCES_MCP_DESCRIPTION = 'Live timeline editor for the current video sequence: read timeline state, place/move/trim/split clips, add captions, manage tracks, and queue exports. All times are seconds.' +/** Extend ScopedMcpServerEntryOptions to configure MCP server entry options for sequence building */ export type BuildSequencesMcpServerEntryOptions = ScopedMcpServerEntryOptions /** Build the `AgentProfileMcpServer`-shaped entry for the sequences channel. */ diff --git a/src/sequences/mcp-handler.ts b/src/sequences/mcp-handler.ts index 11c8930..c605ff3 100644 --- a/src/sequences/mcp-handler.ts +++ b/src/sequences/mcp-handler.ts @@ -28,11 +28,13 @@ import type { McpToolDefinition } from '../tools/mcp-rpc' * name to keep the public surface stable without a second source of truth. */ export { MCP_PROTOCOL_VERSIONS as SEQUENCES_MCP_PROTOCOL_VERSIONS } from '../tools/mcp-rpc' +/** Describe server information including name and version for Sequences MCP integration */ export interface SequencesMcpServerInfo { name: string version: string } +/** Define options for creating sequences MCP handler including store, playhead frame, and server info */ export interface CreateSequencesMcpHandlerOptions { /** Already scoped + authorized for one (workspace, sequence, actor). */ store: SequenceStore @@ -42,6 +44,7 @@ export interface CreateSequencesMcpHandlerOptions { serverInfo?: SequencesMcpServerInfo } +/** Create a handler to process MCP sequence requests with optional playhead frame and server info */ export function createSequencesMcpHandler( opts: CreateSequencesMcpHandlerOptions, ): (request: Request) => Promise { diff --git a/src/sequences/mcp-tools.ts b/src/sequences/mcp-tools.ts index e40c96b..39369e5 100644 --- a/src/sequences/mcp-tools.ts +++ b/src/sequences/mcp-tools.ts @@ -51,6 +51,7 @@ export interface SequenceMcpToolEnv { playheadFrame: number } +/** Define a tool with metadata and a run method for processing input within a specific environment */ export interface SequenceMcpToolDefinition { name: string description: string @@ -62,10 +63,13 @@ export interface SequenceMcpToolDefinition { // Enumerations (value-level twins of the model's type unions) // --------------------------------------------------------------------------- +/** Define supported export formats for sequence outputs including video, subtitle, and metadata types */ export const SEQUENCE_EXPORT_FORMATS = ['mp4', 'otio', 'xml', 'edl', 'vtt', 'srt', 'contact_sheet'] as const satisfies readonly SequenceExportFormat[] +/** Define immutable sequence track kinds for video, audio, caption, reference, and agent */ export const SEQUENCE_TRACK_KINDS = ['video', 'audio', 'caption', 'reference', 'agent'] as const satisfies readonly SequenceTrackKind[] +/** Define the allowed media kinds for sequences including video, image, and audio */ export const SEQUENCE_MEDIA_KINDS = ['video', 'image', 'audio'] as const satisfies readonly SequenceMediaKind[] /** Largest accepted `add_captions` batch — bounds one decision row / one @@ -361,6 +365,7 @@ const CLIP_ID_SCHEMA = { type: 'string', description: 'Clip id from get_timeline // The registry // --------------------------------------------------------------------------- +/** Resolve an array of immutable sequence MCP tool definitions for timeline and frame operations */ export const SEQUENCE_MCP_TOOLS: readonly SequenceMcpToolDefinition[] = [ { name: 'get_timeline_state', @@ -780,6 +785,7 @@ export const SEQUENCE_MCP_TOOLS: readonly SequenceMcpToolDefinition[] = [ }, ] +/** Resolve the SequenceMcpToolDefinition matching the given name or return undefined */ export function findSequenceMcpTool(name: string): SequenceMcpToolDefinition | undefined { return SEQUENCE_MCP_TOOLS.find((tool) => tool.name === name) } diff --git a/src/sequences/model.ts b/src/sequences/model.ts index bb7c023..873b6ec 100644 --- a/src/sequences/model.ts +++ b/src/sequences/model.ts @@ -18,14 +18,19 @@ export const MIN_SEQUENCE_CLIP_FRAMES = 1 * agent-decision lane rendered as markers, never as media. */ export type SequenceTrackKind = 'video' | 'audio' | 'caption' | 'reference' | 'agent' +/** Define sequence status as one of the specific lifecycle stages draft, active, exporting, or archived */ export type SequenceStatus = 'draft' | 'active' | 'exporting' | 'archived' +/** Define export formats available for sequence data including video, subtitle, and metadata types */ export type SequenceExportFormat = 'mp4' | 'otio' | 'xml' | 'edl' | 'vtt' | 'srt' | 'contact_sheet' +/** Represent export status of a sequence as queued, processing, completed, failed, or cancelled */ export type SequenceExportStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled' +/** Define media types allowed in a sequence including video, image, and audio */ export type SequenceMediaKind = 'video' | 'image' | 'audio' +/** Describe metadata and properties of a media sequence including dimensions, duration, and status */ export interface SequenceMeta { id: string title: string @@ -38,6 +43,7 @@ export interface SequenceMeta { metadata: Record } +/** Define properties and state for a sequence track including id, kind, name, order, and flags */ export interface SequenceTrack { id: string kind: SequenceTrackKind @@ -60,6 +66,7 @@ export interface SequenceClipMedia { providerStatus?: 'queued' | 'processing' | 'completed' | 'failed' } +/** Define properties for a media sequence clip including timing, source, track, and caption details */ export interface SequenceClip { id: string trackId: string @@ -97,6 +104,7 @@ export interface SequenceDecision { createdAt: Date } +/** Describe a record representing the export details and status of a sequence */ export interface SequenceExportRecord { id: string format: SequenceExportFormat @@ -129,18 +137,21 @@ export interface SequenceFrameSnapshot { // Frame math // --------------------------------------------------------------------------- +/** Convert seconds to the nearest whole number of frames based on frames per second */ export function secondsToFrames(seconds: number, fps: number): number { if (!Number.isFinite(seconds) || seconds < 0) throw new Error('seconds must be a non-negative finite number') assertFps(fps) return Math.round(seconds * fps) } +/** Convert a frame count to seconds based on the given frames per second rate */ export function framesToSeconds(frames: number, fps: number): number { if (!Number.isInteger(frames) || frames < 0) throw new Error('frames must be a non-negative integer') assertFps(fps) return frames / fps } +/** Format a number of seconds into a string with integer or two-decimal precision suffix s */ export function formatSeconds(seconds: number): string { return Number.isInteger(seconds) ? `${seconds}s` : `${seconds.toFixed(2)}s` } @@ -156,16 +167,19 @@ export function formatTimecode(frames: number, fps: number): string { return `${minutes}:${String(seconds).padStart(2, '0')}.${String(residualFrames).padStart(2, '0')}` } +/** Define the start frame and duration in frames for a timeline clip's bounds */ export interface TimelineClipBounds { startFrame: number durationFrames: number } +/** Define a time range with inclusive start and end frame numbers */ export interface TimelineInterval { startFrame: number endFrame: number } +/** Clamp the clip start frame within the valid range of the sequence duration and clip length */ export function clampClipStart(input: { startFrame: number durationFrames: number @@ -176,6 +190,7 @@ export function clampClipStart(input: { return Math.max(0, Math.min(input.sequenceDurationFrames - input.durationFrames, input.startFrame)) } +/** Clamp clip duration to fit within sequence bounds and minimum length constraints */ export function clampClipDuration(input: { startFrame: number durationFrames: number @@ -188,6 +203,7 @@ export function clampClipDuration(input: { return Math.max(MIN_SEQUENCE_CLIP_FRAMES, Math.min(input.durationFrames, input.sequenceDurationFrames - input.startFrame)) } +/** Validate that a clip's start and duration fit within the sequence duration without overflow */ export function assertClipFitsSequence(input: { startFrame: number durationFrames: number diff --git a/src/sequences/operations.ts b/src/sequences/operations.ts index 1558f44..749c994 100644 --- a/src/sequences/operations.ts +++ b/src/sequences/operations.ts @@ -14,6 +14,7 @@ import type { SequenceExportFormat, SequenceTrackKind } from './model' +/** Define an operation to place a media clip with timing, track, and playback options */ export interface PlaceClipOperation { type: 'place_clip' /** Omitted → first unlocked track matching the media kind. */ @@ -35,6 +36,7 @@ export interface PlaceClipOperation { metadata?: Record } +/** Add a caption with optional language, timing, and track placement details */ export interface AddCaptionOperation { type: 'add_caption' text: string @@ -48,6 +50,7 @@ export interface AddCaptionOperation { trackId?: string } +/** Resolve an operation to move a clip to a new start frame and optional track */ export interface MoveClipOperation { type: 'move_clip' clipId: string @@ -55,6 +58,7 @@ export interface MoveClipOperation { trackId?: string } +/** Define an operation to trim a clip by adjusting its start, duration, and optional source in/out points */ export interface TrimClipOperation { type: 'trim_clip' clipId: string @@ -69,6 +73,7 @@ export interface TrimClipOperation { sourceOutFrame?: number | null } +/** Split a clip at a specified frame inside the clip to create two separate segments */ export interface SplitClipOperation { type: 'split_clip' clipId: string @@ -76,6 +81,7 @@ export interface SplitClipOperation { atFrame: number } +/** Resolve an operation to set clipboard text with optional language and clip identifier */ export interface SetClipTextOperation { type: 'set_clip_text' clipId: string @@ -83,34 +89,40 @@ export interface SetClipTextOperation { language?: string } +/** Define an operation to enable or disable a clip by its identifier */ export interface SetClipDisabledOperation { type: 'set_clip_disabled' clipId: string disabled: boolean } +/** Represent a delete clip operation with a specified clip identifier */ export interface DeleteClipOperation { type: 'delete_clip' clipId: string } +/** Define an operation to create a new sequence track with a specified kind and name */ export interface CreateTrackOperation { type: 'create_track' kind: SequenceTrackKind name: string } +/** Define an operation to extend a sequence by a specified number of frames */ export interface ExtendSequenceOperation { type: 'extend_sequence' durationFrames: number } +/** Define the structure for a queue export operation with format and optional metadata */ export interface QueueExportOperation { type: 'queue_export' format: SequenceExportFormat metadata?: Record } +/** Represent sequence editing actions for manipulating clips, tracks, captions, and exports */ export type SequenceOperation = | PlaceClipOperation | AddCaptionOperation @@ -131,8 +143,10 @@ export interface SequencePlan { operations: SequenceOperation[] } +/** Extract the type of operation from a sequence operation object */ export type SequenceOperationType = SequenceOperation['type'] +/** List all valid sequence operation types used in editing workflows */ export const SEQUENCE_OPERATION_TYPES: readonly SequenceOperationType[] = [ 'place_clip', 'add_caption', diff --git a/src/sequences/schema.ts b/src/sequences/schema.ts index c2af318..9670720 100644 --- a/src/sequences/schema.ts +++ b/src/sequences/schema.ts @@ -22,6 +22,7 @@ import type { AnySQLiteColumn, AnySQLiteTable } from 'drizzle-orm/sqlite-core' /** A product table referenced by FK — only the `id` column is touched. */ export type SequenceParentTable = AnySQLiteTable & { id: AnySQLiteColumn } +/** Define options for creating sequence-related database tables including workspace and user tables */ export interface CreateSequenceTablesOptions { workspaceTable: SequenceParentTable userTable: SequenceParentTable @@ -37,6 +38,7 @@ const createdAt = () => integer('created_at', { mode: 'timestamp' }).notNull().d const updatedAt = () => integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`) +/** Build SQLite sequence tables with defined columns and relationships based on provided options */ export function createSequenceTables(opts: CreateSequenceTablesOptions) { const { workspaceTable, userTable, generationTable, assetTable } = opts @@ -142,10 +144,16 @@ export function createSequenceTables(opts: CreateSequenceTablesOptions) { return { sequences, sequenceTracks, sequenceClips, sequenceDecisions, sequenceExports } } +/** Resolve sequence tables by invoking the createSequenceTables factory function */ export type SequenceTables = ReturnType +/** Resolve a sequence row by inferring the selected fields from the sequences table */ export type SequenceRow = SequenceTables['sequences']['$inferSelect'] +/** Resolve the selected sequence track row from the sequenceTracks table */ export type SequenceTrackRow = SequenceTables['sequenceTracks']['$inferSelect'] +/** Resolve the selected fields of sequence clips from the sequence tables data structure */ export type SequenceClipRow = SequenceTables['sequenceClips']['$inferSelect'] +/** Resolve a sequence decision row from the sequenceDecisions table data */ export type SequenceDecisionRow = SequenceTables['sequenceDecisions']['$inferSelect'] +/** Resolve a row type representing exported sequence data from sequenceExports table */ export type SequenceExportRow = SequenceTables['sequenceExports']['$inferSelect'] diff --git a/src/sequences/store.ts b/src/sequences/store.ts index 709b868..419e369 100644 --- a/src/sequences/store.ts +++ b/src/sequences/store.ts @@ -24,12 +24,14 @@ import type { SequenceTrackKind, } from './model' +/** Define properties for a new sequence track including kind, name, and optional sort order */ export interface NewSequenceTrack { kind: SequenceTrackKind name: string sortOrder?: number } +/** Define properties for a new sequence clip including timing, labels, and optional metadata */ export interface NewSequenceClip { trackId: string label: string @@ -44,6 +46,7 @@ export interface NewSequenceClip { metadata?: Record } +/** Define optional properties to update or patch a sequence clip's attributes in a timeline */ export interface SequenceClipPatch { trackId?: string label?: string @@ -57,6 +60,7 @@ export interface SequenceClipPatch { metadata?: Record } +/** Define the structure for a new sequence decision with optional metadata and acceptance status */ export interface NewSequenceDecision { clipId?: string | null kind: SequenceDecision['kind'] @@ -66,6 +70,7 @@ export interface NewSequenceDecision { metadata?: Record } +/** Manage sequences by providing methods to get timelines, clips, and modify tracks and clips */ export interface SequenceStore { /** Full aggregate: sequence meta + tracks + clips with resolved media. */ getTimeline(): Promise diff --git a/src/sequences/validate.ts b/src/sequences/validate.ts index 1a15ab2..4cc62c7 100644 --- a/src/sequences/validate.ts +++ b/src/sequences/validate.ts @@ -79,6 +79,7 @@ const MEDIA_KINDS: Record = { * without shipping a full registry. */ const LANGUAGE_TAG = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$/ +/** Validate each operation in a sequence against the timeline and context, throwing detailed errors on failure */ export function validateSequenceOperations( timeline: SequenceTimeline, operations: SequenceOperation[], @@ -95,6 +96,7 @@ export function validateSequenceOperations( }) } +/** Validate a sequence operation against the timeline and context to ensure correctness */ export function validateSequenceOperation( timeline: SequenceTimeline, operation: SequenceOperation, @@ -132,6 +134,7 @@ export function validateSequenceOperation( } } +/** Validate the properties and constraints of a PlaceClipOperation within a SequenceTimeline */ export function validatePlaceClip(timeline: SequenceTimeline, operation: PlaceClipOperation): void { if (operation.label.trim().length === 0) throw new Error('label must be non-empty') if (operation.media) { @@ -148,6 +151,7 @@ export function validatePlaceClip(timeline: SequenceTimeline, operation: PlaceCl resolvePlaceClipTrack(timeline, operation) } +/** Validate the parameters and context of an AddCaptionOperation within a sequence timeline */ export function validateAddCaption( timeline: SequenceTimeline, operation: AddCaptionOperation, @@ -169,6 +173,7 @@ export function validateAddCaption( } } +/** Validate that a clip move operation is within bounds and targets a compatible unlocked track */ export function validateMoveClip(timeline: SequenceTimeline, operation: MoveClipOperation): void { const { clip, track } = requireMutableClip(timeline, operation.clipId) assertOperationBounds(timeline, { startFrame: operation.startFrame, durationFrames: clip.durationFrames }) @@ -181,6 +186,7 @@ export function validateMoveClip(timeline: SequenceTimeline, operation: MoveClip } } +/** Validate that a trim clip operation respects timeline bounds and source frame constraints */ export function validateTrimClip(timeline: SequenceTimeline, operation: TrimClipOperation): void { const { clip } = requireMutableClip(timeline, operation.clipId) if (operation.sourceInFrame !== undefined) assertSourceInFrame(operation.sourceInFrame) @@ -194,6 +200,7 @@ export function validateTrimClip(timeline: SequenceTimeline, operation: TrimClip assertSourceWindow(sourceInFrame, sourceOutFrame, operation.durationFrames) } +/** Validate that a split operation on a clip is within valid frame boundaries and conditions */ export function validateSplitClip(timeline: SequenceTimeline, operation: SplitClipOperation): void { const { clip } = requireMutableClip(timeline, operation.clipId) if (!Number.isInteger(operation.atFrame)) throw new Error('atFrame must be an integer') @@ -208,6 +215,7 @@ export function validateSplitClip(timeline: SequenceTimeline, operation: SplitCl } } +/** Validate that a SetClipTextOperation targets a caption clip with non-empty text and valid language tag */ export function validateSetClipText(timeline: SequenceTimeline, operation: SetClipTextOperation): void { const { track } = requireMutableClip(timeline, operation.clipId) if (track.kind !== 'caption') { @@ -219,19 +227,23 @@ export function validateSetClipText(timeline: SequenceTimeline, operation: SetCl if (operation.language !== undefined) assertLanguageTag(operation.language) } +/** Validate that the clip can be disabled within the given timeline and operation constraints */ export function validateSetClipDisabled(timeline: SequenceTimeline, operation: SetClipDisabledOperation): void { requireMutableClip(timeline, operation.clipId) } +/** Validate that the clip to delete exists and is mutable in the given timeline */ export function validateDeleteClip(timeline: SequenceTimeline, operation: DeleteClipOperation): void { requireMutableClip(timeline, operation.clipId) } +/** Validate that a CreateTrackOperation has a supported kind and a non-empty name */ export function validateCreateTrack(operation: CreateTrackOperation): void { if (!(operation.kind in TRACK_KINDS)) throw new Error(`unsupported track kind ${JSON.stringify(operation.kind)}`) if (operation.name.trim().length === 0) throw new Error('name must be non-empty') } +/** Validate that the extend sequence operation has a positive duration and exceeds the last clip end frame */ export function validateExtendSequence(timeline: SequenceTimeline, operation: ExtendSequenceOperation): void { if (!Number.isInteger(operation.durationFrames) || operation.durationFrames <= 0) { throw new Error('durationFrames must be a positive integer') @@ -242,6 +254,7 @@ export function validateExtendSequence(timeline: SequenceTimeline, operation: Ex } } +/** Validate that the queue export operation uses a supported export format */ export function validateQueueExport(operation: QueueExportOperation): void { if (!(operation.format in EXPORT_FORMATS)) { throw new Error(`unsupported export format ${JSON.stringify(operation.format)}`) @@ -429,6 +442,7 @@ function describeJsonValue(value: unknown): string { // Resolution helpers — shared with ./apply // --------------------------------------------------------------------------- +/** Resolve caption target by specifying an existing track or creating a new one with language and name */ export type CaptionTargetResolution = | { kind: 'existing'; track: SequenceTrack } | { kind: 'create'; language: string; name: string } diff --git a/src/store/index.ts b/src/store/index.ts index b97f1c9..44b1b7b 100644 --- a/src/store/index.ts +++ b/src/store/index.ts @@ -28,6 +28,7 @@ export interface DatabaseProvider { reset(): void } +/** Define options for configuring database provider behavior including error messaging */ export interface DatabaseProviderOptions { /** Error thrown when `db` is accessed before injection. Keep the product's * existing wording so callers see a familiar message. */ @@ -80,23 +81,27 @@ export function createDatabaseProvider( // `KVNamespace` satisfies it structurally, so prod passes the binding unchanged, // and `createInMemoryKV()` supplies the portable adapter for sandbox/eval. +/** Describe the result of listing keys with completion status and optional pagination cursor */ export interface KVListResult { keys: { name: string }[] list_complete: boolean cursor?: string } +/** Define options for storing a key-value pair with expiration and metadata settings */ export interface KVPutOptions { expiration?: number expirationTtl?: number metadata?: unknown } +/** Resolve a key-value pair retrieval including its associated metadata and value */ export interface KVGetWithMetadataResult { value: string | null metadata: unknown | null } +/** Define a key-value store interface for asynchronous data retrieval, storage, deletion, and listing */ export interface KVStore { get(key: string): Promise /** Read a value with its stored metadata (e.g. the vault's encrypted/hasPII flags). */ diff --git a/src/stream/stream-normalizer.ts b/src/stream/stream-normalizer.ts index 6d96001..971544d 100644 --- a/src/stream/stream-normalizer.ts +++ b/src/stream/stream-normalizer.ts @@ -11,23 +11,28 @@ import { type ChatPlanStatus, } from '../plans/index' +/** Represent a JSON-compatible object with string keys and values of any type */ export type JsonRecord = Record +/** Define an event object carrying a type and optional JSON data payload */ export interface StreamEvent { type: string data?: JsonRecord } +/** Resolve an unknown value to a JsonRecord if it is a non-array object or return undefined */ export function asRecord(value: unknown): JsonRecord | undefined { return value && typeof value === 'object' && !Array.isArray(value) ? value as JsonRecord : undefined } +/** Resolve a non-empty string from a value or return undefined */ export function asString(value: unknown): string | undefined { return typeof value === 'string' && value.length > 0 ? value : undefined } +/** Resolve a unique tool identifier from various possible properties or generate a fallback ID */ export function resolveToolId(part: JsonRecord): string { return String( part.id ?? @@ -41,10 +46,12 @@ export function resolveToolId(part: JsonRecord): string { ) } +/** Resolve the tool name from a JSON record using tool, name, or a default value */ export function resolveToolName(part: JsonRecord): string { return String(part.tool ?? part.name ?? 'tool') } +/** Resolve time properties from various keys into a normalized record with numeric start and end fields */ export function normalizeTime(value: unknown): JsonRecord | undefined { const record = asRecord(value) if (!record) return undefined @@ -59,6 +66,7 @@ export function normalizeTime(value: unknown): JsonRecord | undefined { } } +/** Normalize tool-related events into a standardized message.part.updated format */ export function normalizeToolEvent(event: StreamEvent): StreamEvent { if (event.type === 'tool_call' || event.type === 'tool.call') { const data = event.data ?? {} @@ -97,6 +105,7 @@ export function normalizeToolEvent(event: StreamEvent): StreamEvent { return event } +/** Normalize a persisted part object by standardizing its structure and fields */ export function normalizePersistedPart(rawPart: JsonRecord): JsonRecord | null { const type = String(rawPart.type ?? '') @@ -225,6 +234,7 @@ export function attachmentPartKey(path: string): string { return `attachment:${path}` } +/** Resolve a unique key string for a part based on its type and identifying properties */ export function getPartKey(part: JsonRecord): string { const type = String(part.type ?? 'unknown') if (type === 'tool') { @@ -251,6 +261,7 @@ function overlayDefined(base: JsonRecord, patch: JsonRecord): JsonRecord { return out } +/** Merge incoming JSON with existing persisted data, applying delta for text types when provided */ export function mergePersistedPart(existing: JsonRecord | undefined, incoming: JsonRecord, delta?: string): JsonRecord { const type = String(incoming.type ?? '') if (!existing) { @@ -346,7 +357,9 @@ export function mergePersistedPart(existing: JsonRecord | undefined, incoming: J return incoming } +/** Resolve errors when a tool fails to report a terminal result before the assistant turn ends */ export const MISSING_TOOL_TERMINAL_ERROR = 'Tool did not report a terminal result before the assistant turn completed.' +/** Provide the reason identifier for a missing tool in the terminal environment */ export const MISSING_TOOL_TERMINAL_REASON = 'missing-tool-terminal' /** Closes a tool part left `running` when a stream ended abnormally: settles @@ -375,6 +388,7 @@ export function terminalizeDanglingToolPart(part: JsonRecord): JsonRecord { } } +/** Resolve dangling tool parts into terminal forms within the given JSON records array */ export function terminalizeDanglingToolParts(parts: JsonRecord[]): JsonRecord[] { return parts.map(terminalizeDanglingToolPart) } @@ -472,6 +486,7 @@ function assembleAssistantParts( .map((part) => (part === lastTextPart ? { ...part, text: finalText } : part)) } +/** Resolve and clean up assistant parts by terminalizing and collapsing redundant segments */ export function finalizeAssistantParts( partOrder: string[], partMap: Map, @@ -515,6 +530,7 @@ export function terminalizeDanglingAssistantToolUpdates( return updates } +/** Encode a StreamEvent object into a Uint8Array using the provided TextEncoder */ export function encodeEvent(encoder: TextEncoder, event: StreamEvent): Uint8Array { return encoder.encode(`${JSON.stringify(event)}\n`) } diff --git a/src/stream/turn-buffer.ts b/src/stream/turn-buffer.ts index ee1e40a..126aebc 100644 --- a/src/stream/turn-buffer.ts +++ b/src/stream/turn-buffer.ts @@ -18,12 +18,14 @@ export type TurnStatus = 'running' | 'complete' | 'error' +/** Represent a buffered turn event with a sequence number and serialized event data */ export interface BufferedTurnEvent { seq: number /** The serialized event line (JSON string, no trailing newline). */ event: string } +/** Manage and query turn events and their lifecycle statuses within a scoped event store */ export interface TurnEventStore { append(turnId: string, events: BufferedTurnEvent[]): Promise read(turnId: string, fromSeq: number): Promise @@ -119,6 +121,7 @@ export function coalesceChatStreamEvents(events: unknown[]): unknown[] { // ── buffering core (the tap) ──────────────────────────────────────────────── +/** Define options for buffering and flushing turn events with optional live client delivery and event coalescing */ export interface BufferedTurnOptions { store: TurnEventStore turnId: string @@ -218,6 +221,7 @@ export function createBufferedTurnTap(opts: BufferedTurnOptions): BufferedTurnTa // ── pump (producer side) ────────────────────────────────────────────────── +/** Define options to pump data from an asynchronous iterable source with buffered turn control */ export interface PumpBufferedTurnOptions extends BufferedTurnOptions { source: AsyncIterable } @@ -243,6 +247,7 @@ export async function pumpBufferedTurn(opts: PumpBufferedTurnOptions): Promise> | null } +/** Represent a chat turn with resolved user message insertion and prior message context */ export interface ResolvedChatTurn { turnIndex: number shouldInsertUserMessage: boolean @@ -14,6 +16,7 @@ export interface ResolvedChatTurn { userParts: JsonRecord[] } +/** Normalize and validate a client turn ID string ensuring it meets format and length requirements */ export function normalizeClientTurnId(value: unknown): string | undefined { if (value === undefined || value === null) return undefined if (typeof value !== 'string') throw new Error('turnId must be a string') @@ -26,12 +29,14 @@ export function normalizeClientTurnId(value: unknown): string | undefined { return trimmed } +/** Build an array of text parts with optional turn ID for user input */ export function buildUserTextParts(text: string, turnId: string | undefined): JsonRecord[] { const part: JsonRecord = { type: 'text', text } if (turnId) part.turnId = turnId return [part] } +/** Resolve whether a message contains any part with the specified turn ID */ export function messageHasTurnId(message: PersistedChatMessageForTurn, turnId: string): boolean { for (const part of message.parts ?? []) { if (part && typeof part === 'object' && String(part.turnId ?? '') === turnId) { @@ -41,6 +46,7 @@ export function messageHasTurnId(message: PersistedChatMessageForTurn, turnId: s return false } +/** Resolve a chat turn by determining message reuse and constructing user message parts */ export function resolveChatTurn(input: { existingMessages: PersistedChatMessageForTurn[] userContent: string diff --git a/src/studio-react/type-config.ts b/src/studio-react/type-config.ts index 1c3c4a6..4c442cb 100644 --- a/src/studio-react/type-config.ts +++ b/src/studio-react/type-config.ts @@ -1,5 +1,6 @@ import { Film, FileText, Image, Mic, Video } from 'lucide-react' +/** Define configuration options for a type including label, icon, and color properties */ export interface TypeConfig { label: string icon: typeof Image @@ -9,6 +10,7 @@ export interface TypeConfig { const IMAGE: TypeConfig = { label: 'Image', icon: Image, color: 'bg-blue-500/10 text-blue-600 border-blue-500/20' } // string-keyed so list cards can index by Generation.type +/** Map type keys to their corresponding configuration objects including labels, icons, and colors */ export const TYPE_CONFIG: Record = { image: IMAGE, video: { label: 'Video', icon: Video, color: 'bg-red-500/10 text-red-600 border-red-500/20' }, @@ -20,6 +22,7 @@ export const TYPE_CONFIG: Record = { // Safe lookup for an arbitrary `Generation.type` — always defined (the table is // declared `Record`, so a raw index is `T | undefined`). Falls back // to the image config, matching the prior `?? TYPE_CONFIG.image` call sites. +/** Resolve the configuration object for a given type or return the default image configuration */ export function typeConfigFor(type: string): TypeConfig { return TYPE_CONFIG[type] ?? IMAGE } diff --git a/src/studio/generation.ts b/src/studio/generation.ts index cf651bd..48d3b66 100644 --- a/src/studio/generation.ts +++ b/src/studio/generation.ts @@ -4,18 +4,23 @@ // design-system package. A sandbox-ui `IntegrationConnection` is assignable to // this; `connectorId` is optional because the engine type leaves it undefined // for connections established without a named connector. +/** Define the structure for a studio integration connection with status and provider identifiers */ export interface StudioIntegrationConnection { status: string providerId: string connectorId?: string } +/** Define generation categories for media including image, video, speech, avatar, and transcription */ export type GenerationType = 'image' | 'video' | 'speech' | 'avatar' | 'transcription' +/** Define possible states representing the progress of a generation process */ export type GenerationStatus = 'pending' | 'running' | 'succeeded' | 'failed' +/** Define possible status values for a media model's availability and accessibility */ export type MediaModelStatus = 'available' | 'limited' | 'unavailable' +/** Define the structure for a generation entity including its metadata and creation details */ export interface Generation { id: string type: string @@ -27,6 +32,7 @@ export interface Generation { metadata: Record | null } +/** Describe media model option properties including id, name, type, status, and optional provider and reason */ export interface MediaModelOption { id: string name: string @@ -36,12 +42,14 @@ export interface MediaModelOption { reason?: string } +/** Represent media model catalog with default values, model options, and optional error message */ export interface MediaModelCatalogResponse { defaults: Record models: Record error?: string } +/** Define the structure for configuring package publishing details and evaluation criteria */ export interface PublishPackage { caption: string description: string @@ -55,6 +63,7 @@ export interface PublishPackage { } } +/** Define a destination for publishing content with identifiers, label, provider IDs, and fields */ export interface PublishDestination { id: string label: string @@ -63,12 +72,15 @@ export interface PublishDestination { } // Order drives the type filter tabs and the composer segmented control +/** Provide an array of supported generation types for media and content processing */ export const GENERATION_TYPES: readonly GenerationType[] = ['image', 'video', 'avatar', 'speech', 'transcription'] +/** Resolve whether a string value matches a valid GenerationType */ export function isGenerationType(value: string): value is GenerationType { return (GENERATION_TYPES as readonly string[]).includes(value) } +/** List available social media platforms with their publishing fields and provider identifiers */ export const DESTINATIONS: PublishDestination[] = [ { id: 'instagram', label: 'Instagram', providerIds: ['instagram'], fields: 'Caption, hashtags, crop' }, { id: 'tiktok', label: 'TikTok', providerIds: ['tiktok'], fields: 'Caption, audio note, vertical video' }, @@ -77,11 +89,15 @@ export const DESTINATIONS: PublishDestination[] = [ { id: 'x', label: 'X', providerIds: ['twitter'], fields: 'Short copy, mentions, thread option' }, ] +/** Provide an array of predefined cadence options for scheduling or approval processes */ export const CADENCES = ['Manual approval', 'Publish now', 'Daily creative drop', 'Weekly series'] +/** Define the minimum number of images required for processing or validation */ export const MIN_IMAGE_COUNT = 1 +/** Define the maximum number of images allowed for upload or display */ export const MAX_IMAGE_COUNT = 4 +/** Resolve a human-readable relative time string from a given date or return an empty string if null */ export function relativeTime(date: Date | null): string { if (!date) return '' const now = Date.now() @@ -96,6 +112,7 @@ export function relativeTime(date: Date | null): string { return new Date(date).toLocaleDateString('en-US', { month: 'short', day: 'numeric' }) } +/** Resolve the output directory path based on the specified generation type */ export function outputPathFor(type: GenerationType): string { if (type === 'image') return 'generated/images' if (type === 'video') return 'generated/videos' @@ -104,11 +121,13 @@ export function outputPathFor(type: GenerationType): string { return 'generated/transcripts' } +/** Resolve the vault path string from a Generation object or return null if unavailable */ export function generationVaultPath(generation: Generation): string | null { const value = generation.metadata?.vaultPath return typeof value === 'string' && value.trim() ? value.trim() : null } +/** Build a PublishPackage object from caption, description, mentions, cadence, and destinations inputs */ export function buildPublishPackage({ caption, postDescription, @@ -150,6 +169,7 @@ export function buildPublishPackage({ } } +/** Determine if a value conforms to the PublishPackage structure with optional metadata fields */ export function isPublishPackage(value: unknown): value is { caption?: string; description?: string; mentions?: string[]; destinations?: string[]; cadence?: string } { if (!value || typeof value !== 'object') return false const publishPackage = value as { @@ -170,6 +190,7 @@ export function isPublishPackage(value: unknown): value is { caption?: string; d ) } +/** Determine if a destination has any active connections in the given list of studio integration connections */ export function isDestinationConnected( destination: PublishDestination, connections: StudioIntegrationConnection[], @@ -179,6 +200,7 @@ export function isDestinationConnected( || (connection.connectorId !== undefined && destination.providerIds.includes(connection.connectorId)))) } +/** Resolve selected models by applying defaults for missing or unavailable entries in the catalog */ export function selectedModelsWithDefaults( current: Partial>, catalog: MediaModelCatalogResponse, @@ -197,6 +219,7 @@ export function selectedModelsWithDefaults( return next } +/** Resolve the preferred model ID for a given generation type from the media model catalog */ export function preferredModelId(type: GenerationType, catalog: MediaModelCatalogResponse | null): string | undefined { if (!catalog) return undefined const models = catalog.models[type] ?? [] @@ -206,6 +229,7 @@ export function preferredModelId(type: GenerationType, catalog: MediaModelCatalo ?? models[0]?.id } +/** Resolve the appropriate status message for a media model based on loading state and availability */ export function modelMessage(model: MediaModelOption | undefined, loading: boolean, count: number): string | null { if (loading) return 'Loading media models...' if (count === 0) return 'No models are available for this media type.' @@ -215,6 +239,7 @@ export function modelMessage(model: MediaModelOption | undefined, loading: boole return null } +/** Define fields required to configure and request various types of media generation */ export interface GenerationRequestFields { workspaceId: string clientRequestId: string @@ -232,6 +257,7 @@ export interface GenerationRequestFields { } // image.count must already be normalized — it is also the optimistic-card count on the caller side +/** Build the request body object for a generation operation from provided fields */ export function buildGenerationRequestBody(fields: GenerationRequestFields): Record { const body: Record = { workspaceId: fields.workspaceId, @@ -277,6 +303,7 @@ export function buildGenerationRequestBody(fields: GenerationRequestFields): Rec return body } +/** Resolve the current status of a generation based on its metadata and result fields */ export function generationStatus(generation: Generation): GenerationStatus { const metadata = generation.metadata ?? {} const status = typeof metadata.generationStatus === 'string' ? metadata.generationStatus : '' @@ -284,6 +311,7 @@ export function generationStatus(generation: Generation): GenerationStatus { return generation.result ? 'succeeded' : 'pending' } +/** Resolve and return the first user-safe error message from generation metadata or null if none exist */ export function generationError(generation: Generation): string | null { const metadata = generation.metadata ?? {} if (typeof metadata.providerError === 'string' && metadata.providerError.trim()) { @@ -310,10 +338,12 @@ function generationBatchSlotKey(generation: Generation): string | null { : null } +/** Resolve a unique merge key from a generation using batch slot or client request ID */ export function generationMergeKey(generation: Generation): string | null { return generationBatchSlotKey(generation) ?? generationClientRequestId(generation) } +/** Merge a new generation into the current list by replacing or prepending it based on matching keys */ export function mergeLiveGeneration(current: Generation[], generation: Generation): Generation[] { const mergeKey = generationMergeKey(generation) const existingIndex = current.findIndex((item) => ( @@ -333,6 +363,7 @@ export function mergeLiveGeneration(current: Generation[], generation: Generatio // represents — deduped by BOTH id and merge key so a server row and its // optimistic twin never both appear. Returns `loader` unchanged when nothing is // live. Drives the canvas, library, and polling off one list. +/** Merge two Generation arrays prioritizing live entries and matching by merge keys or IDs */ export function mergeLoaderAndLive(loader: Generation[], live: Generation[]): Generation[] { if (live.length === 0) return loader const leading = live.map((generation) => { @@ -354,6 +385,7 @@ export function mergeLoaderAndLive(loader: Generation[], live: Generation[]): Ge ] } +/** Determine if a generation ID indicates a local generation */ export function isLocalGeneration(generation: Generation): boolean { return generation.id.startsWith('local-') } @@ -366,6 +398,7 @@ function generationOutputIndex(generation: Generation): number { // The most-recent run: all generations sharing the leading item's clientRequestId // (a multi-image batch), ordered by output slot. Falls back to the single leading // item when no request id is present. Drives the result canvas. +/** Resolve and return the latest batch of generations grouped and sorted by client request ID and output index */ export function latestBatchOf(generations: Generation[]): Generation[] { const first = generations[0] if (!first) return [] @@ -376,6 +409,7 @@ export function latestBatchOf(generations: Generation[]): Generation[] { return [...batch].sort((a, b) => generationOutputIndex(a) - generationOutputIndex(b)) } +/** Resolve a user-safe generation message by filtering sensitive or error-related content */ export function userSafeGenerationMessage(message?: string): string { if (!message) return 'Generation failed' if (/Tangle API key is invalid or expired/i.test(message)) return message @@ -385,6 +419,7 @@ export function userSafeGenerationMessage(message?: string): string { return message } +/** Generate content optimistically based on input parameters and optional model and output details */ export function optimisticGeneration({ type, prompt, @@ -420,6 +455,7 @@ export function optimisticGeneration({ } } +/** Mark a generation as failed with updated status and error information */ export function failedOptimisticGeneration(generation: Generation): Generation { return { ...generation, @@ -431,6 +467,7 @@ export function failedOptimisticGeneration(generation: Generation): Generation { } } +/** Normalize a value to a finite integer within the allowed image count range */ export function normalizeImageCount(value: unknown): number { const numeric = typeof value === 'number' ? value : Number(value) if (!Number.isFinite(numeric)) return MIN_IMAGE_COUNT diff --git a/src/tangle/index.ts b/src/tangle/index.ts index 46bbce0..3092391 100644 --- a/src/tangle/index.ts +++ b/src/tangle/index.ts @@ -40,6 +40,7 @@ export interface BrokerTokenMinter { mintBrokerToken(input: { clientId: string; clientSecret: string; grantId: string; ttlSeconds?: number }): Promise } +/** Define input parameters required to generate a consent URL for OAuth authorization */ export interface ConsentUrlInput { /** Platform base URL (e.g. https://id.tangle.tools). */ endpoint: string @@ -72,6 +73,7 @@ export function buildConsentUrl(input: ConsentUrlInput): string { return `${base}/cross-site/app-consent?${params.toString()}` } +/** Define options for configuring a broker token provider including client credentials and token management settings */ export interface BrokerTokenProviderOptions { client: BrokerTokenMinter clientId: string @@ -87,6 +89,7 @@ export interface BrokerTokenProviderOptions { now?: () => number } +/** Provide and refresh broker bearer tokens, allowing forced token invalidation */ export interface BrokerTokenProvider { /** A valid `sk-tan-broker-` bearer, minting/refreshing as needed. */ getToken(): Promise diff --git a/src/teams-react/contracts.ts b/src/teams-react/contracts.ts index f578007..ce411ee 100644 --- a/src/teams-react/contracts.ts +++ b/src/teams-react/contracts.ts @@ -22,6 +22,7 @@ export interface MemberView { inherited?: boolean } +/** Define properties and callbacks for managing members and their roles in a workspace panel */ export interface MembersPanelProps { members: MemberView[] /** The viewer's effective role — gates which controls are interactive. */ @@ -55,6 +56,7 @@ export interface InvitationView { inviteUrl: string } +/** Define properties and callbacks for managing workspace invitations and user roles */ export interface InvitationsPanelProps { invitations: InvitationView[] /** The viewer's effective role — gates whether the invite controls are interactive. */ @@ -71,8 +73,10 @@ export interface InvitationsPanelProps { onNotice?(notice: { kind: 'success' | 'error'; message: string }): void } +/** Define possible statuses for the acceptance state of an invitation */ export type InviteAcceptStatus = 'pending' | 'invalid' | 'already-accepted' | 'expired' | 'revoked' +/** Describe details of an accepted invite including status, workspace, inviter, role, emails, and expiration */ export interface InviteAcceptDetails { status: InviteAcceptStatus /** Workspace the invite grants access to. */ @@ -91,6 +95,7 @@ export interface InviteAcceptDetails { needsEmailVerification?: boolean } +/** Define properties and callbacks for handling invite acceptance and navigation actions on the invite page */ export interface InviteAcceptPageProps { details: InviteAcceptDetails /** Accept the invite; resolve with the workspace to navigate to. */ diff --git a/src/teams-react/lazy.tsx b/src/teams-react/lazy.tsx index 9c8e29a..0619909 100644 --- a/src/teams-react/lazy.tsx +++ b/src/teams-react/lazy.tsx @@ -10,14 +10,17 @@ import type { MembersPanelProps, InvitationsPanelProps, InviteAcceptPageProps } export type { MembersPanelProps, InvitationsPanelProps, InviteAcceptPageProps } +/** Load MembersPanel component lazily to optimize initial rendering performance */ export const MembersPanelLazy = lazy( () => import('./components/MembersPanel').then((m) => ({ default: m.MembersPanel })), ) +/** Load InvitationsPanel component lazily to optimize initial rendering performance */ export const InvitationsPanelLazy = lazy( () => import('./components/InvitationsPanel').then((m) => ({ default: m.InvitationsPanel })), ) +/** Load InviteAcceptPage component lazily for optimized code splitting and performance */ export const InviteAcceptPageLazy = lazy( () => import('./components/InviteAcceptPage').then((m) => ({ default: m.InviteAcceptPage })), ) diff --git a/src/teams/drizzle/access.ts b/src/teams/drizzle/access.ts index 1036934..67207ae 100644 --- a/src/teams/drizzle/access.ts +++ b/src/teams/drizzle/access.ts @@ -45,6 +45,7 @@ export interface WorkspaceAccessTable { updatedAt: any } +/** Define options required to create access with database, tables, and workspace table references */ export interface CreateAccessOptions { db: TeamDatabase tables: TeamTables @@ -52,6 +53,7 @@ export interface CreateAccessOptions { workspaceTable: TeamParentTable & WorkspaceAccessTable } +/** Define access details including workspace data, organization info, member info, and role within workspace */ export interface WorkspaceAccess { workspace: Record organization: OrganizationRow @@ -59,18 +61,21 @@ export interface WorkspaceAccess { role: WorkspaceRole } +/** Describe a user's workspace details including organization and role information */ export interface UserWorkspaceSummary extends Record { organizationId: string organizationName: string role: WorkspaceRole } +/** Define methods to retrieve and enforce user access permissions within workspaces */ export interface WorkspaceAccessApi { getWorkspaceAccess(workspaceId: string, userId: string, minRole?: WorkspaceRole): Promise requireWorkspaceAccess(workspaceId: string, userId: string, minRole?: WorkspaceRole): Promise listUserWorkspaces(userId: string): Promise } +/** Create workspace access API to manage user roles and permissions within a workspace */ export function createWorkspaceAccess(opts: CreateAccessOptions): WorkspaceAccessApi { const { db, tables, workspaceTable } = opts const { organizations, organizationMembers, workspaceMembers } = tables @@ -165,22 +170,26 @@ export function createWorkspaceAccess(opts: CreateAccessOptions): WorkspaceAcces return { getWorkspaceAccess, requireWorkspaceAccess, listUserWorkspaces } } +/** Define access details linking an organization, its member, and the member's role */ export interface OrganizationAccess { organization: OrganizationRow member: OrganizationMemberRow role: OrganizationRole } +/** Define methods to retrieve and enforce user access levels within an organization */ export interface OrganizationAccessApi { getOrganizationAccess(organizationId: string, userId: string, minRole?: OrganizationRole): Promise requireOrganizationAccess(organizationId: string, userId: string, minRole?: OrganizationRole): Promise } +/** Define options required to create access for an organization including database and tables */ export interface CreateOrganizationAccessOptions { db: TeamDatabase tables: TeamTables } +/** Resolve organization access API with specified database and table options */ export function createOrganizationAccess(opts: CreateOrganizationAccessOptions): OrganizationAccessApi { const { db, tables } = opts const { organizations, organizationMembers } = tables diff --git a/src/teams/drizzle/invitations-schema.ts b/src/teams/drizzle/invitations-schema.ts index 3cf7330..091e50e 100644 --- a/src/teams/drizzle/invitations-schema.ts +++ b/src/teams/drizzle/invitations-schema.ts @@ -19,6 +19,7 @@ import { sql } from 'drizzle-orm' import { index, integer, sqliteTable, text, uniqueIndex } from 'drizzle-orm/sqlite-core' import type { TeamParentTable } from './schema' +/** Define options for creating a workspace invitation table with user, workspace, and organization references */ export interface CreateWorkspaceInvitationTableOptions { /** The product's user table — `invitedByUserId` references `userTable.id`. */ userTable: TeamParentTable @@ -28,6 +29,7 @@ export interface CreateWorkspaceInvitationTableOptions { organizationTable: TeamParentTable } +/** Build a workspace invitation table with defined columns and foreign key constraints */ export function createWorkspaceInvitationTable(opts: CreateWorkspaceInvitationTableOptions) { const { userTable, workspaceTable, organizationTable } = opts @@ -56,5 +58,7 @@ export function createWorkspaceInvitationTable(opts: CreateWorkspaceInvitationTa return { workspaceInvitations } } +/** Resolve the structure of workspace invitation tables from the creation function */ export type WorkspaceInvitationTables = ReturnType +/** Resolve the structure of a workspace invitation row from the workspaceInvitations table */ export type WorkspaceInvitationRow = WorkspaceInvitationTables['workspaceInvitations']['$inferSelect'] diff --git a/src/teams/drizzle/personal-organization.ts b/src/teams/drizzle/personal-organization.ts index fc11685..4291444 100644 --- a/src/teams/drizzle/personal-organization.ts +++ b/src/teams/drizzle/personal-organization.ts @@ -23,23 +23,27 @@ import type { OrganizationRole } from '../roles' import type { TeamDatabase } from './access' import type { OrganizationMemberRow, OrganizationRow, TeamTables } from './schema' +/** Define the structure for a user within a personal organization context */ export interface EnsurePersonalOrganizationUser { id: string name?: string | null email?: string | null } +/** Describe a personal organization result including organization, member, and role details */ export interface PersonalOrganizationResult { organization: OrganizationRow member: OrganizationMemberRow role: OrganizationRole } +/** Define options required to create a personal organization including database and tables references */ export interface CreatePersonalOrganizationOptions { db: TeamDatabase tables: TeamTables } +/** Ensure a user has a personal organization by creating or retrieving it as needed */ export function createEnsurePersonalOrganization(opts: CreatePersonalOrganizationOptions) { const { db, tables } = opts const { organizations, organizationMembers } = tables diff --git a/src/teams/drizzle/schema.ts b/src/teams/drizzle/schema.ts index 6686119..1e0a3eb 100644 --- a/src/teams/drizzle/schema.ts +++ b/src/teams/drizzle/schema.ts @@ -26,6 +26,7 @@ import type { AnySQLiteColumn, AnySQLiteTable } from 'drizzle-orm/sqlite-core' /** A product table referenced by FK — only the `id` column is touched. */ export type TeamParentTable = AnySQLiteTable & { id: AnySQLiteColumn } +/** Define options specifying user and workspace tables for creating team-related tables */ export interface CreateTeamTablesOptions { /** The product's user table — org/member rows reference `userTable.id`. */ userTable: TeamParentTable @@ -39,6 +40,7 @@ const createdAt = () => integer('created_at', { mode: 'timestamp' }).notNull().d const updatedAt = () => integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`) +/** Build SQLite tables for organizations and related team structures using provided options */ export function createTeamTables(opts: CreateTeamTablesOptions) { const { userTable, workspaceTable } = opts @@ -87,8 +89,12 @@ export function createTeamTables(opts: CreateTeamTablesOptions) { return { organizations, organizationMembers, workspaceMembers } } +/** Resolve team tables by deriving the return type of createTeamTables */ export type TeamTables = ReturnType +/** Resolve the structure of an organization row from the organizations table in TeamTables */ export type OrganizationRow = TeamTables['organizations']['$inferSelect'] +/** Resolve the structure of an organization member row from the team tables selection */ export type OrganizationMemberRow = TeamTables['organizationMembers']['$inferSelect'] +/** Resolve a workspace member row with selected fields from the workspaceMembers table */ export type WorkspaceMemberRow = TeamTables['workspaceMembers']['$inferSelect'] diff --git a/src/teams/invitations-api.ts b/src/teams/invitations-api.ts index 16dcc63..a59c2a0 100644 --- a/src/teams/invitations-api.ts +++ b/src/teams/invitations-api.ts @@ -55,7 +55,9 @@ export interface SendInvitationEmailInput { inviteUrl: string expiresAt: Date } +/** Represent the outcome of sending an invitation email with success status and optional error message */ export type SendInvitationEmailResult = { succeeded: true } | { succeeded: false; error: string } +/** Resolve sending an invitation email and return the result asynchronously */ export interface SendInvitationEmailSeam { (input: SendInvitationEmailInput): Promise } @@ -73,6 +75,7 @@ export interface InvitationWorkspaceTable { name: any } +/** Define configuration options required to manage workspace invitations and related data sources */ export interface InvitationsApiOptions { db: TeamDatabase tables: TeamTables @@ -91,6 +94,7 @@ export interface InvitationsApiOptions { productDisplayName?: string } +/** Represent a workspace invitation with details about inviter, permissions, status, and timestamps */ export interface WorkspaceInvitationView { id: string workspaceId: string @@ -109,6 +113,7 @@ export interface WorkspaceInvitationView { lastSentAt: Date | null } +/** Describe the structure of an invitation preview with workspace, email, permissions, status, and expiration details */ export interface InvitationPreview { workspaceId: string workspaceName: string @@ -119,6 +124,7 @@ export interface InvitationPreview { expiresAt: Date } +/** Resolve the result of an invitation as success with a value or failure with status and error details */ export type InvitationOutcome = | { succeeded: true; value: T } | { succeeded: false; status: number; error: string } diff --git a/src/teams/invitations.ts b/src/teams/invitations.ts index e8240e2..57b4472 100644 --- a/src/teams/invitations.ts +++ b/src/teams/invitations.ts @@ -16,22 +16,28 @@ import type { AssignableWorkspaceRole } from './roles' /** The role an invitation grants — the assignable workspace ladder (never owner). */ export type InvitationPermission = AssignableWorkspaceRole +/** Define possible states for an invitation's lifecycle including pending, accepted, expired, and revoked */ export type InvitationStatus = 'pending' | 'accepted' | 'expired' | 'revoked' +/** Define possible statuses for the sending state of an invitation email */ export type InvitationEmailStatus = 'not_sent' | 'sent' | 'failed' +/** Define the number of days before an invitation expires */ export const INVITATION_EXPIRY_DAYS = 7 const INVITATION_PERMISSIONS = ['admin', 'editor', 'viewer'] as const const TOKEN_BYTE_LENGTH = 32 +/** Normalize an invitation email by trimming whitespace and converting to lowercase */ export function normalizeInvitationEmail(email: string): string { return email.trim().toLowerCase() } +/** Resolve invitation permission from a string or return null if invalid */ export function parseInvitationPermission(value: string | undefined): InvitationPermission | null { return INVITATION_PERMISSIONS.includes(value as InvitationPermission) ? (value as InvitationPermission) : null } +/** Calculate the expiration date of an invitation based on the given or current date */ export function getInvitationExpiresAt(now: Date = new Date()): Date { return new Date(now.getTime() + INVITATION_EXPIRY_DAYS * 24 * 60 * 60 * 1000) } @@ -48,12 +54,14 @@ export function generateInvitationToken(): string { return `inv_${btoa(token).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')}` } +/** Generate an invite URL by combining the origin with an encoded token */ export function inviteUrlForToken(origin: string, token: string): string { return `${origin.replace(/\/+$/, '')}/invite/${encodeURIComponent(token)}` } // ── email template (pure; no transport) ── +/** Define input data required to render an invitation email template */ export interface RenderInvitationEmailInput { to: string workspaceName: string @@ -63,11 +71,13 @@ export interface RenderInvitationEmailInput { expiresAt: Date } +/** Define the structure for an invitation email brand including the RFC-5322 From header */ export interface InvitationEmailBrand { /** RFC-5322 From header, e.g. `GTM Agent `. */ fromAddress: string } +/** Define the structure of a fully rendered invitation email with sender, subject, and content fields */ export interface RenderedInvitationEmail { from: string subject: string diff --git a/src/teams/invite.ts b/src/teams/invite.ts index d4fc7b0..1d63e22 100644 --- a/src/teams/invite.ts +++ b/src/teams/invite.ts @@ -36,8 +36,10 @@ export interface InviteTokenState { expiresAt?: Date | number | null } +/** Define possible reasons for rejecting an invite including acceptance, expiration, or email mismatch */ export type InviteRejectionReason = 'already-accepted' | 'expired' | 'email-mismatch' +/** Represent the outcome of validating an invite with success status and optional rejection reason */ export interface InviteValidationResult { ok: boolean reason?: InviteRejectionReason diff --git a/src/teams/members-api.ts b/src/teams/members-api.ts index 04590d6..4687635 100644 --- a/src/teams/members-api.ts +++ b/src/teams/members-api.ts @@ -96,6 +96,7 @@ export interface MemberSyncSeam { remove?(input: { workspaceId: string; userId: string }): Promise | void } +/** Define configuration options for managing team members and workspace access APIs */ export interface MembersApiOptions { db: TeamDatabase tables: TeamTables @@ -109,6 +110,7 @@ export interface MembersApiOptions { memberSyncSeam?: MemberSyncSeam } +/** Define the structure of a workspace member entry with identification, role, and status details */ export interface MemberListEntry { id: string userId: string | null diff --git a/src/teams/resend.ts b/src/teams/resend.ts index e2b56dc..bcba1c4 100644 --- a/src/teams/resend.ts +++ b/src/teams/resend.ts @@ -15,6 +15,7 @@ import { Resend } from 'resend' import { renderInvitationEmail } from './invitations' import type { SendInvitationEmailSeam } from './invitations-api' +/** Define options for sending a resend invitation including sender address and optional API key */ export interface ResendInvitationSenderOptions { /** RFC-5322 From header, e.g. `GTM Agent `. */ from: string diff --git a/src/teams/roles.ts b/src/teams/roles.ts index 2ec72dc..46e6e79 100644 --- a/src/teams/roles.ts +++ b/src/teams/roles.ts @@ -16,17 +16,25 @@ */ export const WORKSPACE_ROLES = ['viewer', 'editor', 'admin', 'owner'] as const +/** Resolve the union type of all possible workspace role string literals from WORKSPACE_ROLES array */ export type WorkspaceRole = typeof WORKSPACE_ROLES[number] +/** Define the list of roles that can be assigned within a workspace */ export const ASSIGNABLE_WORKSPACE_ROLES = ['viewer', 'editor', 'admin'] as const +/** Resolve the set of roles that can be assigned within a workspace */ export type AssignableWorkspaceRole = typeof ASSIGNABLE_WORKSPACE_ROLES[number] +/** Define the set of fixed roles available within an organization */ export const ORGANIZATION_ROLES = ['owner', 'admin', 'member', 'billing'] as const +/** Resolve a role string from the predefined list of organization roles */ export type OrganizationRole = typeof ORGANIZATION_ROLES[number] +/** Define access levels for workspace collaboration as either read or write */ export type WorkspaceCollaborationAccess = 'read' | 'write' +/** Define user roles available within a sandbox workspace environment */ export type SandboxWorkspaceRole = 'owner' | 'admin' | 'developer' | 'viewer' +/** Map workspace roles to their corresponding hierarchical rank values */ export const WORKSPACE_ROLE_RANK: Record = { viewer: 0, editor: 1, @@ -34,6 +42,7 @@ export const WORKSPACE_ROLE_RANK: Record = { owner: 3, } +/** Map organization roles to their hierarchical rank for permission and access control purposes */ export const ORGANIZATION_ROLE_RANK: Record = { member: 0, billing: 1, @@ -51,6 +60,7 @@ export function hasOrganizationRole(actual: OrganizationRole, minimum: Organizat return ORGANIZATION_ROLE_RANK[actual] >= ORGANIZATION_ROLE_RANK[minimum] } +/** Determine if a value is a valid assignable workspace role among viewer, editor, or admin */ export function isAssignableWorkspaceRole(value: unknown): value is AssignableWorkspaceRole { return typeof value === 'string' && ASSIGNABLE_WORKSPACE_ROLES.includes(value as AssignableWorkspaceRole) } @@ -81,10 +91,12 @@ export function canManageWorkspaceMemberRole(actorRole: WorkspaceRole, targetRol return actorRole === 'owner' || !hasWorkspaceRole(targetRole, actorRole) } +/** Map a workspace role to the corresponding collaboration access level */ export function workspaceRoleToCollaborationAccess(role: WorkspaceRole): WorkspaceCollaborationAccess { return role === 'viewer' ? 'read' : 'write' } +/** Map a workspace role to its corresponding sandbox workspace role */ export function workspaceRoleToSandboxRole(role: WorkspaceRole): SandboxWorkspaceRole { const mapping: Record = { owner: 'owner', diff --git a/src/theme-contract/index.ts b/src/theme-contract/index.ts index 122833a..c69eb78 100644 --- a/src/theme-contract/index.ts +++ b/src/theme-contract/index.ts @@ -50,6 +50,7 @@ import { type Dirent, existsSync, readFileSync, readdirSync } from 'node:fs' import { join, relative } from 'node:path' import { fileURLToPath } from 'node:url' +/** Define options for scanning source directories and CSS token files in a theme contract */ export interface ThemeContractOptions { /** Consumer source directories to scan for token references (recursively). */ srcDirs: string[] @@ -72,6 +73,7 @@ export interface ThemeContractOptions { allowlist?: string[] } +/** Describe a missing theme contract variable and where it was referenced */ export interface ThemeContractMiss { /** The undefined custom property, e.g. `--popover`. */ varName: string @@ -83,6 +85,7 @@ export interface ThemeContractMiss { referencedIn: string } +/** Describe the result of validating a theme contract including success status and missing items */ export interface ThemeContractResult { ok: boolean missing: ThemeContractMiss[] diff --git a/src/theme/tailwind-preset.ts b/src/theme/tailwind-preset.ts index b31b6d1..d4b23d6 100644 --- a/src/theme/tailwind-preset.ts +++ b/src/theme/tailwind-preset.ts @@ -17,6 +17,7 @@ const withForeground = (name: string) => ({ foreground: `hsl(var(--${name}-foreground))`, }) +/** Define a preset configuration for dark mode and extended theme colors with foreground variants */ const agentAppPreset = { darkMode: ['class', '[data-theme="dark"]'] as [string, string], theme: { diff --git a/src/theme/theme.ts b/src/theme/theme.ts index 9d24040..d871e07 100644 --- a/src/theme/theme.ts +++ b/src/theme/theme.ts @@ -69,6 +69,7 @@ export interface CanvasRenderPalette { brokenStroke: string } +/** Define a light color theme with specific background, foreground, and accent color values */ export const lightTheme: AgentAppTheme = { background: '0 0% 100%', foreground: '0 0% 5%', @@ -109,6 +110,7 @@ export const lightTheme: AgentAppTheme = { }, } +/** Define a dark color scheme for the Agent app interface with specific background and foreground hues */ export const darkTheme: AgentAppTheme = { background: '240 8% 5%', foreground: '240 6% 93%', diff --git a/src/tools/auth.ts b/src/tools/auth.ts index fafd92d..2a7274e 100644 --- a/src/tools/auth.ts +++ b/src/tools/auth.ts @@ -11,12 +11,14 @@ export interface ToolHeaderNames { threadId: string } +/** Provide default HTTP header names for user, workspace, and thread identification */ export const DEFAULT_HEADER_NAMES: ToolHeaderNames = { userId: 'X-Agent-App-User-Id', workspaceId: 'X-Agent-App-Workspace-Id', threadId: 'X-Agent-App-Thread-Id', } +/** Define options to verify bearer tokens and customize authentication header names */ export interface AuthenticateOptions { /** Verify the bearer capability token belongs to `userId`. The product's * HMAC/JWT impl — the seam that keeps token crypto out of this package. */ @@ -24,6 +26,7 @@ export interface AuthenticateOptions { headerNames?: ToolHeaderNames } +/** Represent the result of tool authentication with success context or failure response */ export type ToolAuthResult = | { ok: true; ctx: AppToolContext } | { ok: false; response: Response } diff --git a/src/tools/capability.ts b/src/tools/capability.ts index d847347..3df0337 100644 --- a/src/tools/capability.ts +++ b/src/tools/capability.ts @@ -22,6 +22,7 @@ import { hmacSha256Base64Url, } from '../crypto/web-token' +/** Define options for creating and verifying capability tokens including secret and prefix */ export interface CapabilityTokenOptions { /** Shared HMAC secret. When absent, mint returns undefined / verify returns false. */ secret?: string @@ -49,6 +50,7 @@ export async function verifyCapabilityToken(userId: string, token: string, opts: return constantTimeEqual(token, expected) } +/** Define options for capability tokens that expire after a specified lifetime in milliseconds */ export interface ExpiringCapabilityTokenOptions extends CapabilityTokenOptions { /** Token lifetime. Expired tokens verify false regardless of signature. */ expiresInMs: number diff --git a/src/tools/dispatch.ts b/src/tools/dispatch.ts index 96cdcbf..18cedaa 100644 --- a/src/tools/dispatch.ts +++ b/src/tools/dispatch.ts @@ -9,6 +9,7 @@ import type { AppToolTaxonomy, } from './types' +/** Define options for dispatching tools including handlers, taxonomy, custom tools, and approval policies */ export interface DispatchOptions { handlers: AppToolHandlers taxonomy: AppToolTaxonomy diff --git a/src/tools/gating.ts b/src/tools/gating.ts index 4e2ee17..db987a8 100644 --- a/src/tools/gating.ts +++ b/src/tools/gating.ts @@ -30,6 +30,7 @@ export interface ToolCapability { toolGroups?: readonly string[] } +/** Resolve options for determining tool capabilities based on taxonomy, capabilities, and enabled IDs */ export interface ResolveToolCapabilitiesOptions { taxonomy: AppToolTaxonomy /** The product's full capability registry. */ @@ -44,6 +45,7 @@ export interface ResolveToolCapabilitiesOptions { baseProposalTypes?: readonly string[] } +/** Describe resolved capabilities including proposal types and product tool groups to expose */ export interface ResolvedToolCapabilities { /** Proposal types to keep — feed to {@link restrictTaxonomy}. */ proposalTypes: string[] diff --git a/src/tools/http.ts b/src/tools/http.ts index d15f797..31981f6 100644 --- a/src/tools/http.ts +++ b/src/tools/http.ts @@ -3,6 +3,7 @@ import { dispatchAppTool, outcomeStatus, type DispatchOptions } from './dispatch import type { AppToolName } from './openai' import type { AppToolDefinition } from './registry' +/** Define options for handling tool requests including tool identification and token verification */ export interface HandleToolRequestOptions extends DispatchOptions { /** Which app tool this route serves — a built-in name or a product-registered * {@link AppToolDefinition} (auto-added to `customTools` for dispatch). */ diff --git a/src/tools/mcp-rpc.ts b/src/tools/mcp-rpc.ts index c7f885f..0d72774 100644 --- a/src/tools/mcp-rpc.ts +++ b/src/tools/mcp-rpc.ts @@ -18,10 +18,12 @@ */ export const MCP_PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'] as const +/** Resolve a valid protocol version from the predefined MCP_PROTOCOL_VERSIONS array */ export type McpProtocolVersion = (typeof MCP_PROTOCOL_VERSIONS)[number] const LATEST_PROTOCOL_VERSION: McpProtocolVersion = MCP_PROTOCOL_VERSIONS[0] +/** Describe the structure of server information including name and version */ export interface McpServerInfo { name: string version: string @@ -38,6 +40,7 @@ export interface McpToolDefinition> { run(args: Record, env: TEnv): Promise } +/** Define options for creating a handler that manages MCP tools with environment support */ export interface CreateMcpToolHandlerOptions> { serverInfo: McpServerInfo /** Full tool list; order IS the tools/list order. */ diff --git a/src/tools/mcp.ts b/src/tools/mcp.ts index 3be45c8..e76a885 100644 --- a/src/tools/mcp.ts +++ b/src/tools/mcp.ts @@ -24,6 +24,7 @@ export interface AppToolMcpServer { metadata: { description: string } } +/** Define configuration options for building an HTTP MCP server including path, baseUrl, token, context, and description */ export interface BuildHttpMcpServerOptions { /** Route path on the app the sandbox POSTs to (e.g. `/api/tools/propose`). */ path: string @@ -130,6 +131,7 @@ export function buildScopedMcpServerEntry( } } +/** Define configuration options required to build an MCP server including tool, baseUrl, token, and context */ export interface BuildMcpServerOptions { /** A built-in app tool name, or a product-registered {@link AppToolDefinition}. * A custom tool supplies its route via `AppToolDefinition.path` (or `paths`). */ diff --git a/src/tools/openai.ts b/src/tools/openai.ts index 35122af..1741ce0 100644 --- a/src/tools/openai.ts +++ b/src/tools/openai.ts @@ -3,9 +3,11 @@ import type { AppToolTaxonomy, BuildAppToolsOptions } from './types' /** The four canonical app-tool names. Stable identifiers the model calls in * both the sandbox (MCP server name) and runtime (function-tool name) paths. */ export const APP_TOOL_NAMES = ['submit_proposal', 'schedule_followup', 'render_ui', 'add_citation'] as const +/** Resolve a valid application tool name from the predefined list of tool names */ export type AppToolName = (typeof APP_TOOL_NAMES)[number] const NAME_SET = new Set(APP_TOOL_NAMES) +/** Determine if a string matches a valid application tool name */ export function isAppToolName(name: string): name is AppToolName { return NAME_SET.has(name) } diff --git a/src/tools/runtime.ts b/src/tools/runtime.ts index da650ce..76c13c3 100644 --- a/src/tools/runtime.ts +++ b/src/tools/runtime.ts @@ -9,6 +9,7 @@ export type AppToolRuntimeExecutor = (call: { args: Record }) => Promise +/** Define options for executing runtime tasks with a trusted per-turn context */ export interface RuntimeExecutorOptions extends DispatchOptions { /** The trusted per-turn context — supplied directly (not from headers), since * the runtime path has no HTTP request. */ diff --git a/src/tools/types.ts b/src/tools/types.ts index 7f8af34..7ee54b7 100644 --- a/src/tools/types.ts +++ b/src/tools/types.ts @@ -55,6 +55,7 @@ export interface BuildAppToolsOptions { customTools?: readonly import('./registry').AppToolDefinition[] } +/** Define the arguments required to submit a proposal including type, title, description, and approval status */ export interface SubmitProposalArgs { type: string title: string @@ -64,6 +65,7 @@ export interface SubmitProposalArgs { * true. Products don't set this; dispatch owns it — fail-closed. */ regulated?: boolean } +/** Describe the result of submitting a proposal including deduplication and execution status */ export interface SubmitProposalResult { proposalId: string /** True when an identical (workspace, title) proposal already existed. */ @@ -77,21 +79,25 @@ export interface SubmitProposalResult { [extra: string]: unknown } +/** Define arguments required to schedule a follow-up with optional priority */ export interface ScheduleFollowupArgs { title: string dueDate: string priority?: string } +/** Define the result structure for scheduling a follow-up with unique identification and due date */ export interface ScheduleFollowupResult { id: string dueDate: string deduped: boolean } +/** Define arguments required to render a UI including title and schema */ export interface RenderUiArgs { title: string schema: unknown } +/** Describe the result of rendering UI including the artifact path and exact persisted content */ export interface RenderUiResult { /** The persisted artifact path. */ path: string @@ -100,11 +106,13 @@ export interface RenderUiResult { content: string } +/** Define arguments required to add a citation including path, quote, and optional label */ export interface AddCitationArgs { path: string quote: string label?: string } +/** Represent the result of adding a citation including its identifier and location path */ export interface AddCitationResult { citationId: string path: string diff --git a/src/trace/flow-types.ts b/src/trace/flow-types.ts index 40a17de..1058125 100644 --- a/src/trace/flow-types.ts +++ b/src/trace/flow-types.ts @@ -14,6 +14,7 @@ export interface FlowSpan { meta?: Record } +/** Describe the structure of a flow trace including spans, timing, tokens, cost, and tool calls */ export interface FlowTrace { spans: FlowSpan[] totalMs: number diff --git a/src/trace/index.ts b/src/trace/index.ts index d11a8c0..deae762 100644 --- a/src/trace/index.ts +++ b/src/trace/index.ts @@ -20,6 +20,7 @@ export * from './mission-flow' import type { FlowSpan, FlowTrace } from './flow-types' +/** Represent a timed event with a timestamp and associated event data */ export interface TimedEvent { /** ms since turn start (`_t` stamped by pumpBufferedTurn). */ t: number @@ -155,6 +156,7 @@ export function renderWaterfall(trace: FlowTrace, opts?: { width?: number }): st return lines.join('\n') } +/** Summarize key statistics of a numerical distribution including count, min, percentiles, and max */ export interface DistributionSummary { n: number min: number @@ -163,6 +165,7 @@ export interface DistributionSummary { max: number } +/** Summarize numeric values into a distribution summary including count, min, median, 90th percentile, and max */ export function summarize(values: number[]): DistributionSummary { const sorted = [...values].sort((a, b) => a - b) const q = (p: number) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))] ?? 0 diff --git a/src/trace/mission-flow.ts b/src/trace/mission-flow.ts index f6633c3..f68ceb1 100644 --- a/src/trace/mission-flow.ts +++ b/src/trace/mission-flow.ts @@ -236,6 +236,7 @@ export function stepActivityFlowTrace( } } +/** Define a step in a mission flow with id, intent, optional status, start time, and duration */ export interface MissionFlowStep { id: string intent: string diff --git a/src/trace/mission-trace.ts b/src/trace/mission-trace.ts index 3a0873a..1fc6d62 100644 --- a/src/trace/mission-trace.ts +++ b/src/trace/mission-trace.ts @@ -22,6 +22,7 @@ export interface MissionTraceContext { rootSpanId: string } +/** Define context information for a step span including trace, span, and parent span identifiers */ export interface StepSpanContext { traceId: string /** 16-hex span id of this step attempt (or any nested unit of work). */ diff --git a/src/turn-stream/adapters.ts b/src/turn-stream/adapters.ts index 8991f06..296ecb5 100644 --- a/src/turn-stream/adapters.ts +++ b/src/turn-stream/adapters.ts @@ -35,6 +35,7 @@ import { // ── structural namespace ──────────────────────────────────────────────────── +/** Resolve a stub interface for handling fetch requests with optional initialization parameters */ export interface TurnStreamStubLike { fetch(input: Request | string, init?: RequestInit): Promise } @@ -132,6 +133,7 @@ export function createDurableObjectTurnEventStore(namespace: TurnStreamNamespace // ── lock primitives (usable outside the route seam too) ───────────────────── +/** Define input parameters required to acquire a durable turn lock in a workspace thread context */ export interface AcquireDurableTurnLockInput { workspaceId: string threadId: string @@ -142,6 +144,7 @@ export interface AcquireDurableTurnLockInput { lockId?: string } +/** Acquire a durable turn lock in the specified namespace with given input parameters */ export async function acquireDurableTurnLock( namespace: TurnStreamNamespaceLike, input: AcquireDurableTurnLockInput, @@ -158,6 +161,7 @@ export async function acquireDurableTurnLock( return result.body } +/** Release a durable turn lock and indicate if the release was successful or deferred */ export async function releaseDurableTurnLock( namespace: TurnStreamNamespaceLike, input: TurnLockReleaseInput, @@ -166,6 +170,7 @@ export async function releaseDurableTurnLock( return postJsonOk(namespace, key, TURN_STREAM_PATHS.lockRelease, input) } +/** Define input parameters to release an interrupted durable turn lock in a workspace or thread */ export interface ReleaseInterruptedDurableTurnLockInput { workspaceId: string threadId: string @@ -198,6 +203,7 @@ export async function releaseInterruptedDurableTurnLock( // ── stale-lock reconciliation against the DO ──────────────────────────────── +/** Define options to reconcile stale durable turn locks with context, namespace, workspace, and active lock details */ export interface ReconcileStaleDurableTurnLockOptions extends Pick< ReconcileStaleTurnLockOptions, @@ -252,6 +258,7 @@ export type TurnLockSeamResult = | { acquired: true; handle?: unknown } | { acquired: false; response: Response } +/** Define options for creating a durable turn lock with customizable scope and identification methods */ export interface CreateDurableTurnLockOptions { namespace: TurnStreamNamespaceLike /** Which lane serializes this turn: `'workspace'` (shared sandbox — one @@ -433,8 +440,10 @@ export async function broadcastThreadCreated( // ── WebSocket upgrade forwarder (worker entry) ────────────────────────────── +/** Represent success or failure of a TURN stream upgrade authorization with optional response data */ export type TurnStreamUpgradeAuthorization = { ok: true } | { ok: false; response: Response } +/** Define options for creating a TURN stream upgrade handler including namespace, path, and authorization logic */ export interface CreateTurnStreamUpgradeHandlerOptions { namespace: TurnStreamNamespaceLike /** The worker route serving the stream. Default `/api/session-stream`. */ diff --git a/src/turn-stream/core.ts b/src/turn-stream/core.ts index 0ae5491..dfa1fe2 100644 --- a/src/turn-stream/core.ts +++ b/src/turn-stream/core.ts @@ -42,12 +42,15 @@ export function isTerminalRunEvent(type: string): boolean { // scope `scope:${scopeId}` — running-turn index for a thread, // backing `TurnEventStore.listRunning`. +/** Define the scope level for acquiring a turn lock within thread or workspace contexts */ export type TurnLockScope = 'thread' | 'workspace' +/** Generate a unique string key combining workspace and thread identifiers */ export function threadChannelKey(workspaceId: string, threadId: string): string { return `${workspaceId}:${threadId}` } +/** Generate a unique channel key based on the given workspace identifier */ export function workspaceChannelKey(workspaceId: string): string { return workspaceId } @@ -60,22 +63,26 @@ export function turnLockChannelKey(workspaceId: string, threadId: string, scope: return scope === 'workspace' ? workspaceChannelKey(workspaceId) : threadChannelKey(workspaceId, threadId) } +/** Generate a storage channel key string for a given turn identifier */ export function turnStorageChannelKey(turnId: string): string { return `turn:${turnId}` } +/** Generate a unique channel key string based on the provided scope identifier */ export function scopeIndexChannelKey(scopeId: string): string { return `scope:${scopeId}` } // ── segment store (reconnect replay over a live socket) ───────────────────── +/** Represent a segment of a turn containing events, sequence limit, and terminal status */ export interface TurnSegment { events: TurnStreamEvent[] maxSeq: number terminal: boolean } +/** Define a store managing segments and tracking the active execution identifier */ export interface SegmentStore { segments: Map activeExecutionId: string | null @@ -93,6 +100,7 @@ export const MAX_RECENT_CREATED = 50 * `end` broadcast can't leave a permanently-stuck "responding" dot. */ export const ACTIVITY_TTL_MS = 15 * 60 * 1000 +/** Create a SegmentStore with initialized segments and no active execution ID */ export function createSegmentStore(): SegmentStore { return { segments: new Map(), activeExecutionId: null } } @@ -186,6 +194,7 @@ export interface DurableTurnLock { releasePending?: boolean } +/** Define input parameters required to acquire a turn-based lock in a workspace thread */ export interface TurnLockAcquireInput { workspaceId: string threadId: string @@ -195,10 +204,12 @@ export interface TurnLockAcquireInput { turnId?: string } +/** Resolve the result of attempting to acquire a turn lock indicating success or active lock status */ export type TurnLockAcquireResult = | { acquired: true; lock: DurableTurnLock } | { acquired: false; active: DurableTurnLock } +/** Define input parameters required to release a turn lock in a specific workspace thread */ export interface TurnLockReleaseInput { workspaceId: string threadId: string @@ -228,6 +239,7 @@ export function activeTurnLock(stored: DurableTurnLock | undefined, now: number) return lock.expiresAt > now ? lock : null } +/** Create a durable turn lock object with timing and scope based on input parameters */ export function createTurnLock(input: TurnLockAcquireInput, now: number, ttlMs = TURN_LOCK_TTL_MS): DurableTurnLock { return { workspaceId: input.workspaceId, @@ -283,6 +295,7 @@ export function interruptedReleaseApplies( // existed there, so a product deletes its fork by re-pointing a binding, not // by re-speaking a protocol. +/** Provide constant paths for managing chat turn streams and locks */ export const TURN_STREAM_PATHS = { broadcast: '/broadcast', lockAcquire: '/chat-turn-lock/acquire', diff --git a/src/turn-stream/do.ts b/src/turn-stream/do.ts index ab71952..96e4ca0 100644 --- a/src/turn-stream/do.ts +++ b/src/turn-stream/do.ts @@ -130,6 +130,7 @@ const MAX_SCOPE_TURNS = 100 // ── the DO ────────────────────────────────────────────────────────────────── +/** Define options to override default TTL and event limits for TURN stream DO operations */ export interface TurnStreamDOOptions { /** Override {@link TURN_LOCK_TTL_MS}. */ lockTtlMs?: number @@ -139,6 +140,7 @@ export interface TurnStreamDOOptions { activityTtlMs?: number } +/** Manage per-turn segments and track active threads with durable event storage */ export class TurnStreamDO { protected readonly state: TurnStreamDOState protected readonly env: unknown diff --git a/src/turn-stream/memory.ts b/src/turn-stream/memory.ts index fbed53f..cc0b0cf 100644 --- a/src/turn-stream/memory.ts +++ b/src/turn-stream/memory.ts @@ -40,6 +40,7 @@ export interface MemoryTurnStreamSocket extends TurnStreamSocket { readonly closed: boolean } +/** Define an in-memory channel for streaming turn-based data with viewer socket connection support */ export interface MemoryTurnStreamChannel { /** Attach a viewer socket to this channel (bypasses the HTTP 101 — the * upgrade handshake is Cloudflare-runtime-only) and run its `sync`. */ @@ -47,6 +48,7 @@ export interface MemoryTurnStreamChannel { readonly instance: TurnStreamDO } +/** Provide an interface to manage channels and namespaces for memory-based turn stream testing */ export interface MemoryTurnStreamHarness { namespace: TurnStreamNamespaceLike /** The channel (creating its DO instance if needed) for a channel key — diff --git a/src/vault/contracts.ts b/src/vault/contracts.ts index 6d5e39b..7062202 100644 --- a/src/vault/contracts.ts +++ b/src/vault/contracts.ts @@ -150,6 +150,7 @@ export interface VaultDockToggle { /** The two editor surfaces the pane switches between for editable text files. */ export type VaultEditorMode = 'rich' | 'source' +/** Define the properties and render methods for the vault pane UI components */ export interface VaultPaneProps { /** Product-owned data access. */ port: VaultDataPort diff --git a/src/vault/lazy.tsx b/src/vault/lazy.tsx index 799eace..5369bb7 100644 --- a/src/vault/lazy.tsx +++ b/src/vault/lazy.tsx @@ -10,6 +10,7 @@ import type { VaultPaneProps } from './contracts' export type { VaultPaneProps } +/** Resolve VaultPane component lazily to optimize loading and improve performance */ export const VaultPaneLazy = lazy( () => import('./VaultPane').then((m) => ({ default: m.VaultPane })), ) diff --git a/src/web-react/chat-stream.ts b/src/web-react/chat-stream.ts index 0ee3eda..8776d42 100644 --- a/src/web-react/chat-stream.ts +++ b/src/web-react/chat-stream.ts @@ -63,12 +63,14 @@ export { type FileIndexWarmingResponse, } from '../chat-routes/file-index' +/** Define the structure for a chat tool call including optional ID, name, and arguments object */ export interface ChatStreamToolCall { toolCallId?: string toolName: string args: Record } +/** Describe the result of a chat stream tool including its outcome and optional metadata fields */ export interface ChatStreamToolResult { toolCallId?: string toolName?: string @@ -76,6 +78,7 @@ export interface ChatStreamToolResult { outcome: { ok: boolean; result?: unknown; code?: string; message?: string } } +/** Define callbacks to handle events and data during a chat streaming session */ export interface ChatStreamCallbacks { onTurnId?: (turnId: string) => void onText?: (delta: string) => void @@ -108,6 +111,7 @@ export interface ChatStreamCallbacks { onPlan?: (plan: ChatPlan) => void } +/** Represent the result of consuming a chat stream including turn ID and content reception status */ export interface ConsumeChatStreamResult { turnId: string | null /** True when any text/reasoning/tool activity was received. */ @@ -308,6 +312,7 @@ export async function consumeChatStream( return { turnId, receivedContent } } +/** Define options for managing and resuming streaming chat interactions with callbacks */ export interface StreamChatOptions { /** Start the turn (POST the chat request); must return a streaming Response. */ start: () => Promise diff --git a/src/web-react/durable-interaction-submit.ts b/src/web-react/durable-interaction-submit.ts index bc357c6..158d6df 100644 --- a/src/web-react/durable-interaction-submit.ts +++ b/src/web-react/durable-interaction-submit.ts @@ -7,6 +7,7 @@ import { type SubmitInteractionAnswer, } from './interaction-card-support' +/** Manage storage and retrieval of interaction attempt keys by interaction and submission identifiers */ export interface InteractionAttemptStore { get(interactionId: string, submissionSignature: string): string | null set(interactionId: string, submissionSignature: string, attemptKey: string): void @@ -28,6 +29,7 @@ function storedAttempts(storage: Pick, key: string): Record< } } +/** Create a session-based store to manage interaction attempts using provided storage and optional namespace */ export function createSessionInteractionAttemptStore( storage: Pick, namespace = 'agent-app:interaction-attempt', @@ -50,6 +52,7 @@ export function createSessionInteractionAttemptStore( } } +/** Create an in-memory store to manage interaction attempts keyed by ID and signature */ export function createMemoryInteractionAttemptStore(): InteractionAttemptStore { const attempts = new Map() const key = (id: string, signature: string) => `${id}\u0000${signature}` @@ -68,10 +71,12 @@ function stableValue(value: unknown): unknown { .map(([key, nested]) => [key, stableValue(nested)])) } +/** Generate a stable string signature from an interaction answer submission */ export function interactionSubmissionSignature(submission: InteractionAnswerSubmission): string { return JSON.stringify(stableValue(submission)) } +/** Define options for submitting durable interaction answers with attempt tracking and optional key creation */ export interface DurableInteractionAnswerSubmitterOptions extends InteractionAnswerSubmitterOptions { attempts: InteractionAttemptStore createAttemptKey?: () => string diff --git a/src/web-react/durable-plan-flow.ts b/src/web-react/durable-plan-flow.ts index e6ed5fe..d19eca5 100644 --- a/src/web-react/durable-plan-flow.ts +++ b/src/web-react/durable-plan-flow.ts @@ -1,6 +1,7 @@ import { useCallback, useEffect, useRef, useState } from 'react' import type { ChatPlan } from '../plans/index' +/** Represent durable plan decisions as either approved or rejected */ export type DurablePlanDecision = 'approved' | 'rejected' /** Stable authority receipt for the follow-up turn dispatched by a plan @@ -14,6 +15,7 @@ export interface DurablePlanFollowUpReceipt { state: string } +/** Describe the result of a durable plan decision including plan details and pending statuses */ export interface DurablePlanDecisionResult { plan: ChatPlan followUp?: DurablePlanFollowUpReceipt @@ -22,6 +24,7 @@ export interface DurablePlanDecisionResult { effectPending?: boolean } +/** Define input parameters for making a durable plan decision including optional feedback */ export interface DurablePlanDecisionInput { planId: string revision: number @@ -29,16 +32,19 @@ export interface DurablePlanDecisionInput { feedback?: string } +/** Define input parameters for retrieving the current durable plan including optional revision number */ export interface DurablePlanCurrentInput { planId: string revision?: number } +/** Define methods to obtain and decide durable plan decisions asynchronously */ export interface DurablePlanDecisionClient { current: (input: DurablePlanCurrentInput) => Promise decide: (input: DurablePlanDecisionInput) => Promise } +/** Represent errors from DurablePlanClient operations including status, code, and current plan details */ export class DurablePlanClientError extends Error { constructor( message: string, @@ -51,6 +57,7 @@ export class DurablePlanClientError extends Error { } } +/** Define configuration options for creating a durable plan decision client */ export interface DurablePlanDecisionClientOptions { url: string | ((input: DurablePlanCurrentInput | DurablePlanDecisionInput) => string) body?: Record | ((input: DurablePlanDecisionInput) => Record) @@ -153,6 +160,7 @@ export function createDurablePlanDecisionClient( } } +/** Define options to configure durable plan flow with plan, client, and optional callbacks */ export interface UseDurablePlanFlowOptions { plan: ChatPlan client: DurablePlanDecisionClient @@ -161,6 +169,7 @@ export interface UseDurablePlanFlowOptions { onUpdated?: (plan: ChatPlan) => void } +/** Define the result and actions for managing a durable plan flow including decisions, restoration, and error handling */ export interface UseDurablePlanFlowResult { plan: ChatPlan deciding: DurablePlanDecision | null diff --git a/src/web-react/index.tsx b/src/web-react/index.tsx index 6fdf9c5..16cac56 100644 --- a/src/web-react/index.tsx +++ b/src/web-react/index.tsx @@ -66,6 +66,7 @@ export type { CatalogModel } from '../runtime/model-catalog' // ── metrics helpers ─────────────────────────────────────────────────────── +/** Describe metrics related to a chat message including model, token counts, and duration */ export interface ChatMessageMetrics { modelUsed?: string promptTokens?: number @@ -112,6 +113,7 @@ export interface ToolRunRecord { steps: ToolRunStep[] } +/** Define properties required to run a drill and handle its closure event */ export interface RunDrillInProps { run: ToolRunRecord onClose: () => void @@ -178,6 +180,7 @@ export function RunDrillIn({ run, onClose }: RunDrillInProps) { // ── ChatMessages ────────────────────────────────────────────────────────── +/** Describe the structure and state of a tool call within a chat interaction */ export interface ChatToolCallInfo { id: string name: string @@ -207,6 +210,7 @@ export type ChatMessageSegment = | { kind: 'text'; content: string } | { kind: 'tool'; call: ChatToolCallInfo } +/** Describe the structure and properties of a chat message with roles, content, and optional metadata */ export interface ChatUiMessage extends ChatMessageMetrics { id: string role: 'user' | 'assistant' | 'system' @@ -222,6 +226,7 @@ export interface ChatUiMessage extends ChatMessageMetrics { parts?: Array> } +/** Define properties for rendering chat messages with optional models, markdown, extras, and durable cards */ export interface ChatMessagesProps { messages: ChatUiMessage[] /** Catalogue models, for per-message cost from pricing. Pass [] to skip cost. */ @@ -279,6 +284,7 @@ export interface ChatEmptyDoor { onSelect: () => void } +/** Define properties for rendering the chat empty state with customizable text and starting doors */ export interface ChatEmptyStateProps { /** Product name shown next to the Tangle mark. Default "Agent". */ productName?: string @@ -332,6 +338,7 @@ export function ChatEmptyState({ ) } +/** Handle approval and rejection actions for proposals with asynchronous support */ export interface ProposalApprovalHandlers { onApprove: (proposalId: string, toolCallId: string) => void | Promise onReject: (proposalId: string, toolCallId: string) => void | Promise diff --git a/src/web-react/interaction-card-support.ts b/src/web-react/interaction-card-support.ts index 01465b7..5e99f90 100644 --- a/src/web-react/interaction-card-support.ts +++ b/src/web-react/interaction-card-support.ts @@ -44,6 +44,7 @@ export function interactionTerminalNotes( // --------------------------------------------------------------------------- // Answer building +/** Define a record mapping field names to objects with optional selected, text, and custom string arrays or values */ export type FieldValues = Record /** Converts acknowledged, persisted answers back into the local field state @@ -108,6 +109,7 @@ export function buildAnswerData(fields: ChatInteractionField[], values: FieldVal // a NEW chat turn carrying the question context, so the user's typed answer is // never dropped on the floor. +/** Determine if a status is late answerable by checking if it is expired or cancelled */ export function isLateAnswerableStatus(status: ChatInteractionStatus): boolean { return status === 'expired' || status === 'cancelled' } @@ -159,7 +161,9 @@ export function lateAnswerMessage(interaction: ChatInteraction, data: Interactio // --------------------------------------------------------------------------- // Submit plumbing +/** Define the timeout duration in milliseconds for submitting an interaction */ export const INTERACTION_SUBMIT_TIMEOUT_MS = 30_000 +/** Provide the timeout message displayed when the agent cannot be reached during interaction submission */ export const INTERACTION_SUBMIT_TIMEOUT_MESSAGE = 'Could not reach the agent. Try again.' /** One card submission: which ask, resolved how, with what answers. */ @@ -169,6 +173,7 @@ export interface InteractionAnswerSubmission { data?: InteractionData } +/** Resolve the result of an interaction submission indicating success or failure with details */ export type InteractionSubmitResult = | { ok: true } | { ok: false; expired: boolean; message: string } @@ -194,6 +199,7 @@ export async function responseErrorMessage(res: Response): Promise<{ code?: stri return { message: `Answer failed (${res.status})` } } +/** Define options for submitting interaction answers including URL, body, timeout, and fetch implementation */ export interface InteractionAnswerSubmitterOptions { /** The product's answer route (the POST half of `createInteractionAnswerRoute`). * A function when the URL carries the session (e.g. `/api/sessions/${id}/interactions`). */ diff --git a/src/web-react/sandbox-terminal.ts b/src/web-react/sandbox-terminal.ts index c703e50..0a47c71 100644 --- a/src/web-react/sandbox-terminal.ts +++ b/src/web-react/sandbox-terminal.ts @@ -1,5 +1,6 @@ import { useCallback, useEffect, useRef, useState } from 'react' +/** Define the connection details and status for a sandbox terminal session */ export interface SandboxTerminalConnection { runtimeUrl: string | null sidecarUrl: string | null @@ -11,6 +12,7 @@ export interface SandboxTerminalConnection { sandboxId?: string } +/** Define the response structure for a sandbox terminal connection including URLs, token, status, and errors */ export interface SandboxTerminalConnectionResponse { runtimeUrl?: string sidecarUrl?: string @@ -21,6 +23,7 @@ export interface SandboxTerminalConnectionResponse { sandboxId?: string } +/** Define options for configuring a sandbox terminal connection including workspace ID and connection parameters */ export interface UseSandboxTerminalConnectionOptions { workspaceId: string connectionUrl?: string | ((workspaceId: string) => string) @@ -30,6 +33,7 @@ export interface UseSandboxTerminalConnectionOptions { tokenRefreshSkewMs?: number } +/** Resolve sandbox terminal connection status and provide a method to initiate the connection */ export interface UseSandboxTerminalConnectionResult extends SandboxTerminalConnection { connect: () => Promise } @@ -48,6 +52,7 @@ const EMPTY_CONNECTION: SandboxTerminalConnection = { loading: false, } +/** Manage and maintain a sandbox terminal connection with automatic polling and token refresh handling */ export function useSandboxTerminalConnection(opts: UseSandboxTerminalConnectionOptions): UseSandboxTerminalConnectionResult { const [conn, setConn] = useState(EMPTY_CONNECTION) const mountedRef = useRef(false) diff --git a/src/web-react/smooth-text.ts b/src/web-react/smooth-text.ts index 0e2ec0e..0aed635 100644 --- a/src/web-react/smooth-text.ts +++ b/src/web-react/smooth-text.ts @@ -10,6 +10,7 @@ import { useEffect, useRef, useState } from 'react' +/** Define configuration options for controlling smooth text reveal animation rates */ export interface SmoothRevealOptions { /** Baseline reveal rate when nearly caught up. Default 90 chars/s. */ baseCharsPerSecond?: number diff --git a/src/web-react/use-chat-interactions.ts b/src/web-react/use-chat-interactions.ts index f852d30..f692315 100644 --- a/src/web-react/use-chat-interactions.ts +++ b/src/web-react/use-chat-interactions.ts @@ -109,8 +109,10 @@ export function terminalizePendingChatInteractions( return list.map((item) => (item.status === 'pending' ? { ...item, status } : item)) } +/** Define modes for restoring chat interactions with legacy or durable strategies */ export type ChatInteractionRestoreMode = 'legacy' | 'durable' +/** Define options to control how chat interactions are restored during the restore process */ export interface RestoreChatInteractionsOptions { /** * `legacy` settles pending asks absent from the sidecar list as answered, @@ -168,6 +170,7 @@ export function hydrateChatInteractions( return persisted.reduce(upsertChatInteraction, list) } +/** Resolve and manage chat interactions with methods to update, cancel, mark resolved, and restore state */ export interface UseChatInteractionsResult { /** All known interactions, insertion-ordered. */ interactions: ChatInteraction[] @@ -189,8 +192,10 @@ export interface UseChatInteractionsResult { reset: () => void } +/** Resolve options for restoring chat interactions from previous sessions */ export type UseChatInteractionsOptions = RestoreChatInteractionsOptions +/** Manage chat interactions state with upsert, cancel, resolve, and restore capabilities */ export function useChatInteractions(options: UseChatInteractionsOptions = {}): UseChatInteractionsResult { const [interactions, setInteractions] = useState([]) diff --git a/src/web-react/use-composer-attachments.ts b/src/web-react/use-composer-attachments.ts index 1694f3c..e8ed3f8 100644 --- a/src/web-react/use-composer-attachments.ts +++ b/src/web-react/use-composer-attachments.ts @@ -65,6 +65,7 @@ interface StagedAttachment { errorMessage?: string } +/** Define options for configuring file upload behavior and handling in a composer component */ export interface UseComposerAttachmentsOptions { /** Simple upload target: every file POSTs here. Ignored when * `buildUploadRequest` is provided. */ @@ -100,6 +101,7 @@ export interface UseComposerAttachmentsOptions { enabled?: boolean } +/** Provide staged file chips, ready attachments, and methods to add, retry, or drop composer files */ export interface UseComposerAttachmentsResult { /** Chip models for `ChatComposer`'s `pendingFiles` prop, one per staged * file — `kind` is always `'file'` (agent-app's `ComposerFile.kind` diff --git a/src/web-react/use-file-mentions.ts b/src/web-react/use-file-mentions.ts index 42fc0fb..fe824c3 100644 --- a/src/web-react/use-file-mentions.ts +++ b/src/web-react/use-file-mentions.ts @@ -120,6 +120,7 @@ export const INDEX_REFRESH_AFTER_MS = 5 * 60 * 1000 * Loading/warming/error states have their own copy — see `emptyTextFor`. */ export const DEFAULT_MENTION_EMPTY_TEXT = 'No matching files' +/** Define options for configuring file mention fetching, caching, and display behavior */ export interface UseFileMentionsOptions { /** GET endpoint returning `FileIndexResponse` (a `createSandboxFileIndexRoute`). */ indexUrl: string @@ -135,6 +136,7 @@ export interface UseFileMentionsOptions { emptyText?: string } +/** Provide properties and methods to manage and refresh file mentions in a composer interface */ export interface UseFileMentionsResult { /** Spread straight into `AgentComposer`'s `mention` prop. */ mention: ComposerMentionProp @@ -167,6 +169,7 @@ function emptyTextFor(state: IndexState, fallback: string): string { } } +/** Resolve and manage file mention data with configurable fetching and state handling */ export function useFileMentions(options: UseFileMentionsOptions): UseFileMentionsResult { const { indexUrl, diff --git a/src/web/index.ts b/src/web/index.ts index 7902f6b..fd60b01 100644 --- a/src/web/index.ts +++ b/src/web/index.ts @@ -32,6 +32,7 @@ export function requireString(body: JsonObject, field: string): string | Respons return v } +/** Define the context of a request including IP address, user agent, timestamp, and request ID */ export interface RequestContext { ipAddress: string userAgent: string @@ -60,6 +61,7 @@ export interface KvLike { put(key: string, value: string, options?: { expirationTtl?: number }): Promise } +/** Describe the outcome of a rate limit check including allowance, remaining count, and reset time */ export interface RateLimitResult { allowed: boolean remaining: number @@ -117,6 +119,7 @@ function parseRateLimitState(raw: string | null): number[] | typeof POISONED_STA return parsed.filter((t): t is number => typeof t === 'number' && Number.isFinite(t)) } +/** Define options for configuring cookie attributes and behavior */ export interface CookieOptions { name: string /** Default '/'. */ @@ -167,6 +170,7 @@ export function readCookieValue(cookieHeader: string | null, name: string): stri return null } +/** Define options for configuring security-related HTTP headers including disclaimers and retention labels */ export interface SecurityHeaderOptions { /** Product disclaimer (e.g. "AI-powered tool. Not legal advice."). Omitted if absent. */ disclaimer?: string From 75086e474d8234de274dcff29c2268f956995644 Mon Sep 17 00:00:00 2001 From: Drew Stone Date: Fri, 24 Jul 2026 13:56:37 -0600 Subject: [PATCH 2/2] test(codemap): raise freshness-gate timeout above vitest's 5s default The generator's --check spawns a full source walk; with the JSDoc pass it now exceeds the 5000ms default in CI. Bump to 60s (it's a subprocess, not hot code). --- tests/codemap-fresh.test.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/codemap-fresh.test.ts b/tests/codemap-fresh.test.ts index 5f69ee5..fd4964b 100644 --- a/tests/codemap-fresh.test.ts +++ b/tests/codemap-fresh.test.ts @@ -19,9 +19,11 @@ const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..') const script = join(repoRoot, 'scripts', 'gen-codemap.mjs') describe('codemap freshness', () => { + // Spawns the generator over the whole source tree; the walk scales with the + // number of documented exports, so give it well over vitest's 5s default. it('committed docs/CODEMAP.md + docs/api/*.md match the current source', () => { const res = spawnSync(process.execPath, [script, '--check'], { encoding: 'utf8' }) const detail = `${res.stdout ?? ''}${res.stderr ?? ''}`.trim() expect(res.status, `codemap --check failed — run \`pnpm docs:gen\` and commit:\n${detail}`).toBe(0) - }) + }, 60_000) })