@b4run/sdk

Author-facing TypeScript declarations for B4.run agents, tools, middleware, memory, routes, and typed runtime contracts.

Use this when: You are authoring routes, tools, middleware, memory declarations, or typed runtime contracts.

Install

Requires Node.js 24 or later.

pnpm add @b4run/sdk

Add zod when declaring typed long-term memory:

pnpm add zod

Example

Define a minimal agent route:

// src/app/support/index.ts
import { agent } from "@b4run/sdk"

export default agent({
  model: "gpt-5-mini",
  systemPrompt: "Answer support questions clearly and concisely.",
})

The same package provides adjacent memory and middleware declarations:

// src/app/support/memory.ts
import { defineMemory } from "@b4run/sdk"
import { z } from "zod"

export default defineMemory({
  kind: "semantic",
  scope: ["workspace", "route"],
  schema: z.object({
    subject: z.string(),
    predicate: z.string(),
    value: z.string(),
  }),
})

// src/middleware.ts
import { defineMiddleware } from "@b4run/sdk"

export default defineMiddleware(() => ({ action: "continue" }))

Middleware that owns a long-lived resource, such as a database pool, uses the lifecycle form. setup runs once, lazily, before the first gated request (and is retried on the next request if it fails); dispose runs when the Node runtime shuts down.

// src/middleware.ts
import { allow, defineMiddleware, reject } from "@b4run/sdk"
import { Pool } from "pg"

let pool: Pool | undefined

export default defineMiddleware({
  async setup() {
    pool = new Pool({ connectionString: process.env.DATABASE_URL })
    await pool.query("select 1")
  },
  async dispose() {
    await pool?.end()
  },
  async handle(req) {
    const session = await pool?.query("select user_id from sessions where token = $1", [
      req.headers.authorization,
    ])
    return session?.rowCount ? allow({ userId: session.rows[0].user_id }) : reject(401)
  },
})

Runtime and stability

• @b4run/sdk is the supported, edge-safe application surface.
• @b4run/sdk/pure is a supported, dependency-free edge-safe integration surface.
• @b4run/sdk/testing is a supported Node-only scenario-authoring surface. It is separate from @b4run/testing.

Related

• @b4run/cli develops, tests, builds, and serves routes declared with the SDK.
• @b4run/testing provides programmatic harnesses for B4.run applications.
• SDK API reference
• Agents
• Tools
• Middleware
• Memory
• Scenario testing

Maturity and support

B4.run is pre-1.0, and its public surface can change. All publishable B4.run packages release together as a fixed group; review the @b4run/sdk changelog and upgrading guide before upgrading. For support, use GitHub Discussions; report defects in GitHub Issues.

License

MIT. See the repository license.