API, metadata, and workspace runtime
The backend API runtime turns an authenticated request into a bounded workspace action. It resolves the caller, workspace model, permissions, data source, and current metadata before it reads records, changes the model, uses an integration, or starts an AI run. REST, GraphQL, MCP, metadata services, and AI services use this boundary. For the wider server layout, see Backend application platform. For persistence and emitted events, see Data persistence and event processing.
Request boundary
The request boundary changes transport input into trusted workspace runtime data. Middleware loads identity and workspace state. Guards then decide if the request may enter a protected API path.
flowchart LR
A[Credential or session] --> B[Request middleware]
B --> C[Caller and workspace context]
C --> D[Authentication and feature guards]
D --> E[API operation]
E --> F[Metadata and workspace data]
Request hydration
Request hydration turns a token or session into request data for later steps. The data includes the caller, workspace, metadata version, feature state, and schema state. REST needs a usable workspace data source. GraphQL can serve public requests without workspace data.
Each transport keeps its own response shape after hydration:
| API style | Result when hydration fails |
|---|---|
| REST | An HTTP response with a status code and JSON error body. |
| GraphQL | A GraphQL error response. Public requests may continue without workspace data. |
| MCP | A JSON-RPC result or error after the workspace and caller role are resolved. |
Middleware also places the workspace metadata version in request-local state. It rejects a workspace with no usable schema and keeps agent-token traffic on the MCP path instead of the normal GraphQL record path.
References: packages/…/middleware.service.ts• L60-116 packages/…/middleware.service.ts• L118-206 packages/…/build-workspace-auth-context-from-request.util.ts• L27-75
Authentication guards
Authentication guards protect the controller or resolver boundary after middleware places identity data on the request. A principal is the caller identity supplied by a user session, API key, OAuth client, application, system process, or agent.
The guards apply several checks:
- User paths require a user principal.
- Workspace paths require a resolved workspace.
- REST chains credential, workspace, and custom-permission checks.
- MCP accepts several caller forms but still requires a valid workspace and allowed principal.
- Feature and settings guards protect optional product areas.
- Metadata, view, AI, MCP-server, and usage paths add permission checks for model changes or protected services.
Principal classification rejects unsafe combinations. Server-admin and admin-panel paths reject a request that is already impersonating another identity.
References: packages/…/auth-principal.guard.ts• L19-47 packages/…/jwt-auth.guard.ts• L14-57 packages/…/classify-auth-principal.util.ts• L10-84 packages/…/admin-panel-guard.ts• L9-20
Workspace authorization context
The workspace authorization context describes who acts in which workspace. It carries the principal kind, workspace state, roles, feature flags, application scope, and AI run scope needed by permissions, repositories, usage tracking, hooks, and events.
The supported context types include user, API key, application, system, and pending-activation user. An AI run can narrow a user, API key, or application context to an agent and an optional run scope. Background jobs rebuild this context because queue workers have no request-local storage.
References: packages/…/workspace-auth-context.type.ts• L6-66 packages/…/build-workspace-auth-context-from-request.util.ts• L27-75 packages/…/agent-run-caller-context.service.ts• L31-79 packages/…/agent-run-caller-context.service.ts• L81-123
API operations
The API styles share one workspace operation model. Each transport supplies input and formats output. Common runners apply metadata rules, permission checks, query limits, usage checks, repository access, and result visibility before the transport returns data.
Common workspace operations
Common runners handle record reads, writes, grouping, duplicate checks, bulk creation, upsert, restore, delete, and merge. They resolve names and values against the current workspace model before a repository reads or changes records.
The operation contract includes these controls:
- Root requests consume API speed limits and record API complexity usage when usage tracking is enabled.
- Read-only work may use a replica. Writes use the primary data source. Nested reads follow the root read choice.
- Metadata controls field types, filter operators, relations, grouping, selected fields, and option values.
- Permission checks cover objects, fields, rows, and record shares.
- Relation depth, selected fields, bulk filters, nested creates, merges, and batch sizes stay bounded.
- Nested writes and record shares use one write scope when related rows must stay together.
- Upsert uses ID and active unique-field metadata to separate inserts from updates. Composite fields and composite unique indexes can identify a record. A soft-deleted record is ignored when its unique index excludes deleted rows. If different unique values point to different records, the operation stops rather than choosing one.
- Returned records keep input order.
- Merge protects unreadable values and moves or removes related records in one transaction.
- Post-query hooks run after visibility checks. Transactional hooks run after commit.
Record input is checked against active field metadata before storage. The runtime maps field and relation names, validates type-specific values and options, and converts values to the form expected by the data source. Relation writes require supported nested operations. A relation target's connect filter is processed with that target's field metadata.
Nested relation reads accept a bounded set of filter, order, and page arguments. The runtime normalizes one order object to the common order list, limits records per parent, applies row access to the relation query, and hydrates only the selected fields. A small concurrency limit keeps several relation branches from creating unbounded database work.
References: packages/…/common-base-query-runner.service.ts• L125-190 packages/…/common-base-query-runner.service.ts• L253-313 packages/…/data-arg-processor.service.ts• L78-188 packages/…/data-arg-processor.service.ts• L267-321 packages/…/process-nested-relations.helper.ts• L69-124 packages/…/process-nested-relations.helper.ts• L289-337 packages/…/extract-nested-relation-query-args.util.ts• L20-97
Field selection and relation reads
Field selection turns requested fields or depth into a readable projection. It removes fields and relation targets that the caller cannot read. One-to-many relations need a positive depth so a normal record request cannot expand without a bound.
Nested relation reads use the same workspace metadata and permission context as the root query. They keep the root read source, limit records per parent, and cap relation work. A disabled or unreadable target does not make the root record readable.
References: packages/…/common-select-fields-builder.ts• L29-89 packages/…/common-select-fields-builder.ts• L91-173 packages/…/graphql-selected-fields.parser.ts• L96-207 packages/…/process-nested-relations.helper.ts• L65-117
Filters and grouping
Filters, ordering, grouping, and duplicate checks are metadata-driven. The runtime resolves each field against the current workspace maps and checks readability before a condition, sort, group key, aggregate, or cursor can affect a result.
Relation filters have bounded depth. A to-many filter uses an existence check when a join could duplicate root records. Grouped reads can add saved-view filters and can return a bounded set of records for each group. Grouping on a relation adds the needed join. When grouped records are requested, both group size and record field work count toward query complexity.
REST filter parsing also checks balanced parentheses and keeps commas inside quotes or value lists from splitting the wrong predicate. This makes malformed or ambiguous filter input fail before it reaches the common query model.
References: packages/…/graphql-query-filter-field.parser.ts• L84-176 packages/…/common-group-by-query-runner.service.ts• L84-189 packages/…/common-group-by-query-runner.service.ts• L207-388 packages/…/check-filter-query.util.ts• L13-54 packages/…/parse-filter-content.util.ts• L7-58
REST operations
The REST API maps HTTP paths and verbs to common workspace operations. It resolves the workspace object and caller role, then parses fields, filters, ordering, cursors, aggregates, views, and relation depth before it runs the operation.
REST object names resolve through plural metadata names. The response stays within selected-field and default-field limits. Settings callers can also reach metadata and view resources through the same protected boundary.
References: packages/…/rest-api-core.service.ts• L44-109 packages/…/rest-api-base.handler.ts• L72-264 packages/…/parse-metadata-rest-pagination.util.ts• L13-50
GraphQL schema and execution
The workspace GraphQL API is generated from current workspace metadata. It exposes object queries and mutations that match the active workspace model. An application-scoped schema limits that model to the application view while retaining the standard application operations needed by that scope.
Schema generation maps objects, fields, options, indexes, relations, queries, and mutations into GraphQL types. Composite fields receive separate input shapes for filtering, ordering, and updates. A schema cache is keyed by the combined metadata hashes used for schema generation. Direct execution classifies a request before normal resolver work, applies omitted variable defaults, collects selected fields, and formats records against metadata. It rejects a request that mixes core and workspace fields. GraphQL also limits selected fields, root resolvers, duplicate roots, and total query complexity.
References: packages/…/workspace-graphql-schema-sdl.service.ts• L48-180 packages/…/schema-sdl-cache-dependencies.constant.ts• L1-7 packages/…/gql-type.generator.ts• L31-137 packages/…/composite-field-metadata-filter-gql-input-types.generator.ts• L33-112 packages/…/composite-field-metadata-order-by-gql-input-type.generator.ts• L28-84 packages/…/composite-field-metadata-update-gql-input-type.generator.ts• L33-109 packages/…/direct-execution.service.ts• L195-339 packages/…/apply-graphql-variable-defaults.util.ts• L4-24
MCP tool interface
The MCP interface exposes workspace actions as named tools for AI clients through JSON-RPC 2.0. The endpoint accepts user, API key, OAuth client, and application callers after the same workspace access checks as other protected APIs. It supports normal JSON responses, notification requests with no response body, and server-sent events for streamed results.
MCP has three tool modes:
| Mode | Purpose |
|---|---|
generic | Keeps a stable record tool set across workspaces. The caller passes the object name as an argument and discovers fields from metadata. |
direct | Lists the caller's permitted object and action tools with their schemas. |
meta | Lists a small set of discovery and execution tools. The caller learns schemas and runs named tools through those meta-tools. |
Initialization returns protocol details and instructions for the selected mode. Generic mode lists stable record tools and selected discovery tools. Direct and meta modes build a role-bound tool set from current workspace state. Tool schemas and annotations distinguish read-only work from writes. Tool calls can still be forwarded to execution when a client uses an object-specific name from an earlier tool list.
Generic record tools cover reads, grouped metrics, creates, updates, upserts, deletes, and merges. Their schemas stay workspace-independent so clients can cache them. They validate arguments before dispatch, keep default reads small, and reject filters that use argument names such as limit or select instead of silently dropping them.
The instructions also separate skills from tools. Skills explain how to complete complex work. Tools perform the work. Destructive record actions require a matching read and explicit confirmation in the client flow.
References: packages/…/mcp-protocol.service.ts• L108-128 packages/…/mcp-protocol.service.ts• L339-409 packages/…/mcp-protocol.service.ts• L412-475 packages/…/generic-record-tools.tool.ts• L227-333
API error mapping
API error mapping keeps shared runtime failures independent of transport. REST reports HTTP exceptions. GraphQL reports GraphQL errors. MCP reports protocol failures as JSON-RPC errors and tool failures as error-marked results.
The shared failure meanings include invalid input, denied access, record-share errors, throttling, usage limits, authentication errors, and data-source errors. Database error codes stay inside the workspace query executor so transport handlers do not depend on one database source.
References: packages/…/middleware.service.ts• L60-116 packages/…/workspace-query-runner-rest-api-exception-handler.util.ts• L21-40 packages/…/workspace-query-runner-graphql-api-exception-handler.util.ts• L34-67 packages/…/build-json-rpc-error.util.ts• L26-47
Workspace metadata
Workspace metadata is the model that gives meaning to records and API fields. The runtime resolves one effective model and shares it with schema builders, validation, permissions, migrations, views, tools, caches, and repositories.
Effective workspace model
The workspace model describes workspace identity, readiness, database schema, access settings, product settings, and application-owned resources. Flat metadata maps provide fast lookups by ID and universal identifier.
The maps connect objects, fields, indexes, views, permissions, roles, applications, navigation items, agents, workflows, validation rules, related-record paths, MCP servers, and messaging providers. Universal identifiers keep links stable when an application or workspace model changes.
References: packages/…/workspace.entity.ts• L66-74 packages/…/workspace-flat-object-metadata-map-cache.service.ts• L13-61 packages/…/workspace-many-or-all-flat-entity-maps-cache.service.ts• L12-51
Effective metadata overrides
Effective metadata is the value visible to the current workspace and application after authored overrides are applied. An override changes selected properties without replacing the base record. A workspace translation is preferred for the requested locale. The base value remains the fallback.
The effective value drives API labels, active state, view settings, field rules, migration checks, AI object selection, and metadata responses. The same value must therefore be used for display and runtime checks.
References: packages/…/resolve-effective-flat-entity.util.ts• L10-38 packages/…/resolve-effective-entity-property.util.ts• L42-169 packages/…/all-overridable-properties-by-metadata-name.constant.ts• L11-32
Field options
Field options define allowed values and display data for select-like fields. Stored values stay separate from labels, colors, and positions. The runtime resolves option rows into the field view used by API responses and input checks.
Updates keep option identity when an update has no explicit ID and the value matches an existing option. Removed or renamed values can also update or delete saved view filters that depend on them. Defaults must refer to valid option values.
References: packages/…/resolve-flat-field-metadata-options.util.ts• L21-47 packages/…/normalize-updated-field-metadata-options.util.ts• L12-53 packages/…/recompute-view-filters-on-flat-field-metadata-options-update.util.ts• L24-114 packages/…/field-metadata.service.ts• L70-105
Views and navigation
Views are workspace metadata that describe how records are filtered, sorted, grouped, and shown. The view path resolves field links through current flat maps and turns a visible view into normal record query parameters. Navigation items link applications to objects, views, layouts, channels, workflows, or agents.
View updates use effective values and current option maps. A view can change visibility or translated properties, but visibility remains part of the access decision. A saved view cannot grant access to records or fields that the caller cannot read.
References: packages/…/view-query-params.service.ts• L45-149 packages/…/from-update-view-input-to-flat-view-to-update-or-throw.util.ts• L67-150 packages/…/from-update-view-input-to-flat-view-to-update-or-throw.util.ts• L224-252 packages/…/workspace-flat-navigation-menu-item-map-cache.service.ts• L13-88
Permission maps
Permission maps combine roles, object permissions, field permissions, row-level rules, feature flags, record shares, private records, and application scope into one record access policy. The policy answers whether a caller can access an object and whether specific record IDs are admitted.
Row-level permission rules group predicates by application, role, object, and root predicate group. A missing role or unresolved rule does not fall through to a share grant. The same access decision protects API reads and emitted event snapshots.
References: packages/…/workspace-roles-permissions-cache.service.ts• L22-125 packages/…/build-row-level-permission-rules.util.ts• L17-163 packages/…/record-access-policy.service.ts• L93-224
Metadata migration
Metadata changes are product changes because they alter both the API model and the workspace data model. The migration path loads related maps, expands side effects, validates the target model, orders actions, applies schema and metadata changes, commits the change, emits metadata events, and refreshes affected caches.
Validation checks references and cross-system rules before a change runs. Examples include role ownership and entitlements, row-rule field and relation paths, connection provider shape, agent trigger shape, and agent response format. Invalid predicates fail closed rather than removing a row restriction.
Object metadata changes enter this boundary as one migration. Creation can add the object fields and initial workspace links. Deletion expands to related fields, indexes, views, and field options. Compatible object updates can share one migration, while changes that rewrite related schema or search state must run alone. The service recomputes the object maps after success and refreshes related permission or navigation state.
Object and field changes can affect indexes, views, layouts, relation paths, permissions, workflows, navigation, and generated APIs. Universal identifiers resolve these links. Work that cannot finish in the request is stored as a deferred workspace operation and dispatched after commit. Schema-affecting operations block a conflicting migration until they finish.
References: packages/…/object-metadata.service.ts• L61-279 packages/…/object-metadata.service.ts• L299-648 packages/…/workspace-migration-validate-build-and-run-service.ts• L323-401 packages/…/workspace-migration-build-orchestrator.service.ts• L397-491 packages/…/workspace-migration-flat-entity-maps.service.ts• L51-83 packages/…/flat-role-validator.service.ts• L27-84
Deferred workspace operations
Deferred workspace operations finish work that is too slow or unsafe for the metadata transaction. The migration stores a typed operation after its metadata transaction. A workspace queue claims pending operations in order and retries failures with bounded attempts.
The operation set includes index creation, foreign-key validation, object rebuilds, logic-function resource cleanup, and workflow-run cleanup. Schema-affecting operations include index creation, foreign-key validation, and object rebuilds. A recovery job resets stale workers, requeues pending work, and marks exhausted work as failed. Operators can retry failed work for one workspace or for all workspaces.
The flow keeps migration and schema work consistent:
sequenceDiagram
participant M as Migration
participant D as Deferred operation store
participant Q as Workspace queue
participant W as Worker
participant R as Recovery job
M->>D: Store operation in transaction
M->>Q: Enqueue after commit
Q->>W: Run workspace operations
W->>D: Claim, execute, delete or record failure
R->>D: Reset stale work and requeue pending work
References: packages/…/deferred-workspace-operation-runner.service.ts• L61-158 packages/…/deferred-workspace-operation-runner.service.ts• L306-389 packages/…/deferred-workspace-operation-recovery.service.ts• L22-85 packages/…/schema-affecting-deferred-workspace-operations.constant.ts• L1-7
Standard application model
Workspace initialization synchronizes the Twenty standard application with the workspace-owned metadata model. It preserves workspace-owned properties, creates permission tables when enabled, sets the default role, and seeds initial views through the same migration boundary used by later changes.
Standard metadata supplies stable indexes, command actions, and skills for common record and automation work. The standard application path can omit permission-storage objects while the permission-table feature is active. This prevents transitional storage objects and their dependents from entering the standard application snapshot.
References: packages/…/twenty-standard-application.service.ts• L42-156 packages/…/compute-company-standard-flat-index-metadata.util.ts• L9-61 packages/…/temporary-omit-permission-storage-objects-from-twenty-standard-all-flat-entity-maps.util.ts• L29-77
Cache layers
Caches keep workspace-derived data fast without allowing a process to use an old workspace model. Source metadata comes from workspace rows. Derived data includes flat maps, permission maps, API dispatch maps, schemas, views, tool maps, channel maps, relation paths, messaging routes, and field options.
Workspace cache
The workspace cache serves derived data by workspace ID and cache key. A provider reads source rows and computes one value. Local entries give fast reads. Shared cache state gives processes a common freshness signal.
The cache checks a local entry against the shared hash before it trusts the value. A missing value, changed hash, or failed expansion causes a shared read or provider recompute. Derived maps keep the hash of the source snapshot they depend on.
References: packages/…/workspace-cache.service.ts• L224-281 packages/…/workspace-cache.service.ts• L314-369 packages/…/workspace-cache.service.ts• L563-665
Metadata map caches
Flat map caches combine related metadata rows into lookup maps. Object maps include fields, views, permissions, layouts, and navigation links. Field maps include indexes, views, permissions, options, and row-rule links. Other providers build maps for roles, agents, workflows, channels, logic functions, and providers.
Some maps use a compact stored form and expand it when read. Migration code can apply safe changes to in-memory maps before the committed snapshot is available. Consumers should use the map service rather than build a second model from raw rows.
References: packages/…/workspace-flat-object-metadata-map-cache.service.ts• L63-136 packages/…/workspace-flat-field-metadata-map-cache.service.ts• L74-195 packages/…/workspace-many-or-all-flat-entity-maps-cache.service.ts• L21-87
API caches
API caches store values derived from metadata rather than source records. GraphQL schema and operation keys include metadata dependencies, query and variables, locale, and user-workspace scope when a result is user-specific.
Direct GraphQL execution uses a cached resolver-name map. Metadata GraphQL caches object metadata at workspace scope and views at user-workspace scope. Workspace GraphQL SDL uses object, field, option, index, and application map hashes. MCP rebuilds its mode-specific instructions and role-bound tool set from current maps and tool catalogs. This keeps generated APIs, metadata responses, and AI tools on the same effective snapshot.
References: packages/…/use-cached-metadata.ts• L10-215 packages/…/metadata-graphql-operations-to-cache.constant.ts• L4-35 packages/…/workspace-graphql-schema-sdl.service.ts• L139-170 packages/…/workspace-resolver-name-map-cache.service.ts• L14-30 packages/…/mcp-protocol.service.ts• L412-439
Cache invalidation
Metadata changes drive cache invalidation. The migration runner maps changed metadata to direct and derived keys. Schema-affecting changes also advance the workspace metadata version.
Relations and special side effects widen invalidation. Index changes affect object and field maps. Field-option changes affect field maps and views. Object label-identifier changes refresh role permissions. Object activation changes invalidate navigation and command maps. Deleting roles or row rules can affect field permission aggregates. A new cache consumer must join the dependency map or it can use stale workspace state.
References: packages/…/object-metadata.service.ts• L261-276 packages/…/get-flat-entity-maps-keys-to-invalidate-for-workspace-migration.util.ts• L16-81 packages/…/workspace-migration-runner.service.ts• L56-117 packages/…/workspace-many-or-all-flat-entity-maps-cache.service.ts• L53-87
Workspace data sources
The runtime separates core workspace metadata from tenant records. Workspace-aware repositories expose both through one metadata and permission contract while the physical stores remain distinct.
Core metadata store
The core PostgreSQL data source stores workspace rows and metadata rows that describe each workspace. Cache providers read these rows to build flat maps. The same core connection creates and removes workspace schemas during workspace lifecycle work.
Workspace creation establishes the schema before it creates and synchronizes standard application metadata. Protected APIs use the workspace only after its schema and access model are ready.
References: packages/…/workspace-schema.service.ts• L14-59 packages/…/workspace.service.ts• L1-180 packages/…/workspace-cache.service.ts• L685-717
Workspace record store
The workspace record store reads tenant records through a workspace-aware PostgreSQL data source. Read-only work may use a replica. Writes use the primary pool. If no replica exists, reads use the primary pool.
The repository is the access boundary for field mapping, object permissions, row rules, relation loading, record formatting, and database event emission. A caller cannot select an object outside the current workspace maps. Common runners receive the repository and the current feature, option, permission, and record-read context together.
References: packages/…/workspace-data-source.service.ts• L39-131 packages/…/workspace-data-source.ts• L36-183 packages/…/workspace-orm.manager.ts• L80-133 packages/…/common-base-query-runner.service.ts• L369-391 packages/…/common-extended-query-runner-context.type.ts• L11-22
Workspace permission filters
Object permissions and row-level rules become query conditions before a workspace record is read or changed. A rule that cannot resolve a caller value becomes a never-match branch instead of being dropped.
These filters protect direct records and records reached through relations. The policy also checks record shares and private records when a request names specific record IDs.
References: packages/…/record-access-policy.service.ts• L176-224 packages/…/build-row-level-permission-record-filter.util.ts• L93-321 packages/…/workspace-roles-permissions-cache.service.ts• L101-123
Workspace event fan-out
Record changes leave the repository as workspace event batches. The event path uses current metadata maps to find matching webhooks, logic functions, and agent triggers. It can also create timeline, subscription, and audit-log work.
Event delivery applies role, row, and field access before it returns an event or sends it to an agent. Updates that change only hidden fields are not exposed. For the event pipeline after this API boundary, see Data persistence and event processing.
References: packages/…/record-access-policy.service.ts• L295-432 packages/…/call-webhook-jobs.job.ts• L1-180 packages/…/call-agent-database-event-triggers.job.ts• L67-178
Connected account source
Connected account metadata describes external mail and calendar access within a workspace. The runtime filters accounts by provider capability, ownership, scope, archive state, and caller context before it exposes an account to a service.
Workspace-shared accounts need the matching administration permission when another member owns them. Disconnect and ownership transfer clear credentials, stop channel subscriptions, disable sync, and emit deletion events so external paths do not keep old access.
References: packages/…/connected-account-metadata.service.ts• L64-177 packages/…/connected-account-metadata.service.ts• L204-300 packages/…/connected-account-metadata.service.ts• L412-514
Application messaging source
Application messaging resolves a channel, usable connected account, provider, application-owned send function, and conversation participants before it sends a message. Idempotency and a delivery lock make a retry return one delivery instead of sending duplicates.
The sender rejects a missing provider, missing application function, invalid function result, or wrong conversation style. The send path then ingests the accepted delivery back into workspace message records. Read actions use the same channel and participant boundary.
References: packages/…/application-message-send.service.ts• L106-230 packages/…/application-message-read.service.ts• L1-220 packages/…/messaging-provider-message-sender.service.ts• L27-113
MCP server source
An MCP server is a workspace application endpoint that may need a connected account before a caller can use it. The runtime keeps the server, its sign-in provider, and its connection-provider link in the same metadata migration boundary.
Only workspace-owned custom servers receive generated sign-in providers. A URL or sign-in-scope change can replace that provider because stored tokens remain tied to the old resource. The connection lookup prefers an account owned by the current user and otherwise uses an allowed workspace account. Missing or unrecoverable credentials become a sign-in error and mark the account as failed.
References: packages/…/mcp-server-sign-in.service.ts• L44-124 packages/…/mcp-server-sign-in.service.ts• L127-194 packages/…/mcp-server-connected-account.service.ts• L45-95 packages/…/mcp-server-migration.service.ts• L21-107
Agent history source
Agent history stores threads, turns, messages, message parts, and evaluations. A workspace route selects the active storage location so chat and run services keep one API contract while history can move between core and workspace storage.
History writes keep a turn, message, parts, or pending answer together when they must stay consistent. Conversation access checks the active thread and viewer before it returns messages or live stream data.
References: packages/…/agent-history-repository.ts• L26-195 packages/…/agent-history-workspace-storage.service.ts• L11-41 packages/…/agent-chat-conversation-access.service.ts• L48-173
AI runtime
The AI runtime is a workspace-scoped client of the same metadata, role, tool, history, usage, and event systems. It adds model execution, chat streaming, delayed continuation, inbox work, file input, and application front components without bypassing caller permissions or workspace data boundaries.
Agent execution context
An agent run stores a caller reference that can be resolved after queue delay or suspension. Before execution or continuation, the runtime rebuilds the caller, agent, application, role, and run scope. A revoked caller or removed agent therefore cannot resume old work.
An agent can act through its application or as a workspace member. The runtime rebuilds the matching application or user authorization context and role IDs, then uses agent actor metadata for record changes. Agent creation and updates keep application ownership, role targets, names, overrides, and universal identifiers aligned.
The agent tool set is built from the effective persona permissions. Open-ended agents can discover a limited catalog. Scoped agents receive only the allowed tools. Usage is charged to the workspace, user, agent, and application scopes that apply to the run.
References: packages/…/agent-run-caller-context.service.ts• L31-79 packages/…/agent-actor-context.service.ts• L62-98 packages/…/agent-actor-context.service.ts• L100-220 packages/…/from-create-agent-input-to-flat-agent.util.ts• L24-107 packages/…/from-update-agent-input-to-flat-agent-to-update.util.ts• L129-230 packages/…/agent-run-turn.service.ts• L461-529 packages/…/agent-step-loop.service.ts• L151-220
Agent file delivery
Agent file delivery turns workspace file references into model input only when the file is readable and fits the selected model's limits. It checks signed URLs, MIME support, per-file size, total size, and file count. Unavailable, unsupported, oversized, or rejected files become clear placeholders instead of stopping the whole run.
The delivery path can load bytes when a model cannot use a signed URL. If a provider rejects a file, it retries with bytes and then removes rejected files from the prompt. Tool output can add a file as a new user message for the next model step. This keeps file access inside the workspace file service and makes provider limits visible to the run.
References: packages/…/agent-file-part.service.ts• L48-95 packages/…/agent-file-part.service.ts• L116-244 packages/…/agent-file-rejection.service.ts• L65-137 packages/…/agent-file-loader.service.ts• L16-65 packages/…/insert-model-input-file-messages.util.ts• L20-59
Agent continuation
An agent can pause on a wait or question. A pending wake-up stores the condition and run context. Resolution schedules one continuation, which claims the conversation, rebuilds the execution context, and resumes the run.
The runtime settles work when the caller disappears, a continuation cannot be recovered, credits end, or the run pauses too many times. Settlement is published through a short-lived Redis record and notification so the request that started the run can learn its final state.
References: packages/…/agent-runner.service.ts• L390-508 packages/…/agent-runner.service.ts• L1363-1468 packages/…/agent-run-settlement.service.ts• L26-97
Agent chat access
Agent chat treats a thread as a shared workspace record. Users and applications can read or write it only when AI settings, role access, row rules, record shares, channel grants, and participant state allow the action.
Chat channels add a role-based boundary before thread access. Channel changes rewrite grants. Channel deletion moves threads under a write lock before it removes the channel. Sharing a thread checks AI access and record read/write access for each participant, so a share cannot create a path to a hidden thread.
The chat path separates assistant participation from reply choice. It checks mentions, participants, pending questions, and conversation state before it starts a model run. Messages from another member can be masked from a viewer while the shared thread remains readable.
References: packages/…/agent-chat-conversation-access.service.ts• L86-173 packages/…/agent-chat-channel-access.service.ts• L25-111 packages/…/agent-chat-channel.service.ts• L107-204 packages/…/agent-chat-sharing.service.ts• L167-333 packages/…/agent-chat.service.ts• L292-367 packages/…/agent-chat-member-message-replay.service.ts• L32-113
Agent chat inbox
Inbox delivery gives a thread to its owner and listed participants. Thread keys and idempotency keys make retries and concurrent sends converge on one conversation and one message.
Channel and personal inbox actions update the right copy of a thread. Snooze work is queued with the saved state, and a later check ignores an old snooze that a newer action replaced.
References: packages/…/agent-inbox.service.ts• L67-215 packages/…/agent-inbox.service.ts• L217-356 packages/…/agent-chat-thread-triage.service.ts• L48-139
Agent action approval
Destructive or sensitive agent actions can pause for a user decision. A proposal records the intended tool, fixed target, proposed fields, and record snapshot. Approval may run only that proposal or an allowed alternative.
Before an approved record update runs, the runtime reads the proposed record fields again. A missing record or changed snapshot produces a failed or conflict result instead of applying an action against new data. If the proposal cannot be read, approval does not run it.
References: packages/…/propose-tool-call.pausing-tool.ts• L65-157 packages/…/propose-tool-call.pausing-tool.ts• L240-361
AI front components
AI front components let an authorized application or workspace user create a small UI component from chat, preview it with workspace data, and publish it for later use. The draft and published resource stay inside the workspace application boundary.
The builder requires the feature and application settings permission. Drafts expire and belong to the creating member. Source, imports, types, build output, selected fields, and sample records are checked before publication. Publication requires approval in the original chat and a matching preview checksum.
References: packages/…/ai-front-component.service.ts• L53-91 packages/…/ai-front-component.service.ts• L147-323 packages/…/ai-front-component.service.ts• L396-617
Change checklist
When these files or sections are changed, remember to consider these:
- Update the GraphQL schema cache dependencies and metadata GraphQL operation dependencies together when a new metadata source changes generated types or cached metadata.
- Keep field option updates aligned across option rows, resolved field metadata, stored defaults, and saved view filters.
- Keep migration side effects, optimistic flat maps, ordered actions, cache invalidation, and metadata events aligned when a metadata relation changes.
- Keep object create, update, and delete expansion aligned with migration operations for fields, indexes, views, options, navigation, and post-migration map refresh.
- Treat a new schema-affecting deferred operation as a change to migration locking, queue recovery, and retry behavior.
- Keep object batch validation aligned with the single-migration boundary and with the fields that cannot be changed together.
- Keep common query runner context fields aligned with workspace ORM context and with every transport that builds or consumes that context.
- Keep nested relation argument parsing, per-parent limits, relation ordering, and row-level permission application aligned when relation query shapes change.
- Keep direct GraphQL variable defaults, selected-field collection, resolver assertions, and result formatting aligned when direct execution changes.
- Keep composite field metadata aligned across filter, order, update, and result type shapes.
- Keep MCP tool mode behavior aligned across initialization instructions, tool listing, tool calls, generic record schemas, and role-bound tool catalogs.
- Keep generated MCP sign-in providers aligned with server URL, scope, application ownership, connected-account lookup, and migration cleanup.
- Keep AI file limits aligned with model modalities, signed URL support, byte downloads, provider fallback, and usage billing.
- Keep agent approval snapshots aligned with fixed record and account targets, editable fields, and the final tool input.
- Keep chat channel role grants, thread shares, participant checks, and channel move or delete locks aligned.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A cache consumer omits a metadata dependency | It can serve an old schema, tool set, or metadata response after a model change. | Dependency hashes and migration invalidation keys cover each derived map. |
| An object batch repeats an object or combines a single-object change with other objects | The service rejects the batch before migration instead of applying an unsafe partial model change. | Batch validation checks duplicate IDs and rejects non-batchable object properties. |
| A relation connect filter names a field missing from the target model | The write cannot resolve the target safely. | Data argument processing resolves the target object and validates known target fields. |
| A grouped query requests too many groups or nested records | Query cost and response size exceed the workspace limit. | Group limits, relation limits, and complexity checks run before execution. |
| A row rule cannot resolve a caller value | The caller receives no matching rows rather than unrestricted rows. | Permission filter construction uses a never-match branch. |
| A nested relation asks for an invalid argument or exceeds its per-parent bound | The query fails or returns more related data than the caller intended. | Nested relation input allows only known arguments and applies a bounded per-parent query. |
| Direct GraphQL receives the same field with conflicting arguments | The resolver could not safely choose one selection. | Selected-field collection rejects conflicting arguments before resolver execution. |
| An approved agent proposal cannot be read or its record snapshot changed | The action is not run, or returns a conflict that needs a new proposal. | Approval rereads the snapshot and fixes the target and editable fields. |
| A channel is deleted while its threads or grants are being changed | Threads can lose their access path or move to the wrong channel. | Channel deletion and grant rewrites use ordered locks and move threads before removal. |
| An MCP server has no usable connected account or its refresh token is unrecoverable | The server cannot run and the caller must sign in again. | Usable-account filtering and refresh handling mark failed accounts and return a sign-in error. |
| A deferred schema operation reaches its attempt limit | The workspace can retain an incomplete schema change. | Recovery marks it failed and operators can reset and enqueue it for retry. |
| A model rejects a workspace file or cannot read its URL | The file is omitted or shown as a placeholder. | File delivery retries with bytes when allowed, then removes rejected files. |
Key files
| File | Why to read it |
|---|---|
| packages/…/middleware.service.ts | Shows how a request becomes workspace-aware before API handlers run. |
| packages/…/common-base-query-runner.service.ts | Shows the shared operation boundary for limits, metadata, repositories, visibility, and hooks. |
| packages/…/process-nested-relations.helper.ts | Shows how bounded relation reads reuse metadata, permissions, and the root data source. |
| packages/…/data-arg-processor.service.ts | Shows how record input follows field metadata and relation rules. |
| packages/…/workspace-graphql-schema-sdl.service.ts | Shows how current workspace maps become a cached GraphQL schema. |
| packages/…/direct-execution.service.ts | Shows how direct GraphQL separates introspection from workspace execution and formats results. |
| packages/…/mcp-protocol.service.ts | Shows how caller scope becomes MCP instructions, tools, and JSON-RPC results. |
| packages/…/workspace-many-or-all-flat-entity-maps-cache.service.ts | Shows the shared source for workspace-derived metadata maps. |
| packages/…/workspace-migration-validate-build-and-run-service.ts | Shows the high-level metadata change path from validation to execution and events. |
| packages/…/deferred-workspace-operation-runner.service.ts | Shows how slow schema work is persisted, queued, retried, and completed. |
| packages/…/object-metadata.service.ts | Shows how object model changes expand into one workspace migration and refresh derived state. |
| packages/…/field-metadata.service.ts | Shows how field changes use flat maps and feed the migration boundary. |
| packages/…/view-query-params.service.ts | Shows how a visible view becomes an ordinary record filter and sort. |
| packages/…/mcp-server-sign-in.service.ts | Shows how workspace MCP servers acquire and replace sign-in providers. |
| packages/…/agent-actor-context.service.ts | Shows how agent work rebuilds application or member authority. |
| packages/…/propose-tool-call.pausing-tool.ts | Shows how user approval protects a proposed agent action from stale data. |
| packages/…/agent-chat-sharing.service.ts | Shows how chat threads combine AI permission, record sharing, and participant access. |
| packages/…/agent-file-part.service.ts | Shows how workspace files are checked and delivered to models. |