@b4run/core

Use this whenCopy link to section: Use this when

Route authors normally use @b4run/sdk, not Core. Use @b4run/core when you build a B4.run integration around configuration, capabilities, static type generation, or route metadata. Use /node for filesystem discovery and compiler-backed extraction. Do not build application code on /internal/compiler.

Install and importCopy link to section: Install and import

bash

npm install @b4run/core

import { config, renderB4Types } from "@b4run/core"
import { discoverRoutes } from "@b4run/core/node"

Compatibility and audienceCopy link to section: Compatibility and audience

Surface	Runtime	Purity	Audience	Stability
`@b4run/core`	edge-safe	not-claimed	integration	low-level
`@b4run/core/node`	node-only	not-claimed	integration	low-level
`@b4run/core/internal/compiler`	node-only	not-claimed	internal	internal

Importing /node registers the disk-backed b4.config.ts loader. The root stays free of that filesystem loader, so a static runtime can seed configuration instead.

Public exportsCopy link to section: Public exports

`@b4run/core`Copy link to section: @b4run/core

Export	Responsibility
`ThreadsStore`	Re-export the `@b4run/sqlite-storage` thread-store contract; its deep reference is deferred.
`createAgentsMdMarker`	Create the AGENTS.md capability marker.
`createMemoryMarker`	Create the typed-memory capability marker.
`createMemoryMdMarker`	Create the memory.md capability marker.
`MAX_MEMORY_BYTES`	Cap the size of a route `memory.md`.
`RuntimeTodo`	Describe one runtime plan item.
`createPlanningMarker`	Create the planning capability marker.
`MAX_PLAN_BYTES`	Cap the size of a route `plan.md`.
`createSkillsMarker`	Create the skills capability marker.
`createSubagentsMarker`	Create the subagents capability marker.
`createWorkspaceMarker`	Create the workspace capability marker.
`BuildTargetName`	Name the known `b4 build` targets as a union (`"node"
`BUILD_TARGET_NAMES`	List the known `b4 build` target names; the tuple `BuildTargetName` is derived from.
`isBuildTargetName`	Narrow an untyped string to a known `b4 build` target name.
`BUILT_IN_TOOL_NAMES`	List built-in capability tool names.
`ClientToolCallEnvelope`	Describe the interrupt envelope a parked client tool call leaves in the checkpoint.
`ClientToolDefinition`	Describe a client-provided tool definition after envelope validation.
`ClientToolResumeValue`	Describe the value the internal resume delivers to a parked client tool call.
`ClientToolStubOptions`	Options for `createClientToolStub`, such as a replay-only stub.
`ABANDONED_CLIENT_TOOL_RESULT`	The tool result recorded for a client tool call the client never answered.
`CLIENT_TOOL_CALL_TYPE`	The interrupt envelope `type` of a parked client tool call.
`CLIENT_TOOL_PREFIX`	The model-visible prefix of every client tool name (`client_`).
`CLIENT_TOOL_UNAVAILABLE_RESULT`	The tool result for a new call to a replay-only stub whose tool was not offered on this run.
`clientToolInterruptId`	Derive the stable interrupt id of a client tool call from its provider tool-call id.
`createClientToolStub`	Create the stub tool that gates, records and parks a client tool call.
`gateClientToolOp`	Gate a client tool call under the `clientTool` permission key.
`isClientToolCallEnvelope`	Narrow an interrupt value to a client tool call envelope.
`MissingClientToolRecorderError`	Thrown when a client tool call would park with no recorder to answer it.
`MemorySupersedeDetail`	Describe a gated memory supersede.
`SubagentGateRequest`	Describe a gated subagent operation.
`gateMemorySupersede`	Gate a memory supersede operation.
`gateSubagentOp`	Gate a subagent operation.
`gateToolOp`	Gate a tool operation.
`wrapToolWithApproval`	Wrap a tool with approval handling.
`wrapToolWithConstraint`	Wrap a tool with argument constraints.
`AppliedContribution`	Record an applied capability contribution.
`ApplyResult`	Return contributions and capability errors.
`CapabilityError`	Describe capability detection or load failure.
`CapabilityRegistry`	Hold capability markers.
`applyCapabilities`	Detect and load registered capabilities.
`createCapabilityRegistry`	Construct a capability registry.
`BrowseFilterLike`	Define a memory browse filter boundary.
`BrowsePageLike`	Define a memory browse page boundary.
`BrowseQueryLike`	Define a memory browse query boundary.
`BrowseSortEntryLike`	Define a memory sort entry boundary.
`BrowseSortFieldLike`	Name memory browse sort fields.
`CapabilityContribution`	Describe capability-provided runtime features.
`CapabilityMarker`	Define capability detection and loading.
`CapabilityMarkerContext`	Provide capability marker context.
`B4ToolDefinition`	Describe a contributed B4.run tool.
`Embedder`	Define the memory embedding seam.
`MarkerFs`	Define capability filesystem operations.
`StaticMarkerFiles`	Describe bundled marker file bodies.
`staticMarkerFs`	Serve bundled marker files without a filesystem.
`MemoryContext`	Provide memory tool context.
`MemoryKindLike`	Name memory kinds at the Core boundary.
`MemoryRecordLike`	Describe a memory record at the Core boundary.
`MemorySourceTypeLike`	Name memory source types.
`MemoryStatusLike`	Name memory statuses.
`MemoryStoreLike`	Define the runtime memory-store boundary.
`MemoryWritesMode`	Configure runtime memory writes.
`PromptFragment`	Describe capability prompt text.
`StreamTransformer`	Transform runtime stream chunks.
`StreamTransformerInput`	Describe a stream-transform input.
`StreamTransformerOutput`	Describe a stream-transform output.
`CreateWorkspaceFsOptions`	Configure workspace filesystem creation.
`createWorkspaceFs`	Create a workspace filesystem facade.
`B4ConfigLoader`	Define the configuration loader seam.
`B4AppError`	Describe an app-root or route-entry failure that carries a `B4_Exxxx` code.
`NamespaceListingCheckpointer`	A checkpointer that enumerates a thread's checkpoint namespaces; B4's savers implement it, `GET /threads/:id/turns` requires it.
`canListNamespaces`	Whether a checkpointer implements `listNamespaces`.
`UnresolvedToolInputTypeError`	Thrown by tool-schema extraction when a tool's declared input type resolves to `any`/`unknown` or depends on an import that does not resolve; the message names the tool file, the type, and the tsconfig used.
`UnresolvedToolInputTypeDetails`	The structured `details` on `UnresolvedToolInputTypeError`: tool name, file, type text, what it resolved to, unresolved imports, and the tsconfig path.
`UnresolvedImport`	One unresolved module specifier or member from the compiler, with its diagnostic text.
`__clearB4ConfigCacheForTests`	Clear the config memo in tests.
`loadB4Config`	Load or read a memoized app configuration.
`registerConfigLoader`	Register a runtime-specific config loader.
`seedB4Config`	Seed configuration for a static runtime.
`config`	Preserve types for a B4.run config object.
`isPrivateSegment`	Test whether a route segment is private.
`isRouteGroupSegment`	Test whether a route segment is a group.
`toRouteSegments`	Parse filesystem route segments.
`RuntimeEnv`	Describe seeded runtime environment values.
`__clearSeededRuntimeEnvForTests`	Clear seeded environment values in tests.
`readRuntimeEnv`	Read process or seeded environment values.
`seedRuntimeEnv`	Seed environment values for a static runtime.
`ResolveStateFieldsOptions`	Configure state-field resolution.
`resolveStateFields`	Normalize state defaults and reducers.
`GuardedSubagentResult`	Represent a gated subagent result.
`ResolveGuardedSubagentArgs`	Configure guarded subagent resolution.
`resolveGuardedSubagent`	Resolve a subagent under policy.
`ResolveSubagentRegistryArgs`	Configure subagent registry resolution.
`dispatchableSubagents`	List subagents eligible for dispatch.
`resolveSubagentRegistry`	Resolve local and conventional subagents.
`DescriptorRouteIndex`	Index route descriptors for subagents.
`ResolvedDelegationRule`	Represent a resolved delegation rule.
`ResolvedSubagent`	Represent one resolved subagent.
`ScopeInput`	Configure route tool scoping.
`ToolOrigin`	Identify where a tool came from.
`impliedToolDenials`	List tools a scope withholds through an implied deny.
`resolveToolScope`	Apply route tool policy.
`toolOrigin`	Read a tool's origin.
`renderB4Types`	Render the complete generated route module.
`renderRouteTypes`	Render route path and parameter types.
`renderScenarioTypes`	Render scenario map augmentation.
`SCENARIO_TYPES_FILE`	Name the generated scenario declaration file.
`RouteStateFields`	Describe generated state fields for one route.
`renderStateTypes`	Render route state types.
`renderToolTypes`	Render route tool types.
`CorsConfig`	Configure cross-origin access to the runtime.
`B4Config`	Configure a B4.run application.
`configureApprovalGrants`	Raise the process-wide approval-grant mode.
`approvalGrantMode`	Read the approval-grant mode in force in this process.
`mintGrantForPark`	Mint the grant for a park, or fail closed when one is required.
`MissingApprovalGrantMinterError`	Report a required grant that no minter could issue.
`__resetApprovalGrantsForTests`	Drop the approval-grant latch so a suite can exercise every mode.
`VercelBuildConfig`	Describe the `vercel` target's static assets, extra functions, and routes (`build.vercel`).
`VercelBuildRoute`	One Build Output route with a required `src`.
`DiscoveredB4App`	Describe a located B4.run application.
`DiscoverRoutesOptions`	Configure route discovery.
`ExtractedToolSchema`	Describe one extracted JSON tool schema.
`ExtractedToolType`	Describe one extracted tool type.
`FindB4AppOptions`	Configure application-root discovery.
`JsonSchemaProperty`	Describe a JSON Schema property.
`LoadB4ConfigOptions`	Select the application whose config is loaded.
`LoadedB4Config`	Return config, root, and config path.
`NormalizedRouteModule`	Describe a normalized route module.
`ResolvedStateField`	Describe a normalized state field.
`RouteDefinition`	Describe one discovered route.
`RouteKind`	Re-export the `@b4run/sdk` route-kind type.
`RouteManifest`	Describe all routes in an application.
`RouteSegment`	Describe a static or dynamic route segment.
`RouteToolSchemas`	Group extracted schemas by route.
`RouteToolTypes`	Group extracted tool types by route.
`StateFieldReducer`	Name a built-in state reducer.

`@b4run/core/node`Copy link to section: @b4run/core/node

Export	Responsibility
`loadB4ConfigUncached`	Load `b4.config.ts` directly from disk.
`registerNodeConfigLoader`	Register the disk-backed config loader.
`registerTsxLoader`	Register TypeScript module loading.
`discoverRoutes`	Discover filesystem routes.
`assertB4RoutesDir`	Validate the routes directory.
`findB4App`	Locate a B4.run application root.
`nodeMarkerFs`	Provide Node filesystem operations to capability markers.
`ExtractToolSchemasOptions`	Configure compiler-backed schema extraction. Optional `appRoot` (where the nearest `tsconfig.json` search starts; defaults to `routeDir`) and `tsconfig` (an explicit config to compile with).
`extractToolSchemasForRoute`	Extract tool schemas for a route. Throws `UnresolvedToolInputTypeError` when a declared input type resolves to `any`/`unknown`.
`ExtractToolTypesOptions`	Configure compiler-backed type extraction; accepts the same `appRoot` and `tsconfig` options.
`extractToolTypesForRoute`	Extract tool types for a route.

`@b4run/core/internal/compiler`Copy link to section: @b4run/core/internal/compiler

This subpath is internal and carries no compatibility promise. The CLI uses it during type generation.

Key contractsCopy link to section: Key contracts

`loadB4Config()`Copy link to section: loadB4Config()

Use this low-level seam when an integration owns configuration loading.

export declare function loadB4Config(options: LoadB4ConfigOptions): Promise<LoadedB4Config>

Behavior contract `core.load-config.failed-load-eviction`

loadB4Config memoizes per app root. A failed in-flight load is evicted only while that same promise remains cached, so a seed written during the load survives its later rejection.

`resolveStateFields()`Copy link to section: resolveStateFields()

Turns state defaults and optional reducer overrides into the normalized fields that type generation and runtime state assembly consume.

export declare function resolveStateFields(
  options: ResolveStateFieldsOptions,
): readonly ResolvedStateField[]

Behavior contract `core.state.reducer-resolution`

resolveStateFields infers append for array defaults and replace for scalar defaults, honors explicit reducer overrides, and sorts fields by name.

Configuration ownershipCopy link to section: Configuration ownership

See Configuration Reference for the full B4Config schema. The root loader is a runtime seam: Node callers import /node to register disk loading, and edge callers seed a constructed config.

import { config } from "@b4run/core"
 
export default config({
  appDir: "src/app",
  build: { targets: ["node"] },
})

Continue with Configuration Reference, Routes, State, and b4:routes.

@b4run/core

Use this when#Copy link to section: Use this when

Install and import#Copy link to section: Install and import

Compatibility and audience#Copy link to section: Compatibility and audience

Public exports#Copy link to section: Public exports

@b4run/core#Copy link to section: @b4run/core

@b4run/core/node#Copy link to section: @b4run/core/node

@b4run/core/internal/compiler#Copy link to section: @b4run/core/internal/compiler

Key contracts#Copy link to section: Key contracts

loadB4Config()#Copy link to section: loadB4Config()

Behavior contract core.load-config.failed-load-eviction

resolveStateFields()#Copy link to section: resolveStateFields()

Behavior contract core.state.reducer-resolution

Configuration ownership#Copy link to section: Configuration ownership

Examples and related guides#Copy link to section: Examples and related guides