Show HN: AGBoss Dependency injection and static validation for AI agents

AGBoss released version 0.1.0 of its open-source TypeScript framework, publishing @agboss/core@0.1.0 as the production runtime and @agboss/cli@0.1.0 as the CLI and static workflow compiler on registry.npmjs.org under the official agboss npm organization. The framework layers static verification on LangGraph for multi-agent workflows, with typed decorator components, constructor dependency injection, compile-time Path Scope verification via `agboss check`, declared action compensation with automatic LIFO rollback, pre-call FinOps budgets, boundary PII token masking, and signed Agent Mesh envelopes for A2A services. Running `npm exec --yes --package=@agboss/cli@0.1.0 -- agboss create my-app` scaffolds a project whose postinstall step runs `agboss check`, generates `.agboss/types.d.ts`, and unpacks 13 version-matched reference guides into `.claude/skills/agboss/` for AI coding agents.

AGBoss agboss.dev https://agboss.dev is an open-source TypeScript framework with static verification for complex multi-agent workflows on top of LangGraph https://www.langchain.com/langgraph . Agents, actions, routers, arbiters, tools, MCP servers, A2A services, and knowledge bases are strictly typed decorator components — assembled in an @Application container with constructor dependency injection, compile-time structural Path Scope verification agboss check , declared action compensation compensateWith / committedBy with explicit rollback side paths .onError / .onJoinError to an undo @Action and automatic LIFO compensation, two-phase human-in-the-loop pauses @ChannelRole , pre-call FinOps budgets @Budget , boundary PII token masking @PiiPolicy , multi-instance SQLite WAL leases and child work-stealing ChildPlacement.AnyInstance , signed Agent Mesh envelopes @A2AExpose , @A2AAgent , agboss hub , and a 5-loop evaluation & testing pipeline @EvalSuite , testWith + 10 unit runners . Current release v0.1.0 : @agboss/core@0.1.0 https://www.npmjs.com/package/@agboss/core production runtime and @agboss/cli@0.1.0 https://www.npmjs.com/package/@agboss/cli CLI & static workflow compiler are publicly published on registry.npmjs.org under the official agboss npm organization. Documentation: https://agboss.dev https://agboss.dev · Quick Start: https://agboss.dev/getting-started/quick-start/ https://agboss.dev/getting-started/quick-start/ · CLI Reference: https://agboss.dev/cli/ https://agboss.dev/cli/ · Examples: https://github.com/agbossjs/agboss-examples https://github.com/agbossjs/agboss-examples npm exec --yes --package=@agboss/cli@0.1.0 -- agboss create my-app cd my-app npm install npm exec --yes --package=@agboss/cli@0.1.0 -- agboss create my-app also available via npx --yes --package=@agboss/cli@0.1.0 agboss create my-app scaffolds a complete project where package.json already lists @agboss/core https://www.npmjs.com/package/@agboss/core in dependencies and @agboss/cli https://www.npmjs.com/package/@agboss/cli in devDependencies , alongside AGENTS.md and CLAUDE.md @AGENTS.md . Running npm install triggers "postinstall": "npm run types" , which runs agboss check , generates .agboss/types.d.ts for TypeScript, and unpacks 13 version-matched reference guides into .claude/skills/agboss/ SKILL.md + references/01..13 for your AI coding agent. cp .env.example .env && npm run chat every name is the full one, as in name 268 : the CLI never adds a suffix for you npx agboss g tool refund-tool --workflow my-app-workflow --agent my-app-assistant-agent one tool per OpenAPI 3 operation DTOs, a client in services/, tests , wired into the agent npx agboss g openapi pets --url ./pets.yaml --workflow my-app-workflow --agent my-app-assistant-agent npx agboss g workflow onboarding-workflow a second workflow, listed in the @Application any layout: targets come from the workflow module, tests go where vitest looks, files are prettier-formatted; a rerun refuses — --force regenerates the files and keeps the wiring in them tools, rag, MCP, judges, routes, … ; --force --reset starts them over without it npm install @agboss/core npm install -D @agboss/cli npx agboss check Why two packages? - @agboss/core dependencies — the lightweight production runtime decorators, execution graph, DI container, storage repository contracts, subpath entries @agboss/core/dto , @agboss/core/testing , @agboss/core/eval , @agboss/core/eslint , schemas, and bundled AI coding skills that ships into your Docker / Kubernetes image. - @agboss/cli devDependencies — the static graph compiler agboss check , code generator agboss generate , dev watcher agboss dev , LangGraph Studio bridge agboss studio , and local visual UI servers agboss eval ui , agboss hub ui that stay out of production container images. js // src/agents/scout.agent.ts — the prompt is a file next to the agent import { Agent } from "@agboss/core"; @Agent { name: "scout-agent", description: "Finds jobs", promptUrls: "./scout.prompt.md" , model: "moonshotai/kimi-k2.6", tools: GreenhouseJobs , } export class ScoutAgent {} // src/job-scout.workflow.ts — the paths, defaults and providers; money is the application's budgets import { Workflow, route, start } from "@agboss/core"; import { WorkflowStartTextDto } from "@agboss/core/dto"; @Workflow { name: "job-scout-workflow", version: "1.0.0", flow: start ChatWorkflowStart .returns WorkflowStartTextDto .toRouter MainRouter // picks one of its @Router { routes } .chooseOne route ProfilerAgent .toFinish ChatWorkflowFinish , route ScoutAgent .toFinish ChatWorkflowFinish , , , defaults: { models: { temperature: 0 }, router: { model: "typesafe/jev-1.13" }, tools: { maxToolCalls: 8 }, }, uncompactedTurns: 5, // the last 5 turns of the thread in full older ones: a @Compaction's summaries providers: JobFitJudge , } export class JobScout {} The application is the one entry 261 : it lists the workflows, the infrastructure a class that extends CostLedgerRepository , ExecutionRecordRepository , PausedExecutionRepository , LangGraph's BaseCheckpointSaver or one of the shared contracts of 265 — ExecutionLeaseRepository , ExecutionTreeRepository , RateLimitRepository ; none listed → the built-in in-memory ones, nothing written to the home folder; the SQLite ones below — each with a fast ping readiness calls, 300 , its model providers , every budget and its health checks healthChecks . createApp and testWith take it, never a workflow. Model providers are infrastructure too 266 : @ModelProvider classes listed in @Application { providers } — none listed → the built-in OpenRouterModelProvider chat and DecisionsModelProvider Jev and the other decision models ; one listed → the list is complete, the built-ins are not added next to it. A workflow and its components only name models; every model of the application agents, model routers, the default router, guardrails, compactions, judges resolves to exactly one listed provider by serves at assembly — none → model.unserved , two → model.ambiguous-provider one model through two providers = two model strings, each in one serves ; the built-ins yield a model another listed provider claims, 454 . agboss describe prints model: … → <provider for each, agboss check --models checks every model of every workflow of the application against its provider: A provider's policies are app-wide too: retryPolicy retries one call attempts, exponential backoff with jitter, Retry-After honoured — the only place backoff is set ; rateLimitPolicy RateLimitPolicy.of { maxConcurrentCalls, perMinute: { calls, tokens }, balancing } is one limit for the whole application — every execution, tenant, parallel branch and instance shares it through RateLimitRepository — a call without room waits its signal ends the wait, its timeout starts only with the room , waiting tenants share free slots by QueueBalancingStrategy TenantRoundRobin by default, TenantLeastInFlight , TenantWeighted by tenant.weight , Fifo , and a 429 pauses the provider's whole queue for Retry-After on every instance, then halves this instance's concurrency and grows it back by one a minute; circuitBreakerPolicy stops calling a provider that is down — its state in RateLimitRepository as well. Without rateLimitPolicy there is no limit: set it per your provider plan. A provider's name ends with -model-provider ; its key is a Secret field of the application's environment apiKey: "openRouterApiKey" : // src/model-providers/openrouter.model-provider.ts — job-scout's chat models, with its own request fields import { ModelCost, ModelProvider, OpenRouterProvider, OPENROUTER BASE URL, PromptCaching, QueueBalancingStrategy, RateLimitPolicy, Reasoning, RetryPolicy, TRANSIENT FAILURES, type OpenRouterFields, } from "@agboss/core/models"; import { minutes, seconds } from "@agboss/core/units"; @ModelProvider { name: "openrouter-model-provider", description: "OpenRouter — every chat model job-scout uses", serves: /. / , // its chat models; decision models go to DecisionsModelProvider no chat there baseUrl: OPENROUTER BASE URL, baseUrlField: "openRouterBaseUrl", // the environment may set another a proxy, a stub apiKey: "openRouterApiKey", // a Secret field of the application's environment timeout: minutes 2 , // per attempt, from the moment it has room cost: ModelCost.fromResponse , reasoning: Reasoning.modelDecides , promptCaching: PromptCaching.off , retryPolicy: RetryPolicy.exponential { maxAttempts: 3, initialDelay: seconds 1 , maxDelay: seconds 20 , jitter: true, retryOn: TRANSIENT FAILURES, } , rateLimitPolicy: RateLimitPolicy.of { maxConcurrentCalls: 8, // the plan's limits, for every instance at once perMinute: { calls: 120 }, balancing: QueueBalancingStrategy.TenantRoundRobin, } , circuitBreakerPolicy: { failureThreshold: 5, window: minutes 1 , openFor: seconds 30 }, } export class OpenRouterModelProvider extends OpenRouterProvider { override readonly requestFields: OpenRouterFields = { provider: { ignore: "Inceptron" } }; } // src/environments/app.environment.ts — the key both providers read; test leaves it out import type { Secret } from "@agboss/core"; export class AppEnvironment { openRouterApiKey?: Secret; // dev, prod: openRouterApiKey: secret "OPENROUTER API KEY" openRouterBaseUrl?: string; // env.optional "OPENROUTER BASE URL" : unset → the provider's baseUrl } // src/job-scout.application.ts — what createApp JobScoutApplication, { env } and testWith run import { Application, Budget, type BudgetHandler, BudgetPeriod, BudgetScope } from "@agboss/core"; import { DecisionsModelProvider } from "@agboss/core/models"; import { usd, type Usd } from "@agboss/core/units"; import { AppEnvironment } from "./environments/app.environment.js"; import { JobScout } from "./job-scout.workflow.js"; import { OpenRouterModelProvider } from "./model-providers/openrouter.model-provider.js"; // config/budget.config.ts in a project: the whole application, a tenant per day, every execution @Budget { name: "application-daily-budget", scope: BudgetScope.Application, period: BudgetPeriod.Day } export class ApplicationDailyBudget implements BudgetHandler { maxSpend : Usd { return usd 5 ; } } @Budget { name: "tenant-daily-budget", scope: BudgetScope.Tenant, period: BudgetPeriod.Day } export class TenantDailyBudget implements BudgetHandler { maxSpend : Usd { return usd 1 ; } } @Budget { name: "execution-budget", scope: BudgetScope.Execution } // the default of every workflow export class ExecutionBudget implements BudgetHandler { maxSpend : Usd { return usd 0.1 ; } } @Application { name: "job-scout-application", version: "1.0.0", environment: AppEnvironment, workflows: JobScout , // app.execute ChatWorkflowStart, … runs the workflow of that start providers: OpenRouterModelProvider, DecisionsModelProvider , // every model resolves to one budgets: ApplicationDailyBudget, TenantDailyBudget, ExecutionBudget , // checked before each step } export class JobScoutApplication {} Every storage contract has a ready SQLite implementation 265 , enabled only by listing it: SqliteExecutionRecordRepository , SqliteCostLedgerRepository , SqlitePausedExecutionRepository , SqliteCheckpointSaver , SqliteExecutionLeaseRepository , SqliteExecutionTreeRepository , SqliteRateLimitRepository . They share one file per application instance — sqlitePath of the environment contract, required only when one is listed else environment.missing-field names it ; WAL, busy timeout , every atomic operation in BEGIN IMMEDIATE , time from the framework's clock. With them --thread , agboss eval score / replay / golden see what earlier processes wrote, a pause survives a restart, and another instance on the file recovers a run whose process died; tests run on sqlitePath: ":memory:" . A project subclasses one through public tokens only extends + override , @Injectable { deps } as the class's own — SqliteExecutionRecordRepository takes SqliteConnection, Clock, ApplicationContext, IdGenerator , 313 and lists the subclass instead. One file serves one machine Wiki → Several-instances : // environments/app.environment.ts — the contract declares the file export class StoreEnvironment { sqlitePath : string; // required because SQLite implementations are listed } // environments/dev.environment.ts — a file of the project git-ignored , or AGBOSS SQLITE PATH export const environment: StoreEnvironment = { sqlitePath: env "AGBOSS SQLITE PATH", { default: ".agboss/job-scout.sqlite" } , }; // @Application { …, environment: StoreEnvironment, providers: durableStores } export const durableStores = SqliteExecutionRecordRepository, SqlitePausedExecutionRepository, SqliteCheckpointSaver, SqliteExecutionLeaseRepository, ; Time is the application's Clock 262, infrastructure like the stores : every time the framework reads the ledger's day, records, leases and every wait it makes lease renewals, recovery, the shutdown timeout, a tool's timeout , model call timeouts, retry backoff, Retry-After pauses goes through it — the system's clock unless @Application { providers } lists a class that extends Clock . A component that needs the time injects it; testWith runs every test on a VirtualClock @agboss/core/testing , moved by await clock.advance seconds 30 without real waiting. Direct time in the framework Date.now , new Date , setTimeout , … fails lint agboss/no-direct-time : // services/reminder.service.ts — the time comes from the application's Clock, never Date.now import { Clock, Injectable } from "@agboss/core"; import { seconds } from "@agboss/core/units"; @Injectable { deps: Clock } export class ReminderService { constructor private readonly clock: Clock {} async remindLater : Promise<Date { await this.clock.sleep seconds 30 ; // in a test: await clock.advance seconds 30 return this.clock.now ; } } Ids are the application's IdGenerator 313, infrastructure like the Clock : every thread id the framework mints app.execute without a threadId and every execution id — roots, children, recursion levels — comes from it; a caller's own threadId is used as given, a recovered execution keeps its id. The built-in RandomIdGenerator gives random UUIDs the formats before 313 unless @Application { providers } lists a class that extends IdGenerator ; it is created before the stores that inject it deps: IdGenerator , so it may not depend on the contexts. testWith makes them deterministic — thread-1 , thread-2 , …, execution-1 , … per test SequentialIdGenerator , @agboss/core/testing — unless the application lists its own. A pauseId never comes from it: it is an answer credential, a random 128-bit token. // config/prefixed-id.generator.ts — listed in @Application { providers: PrefixedIdGenerator } import { randomUUID } from "node:crypto"; import { IdGenerator, Injectable } from "@agboss/core"; @Injectable export class PrefixedIdGenerator extends IdGenerator { override newThreadId : string { return thr ${randomUUID } ; } override newExecutionId : string { return exe ${randomUUID } ; } } A rule needs no model: @Router { decidedBy: DecidedBy.Code, routes: { target: A }, { target: B } } on a class that implements RouterHandler<Self decides in route input , returning one of its targets Route<Self — no model call, cost 0, the same flow. Routes may carry the options of a parallel launch 273 : spawn stated on every route of a model router before a launch — SpawnPolicy.Always or SpawnPolicy.OnDemand ; OnDemand by default on a code router's and failure FailurePolicy.FailFast by default Wiki → Routers https://github.com/agbossjs/agboss/wiki/Routers . Several steps at once are a parallel launch 273 : .toParallelAgents ResearcherAgent, CriticAgent, CriticAgent, { maxConcurrency: 3 } or .toParallelActions … , always followed by .join and the values the branches give — .join .returns ResearchDto .returns listOf CritiqueDto , checked against the generated JoinOutputs ; one agent after .returns listOf CompanyDto runs once per item { maxItems } required; a longer list is truncated, never an error — result.launches says { items, taken } . At most maxConcurrency branches run at once, a new one starting as another ends; a failed branch cancels the others and the join takes .onJoinError E, … Wiki → Workflow https://github.com/agbossjs/agboss/wiki/Workflow . Not every answer is always needed: a quorum 279 counts them — .joinQuorum { min: 2, max: 3, deadline: seconds 30 } goes on with the counted answers, .joinQuorumGroups group LegalAgent, CriticAgent .priority 1 .returns … .toAgent … , … with the first complete group by priority , each group on its own path. @Arbiter classes decide which answers count, attached with .acceptedBy X before the quorum a chain is an AND, anyOf A, B stops at the first that accepts : by model, a criterion per agent; by code, one @OnAnswer Agent method per agent. A single answer a quorum may leave out is optional XDto in .returns … — the compiler and agboss check say so on the quorum. At run time the quorum is decided as answers arrive: once max answers are counted or a group has won, or the quorum can no longer be reached the other branches are cancelled; the deadline runs on the application's Clock ; not reached → QuorumNotReachedError into .onJoinError … ; a failing arbiter is ArbiterError . result.launches and onQuorumDecided show each answer as counted, rejected and by which arbiter , surplus or cancelled, and the winning group; agboss generate arbiter writes a code arbiter for a launch Wiki → Parallel https://github.com/agbossjs/agboss/wiki/Parallel . A whole workflow is a step too 263 : .toWorkflow CompanyCheckWorkflow runs an ordinary @Workflow of the application as a child — a component "start input → one of its finishes' outputs", runnable and testable on its own. Its start is chosen by the class of what comes in one start, else the one taking the chain's current value; graph.no-matching-start / graph.ambiguous-start otherwise , its scope starts with that input only, and its result is branched by class — .returns oneOf CompanyScoreDto, CompanyRejectedDto .switch caseOf … … , one case per finish output class. .toParallelWorkflows CompanyCheckWorkflow, { maxConcurrency: 3, maxItems: 50 } runs one child per item, joined as .join .returns listOf oneOf … ; a child reached from two places has its own path workflow W .onError … .returns oneOf … .switch … . At run time each child is an execution of its own — its id, steps and maxSteps , no history — inside its parent's checkpoint and budgets; an uncaught failure of its own fails the parent's step with ChildExecutionFailedError , and result.children holds the nested records Wiki → Workflow-as-a-step https://github.com/agbossjs/agboss/wiki/Workflow-as-a-step . A workflow may launch itself 264 : ThisWorkflow stands for the enclosing workflow in .toWorkflow ThisWorkflow , route ThisWorkflow or .toParallelWorkflows ThisWorkflow, { maxItems } — a topic too broad for one report researched subtopic by subtopic by the same workflow. A recursive workflow sets @Workflow { maxDepth: 3 } graph.recursion-without-depth ; the root is at depth 1 executionContext.depth , and each child record's depth , so the last level is depth === maxDepth . There the framework stops it, never the prompt: an agent's oneOf variant whose caseOf … launches ThisWorkflow leaves its response schema, a model router does not see such a route, a code router returning one fails with RouterDecisionError — so every such branch keeps a way out graph.recursion-without-exit ; a launch decided by code past maxDepth does not start and fails its step with ChildExecutionFailedError caused by DepthLimitExceededError .onError LimitExceededError, … takes it . Only direct recursion: a workflow launching one that launches it is graph.mutual-recursion . The root's execution budget counts every level; each level has its own maxSteps ; agboss describe prints recursive: ThisWorkflow, maxDepth 3, on the last level: researcher-agent → TopicReportDto only . Each recursive workflow is typed by its own entry: the .returns … after a ThisWorkflow launch is checked by @Workflow { name, flow } against the generated ThisWorkflowOutputs name , so one project holds recursive workflows with different finishes. The whole tree shares one concurrency cap 264 : @Workflow { maxConcurrentExecutions: 6 } of the root default 10 — how many executions of the tree, the root and all its descendants, work on a step at once. A step without a free slot waits in a queue — a throttle, never an error; an execution waiting at a join, for its child or paused holds no slot an execution's parallel branches share its one . The queue serves a parent whose children have all finished first, then the deepest execution, every 10 s of waiting counting as one level deeper the application's Clock . A launch's maxConcurrency and the cap both hold — the stricter wins; a child workflow's own smaller maxConcurrentExecutions limits its subtree a larger one is limits.child-concurrency-above-parent , a warning . Time in the queue does not count toward a quorum's deadline . The slots are in-process under the tree's lease: after a pause or a crash the next pass rebuilds the queue from the unfinished tasks, and a FailFast failure empties it. A slot is an execution, not model load — provider throughput is rateLimitPolicy Wiki → FinOps → Concurrency of a tree https://github.com/agbossjs/agboss/wiki/FinOps concurrency-of-a-tree-264 . The CLI works on the application whose path the project's package.json sets once — "agboss": { "application": "src/job-scout.application.ts" } or --application <path . npx agboss check writes .agboss/types.d.ts — what types the paths, each node's input and app.execute ; a generated project runs it on install npm run types . The whole shape — DTOs, a service, a tool, an agent, a router, the workflow, its application and its test — is the worked example in CLAUDE.md https://github.com/agbossjs/agboss/blob/main/CLAUDE.md → Architecture compiled and run by make check . npx agboss chat the application's one start; with several: --start <name npx agboss run --start chat-workflow-start "my resume src/data/sample-resume.md" npx agboss run --start <name --input '<json ' a start taking a DTO: checked field by field first npx agboss describe --json the application: workflows, starts, children, implementations — no API key npx agboss check --env prod types, assembly, the worst case per start, prod's process variables npx agboss dev watch mode: types regenerated, problems printed on change npx agboss studio LangGraph Studio on every workflow — no studio.ts, no langgraph.json npx agboss --help run, eval, replay, golden, compare, rag index agboss dev reruns agboss check in a short-lived process on every change of the application's src/ debounced : .agboss/types.d.ts stays current and assembly problems show as you type. agboss studio --env <name --port N builds every workflow of the application — the children too — writes the Studio config into the git-ignored .agboss/ studio.ts , langgraph.json and starts LangGraph's dev server on it; a child workflow is drawn inside its parent a subgraph, toParallelWorkflows included , and a problem — assembly, a missing variable — stops it before the server starts. A command that runs one workflow chat , run , eval , replay , golden add , compare takes it by its start's full name, --start chat-workflow-start — optional when the application has one start; with several and none given, or a name no start has, it stops with the list of starts and a Did you mean "…"? , running nothing. Needs OPENROUTER API KEY in .env dev's openRouterApiKey: secret "OPENROUTER API KEY" . Docs: Wiki → Components https://github.com/agbossjs/agboss/wiki/Components · Configuration https://github.com/agbossjs/agboss/wiki/Configuration · Knowledge bases https://github.com/agbossjs/agboss/wiki/Knowledge-bases · Profiles and comparisons https://github.com/agbossjs/agboss/wiki/Profiles-and-comparisons . agboss ships its own guide for coding agents 305 , written for the installed version: skills/agboss/ in the package — SKILL.md and 13 references, from composition and the flow DSL to tests, the error catalog and migrating a LangGraph graph 424 , every snippet compiled by the gate. agboss create writes three things for agents: - AGENTS.md Cursor, Codex, … — the project's instructions and a table routing each task to one reference; put the project's own rules under its Project rules ; - CLAUDE.md — one line, @AGENTS.md Claude Code reads CLAUDE.md ; - .claude/skills/agboss/ — the skills and their manifest .agboss-skills.json : the version and a sha256 per file , git-ignored. AGENTS.md and CLAUDE.md are written once and never rewritten. The skills folder is the framework's: npx agboss check so the project's postinstall , npx agboss dev and npx agboss generate … makes it match the agboss the project resolves — skills: .claude/skills/agboss updated 0.1.0 → 0.2.0 14 files after an upgrade, installed on a fresh clone, repaired with skills.local-edit when a file was edited by hand. A problem is a warning skills.sync-failed , skills.no-framework and never changes the exit code; --json carries result.skills . "agboss": { "skills": false } in package.json turns the sync off. More: Wiki → CLI https://github.com/agbossjs/agboss/wiki/CLI . Standalone Verified Showcase agbossjs/agboss-examples https://github.com/agbossjs/agboss-examples agbossjs/agboss-examples 7 self-contained, CI-verified applications proving AGBoss's compile-time and runtime guarantees npx agboss check + npm test on every project, with canonical 1 class = 1 file component folders and symmetric Spring-style tests/ mirroring src/ : 1. 01-hello-agboss https://github.com/agbossjs/agboss-examples/tree/main/01-hello-agboss — First-run starter, real async HTTP service DI PricingCatalogService with ExecutionContext.signal + step.idempotencyKey , production HTTP server src/http/server.ts with multi-tenant headers, 202 Accepted on pauses, and /health/live + /health/ready probes , and testWith + mockOf . 2. 02-path-scope-proof https://github.com/agbossjs/agboss-examples/tree/main/02-path-scope-proof — Side-by-side proof of 4 production graph bugs input.missing-on-path , input.outdated-on-path , launch.branch-outdates-sibling , flow.uncompensated-action that pass tsc --noEmit in raw LangGraph Annotation.Root langgraph-broken/ and are caught before runtime by agboss check agboss-broken/ vs agboss-fixed/ . 3. 03-support-refund-desk https://github.com/agbossjs/agboss-examples/tree/main/03-support-refund-desk — Support & refund desk proving reversible @PiiPolicy replaceWithToken , revealPii: true , PiiRefusedError , @ToolInterceptor replyToModel , block , @InputGuardrail DecidedBy.Code , @OutputGuardrail , in-memory BM25/TF-IDF @Rag InMemoryKnowledgeIndexService + RefundPolicyRetriever , PolicyAwareCompaction , and a 5-loop @EvalSuite with compact git-tracked eval/baseline/main-baseline.json and agboss eval calibrate Cohen's$\kappa$ . 4. 04-travel-booking-saga https://github.com/agbossjs/agboss-examples/tree/main/04-travel-booking-saga — Transactional multi-step saga compensateWith / committedBy across payment-saga , budget-saga , quorum-saga .toParallelAgents .acceptedBy .joinQuorum { min: 2, max: 2 } , and hitl-hold-saga Channel.withdraw , NotPausedError , SQLite WAL crash recovery, and HTTP 202 Accepted pause adapter . 5. 05-cluster-work-stealing https://github.com/agbossjs/agboss-examples/tree/main/05-cluster-work-stealing — Multi-instance horizontal scaling with ChildPlacement.AnyInstance , SqliteChildExecutionQueueRepository , recursive ThisWorkflow maxDepth: 2 , 30s SQLite leases & fencing ExecutionLeaseLostError , maxConcurrentSteps: 2 backpressure HealthComponentKind.StepSlots , @HealthCheck , and IncompatibleResumeError . 6. 06-enterprise-agent-mesh https://github.com/agbossjs/agboss-examples/tree/main/06-enterprise-agent-mesh — 3-service mesh apps/1-order-gateway , apps/2-billing-a2a , apps/3-catalog-mcp over @A2AAgent / @A2AExpose and @McpTool / @McpExpose , Ed25519 agboss-mesh JWS envelope, MeshLoopDetectedError & HopsLimitExceededError , MCP meta.callId deduplication via SqliteMeshRequestRepository , and agboss check --federation Blast Radius. 7. 07-langgraph-migration https://github.com/agbossjs/agboss-examples/tree/main/07-langgraph-migration — Side-by-side comparison of raw @langchain/langgraph before-langgraph/support.graph.ts with 15-field Annotation.Root God State, string-keyed addConditionalEdges , unbounded Send , dynamic prompt interpolation vs AGBoss after-agboss/src/ + after-agboss/tests/ with 10 narrow @Dto s, @Router , bounded .toParallelAgents , @Action , @Channel , and agboss check --strict . examples/job-scout https://github.com/agbossjs/agboss/blob/main/examples/job-scout — resume → proposed search brief → Greenhouse jobs ranked by Jev. It depends on agboss exactly like your project would: npm install && npm run build at the repo root cd examples/job-scout && npm run chat "my resume src/data/sample-resume.md" examples/flow-patterns https://github.com/agbossjs/agboss/blob/main/examples/flow-patterns — the flow's patterns with scripted tests only no model key : src/offer/ a review loop agent ReviewerAgent .returns oneOf … .switch … , caseOf ChangesRequestedDto, { about: OfferDraftDto } , .onError VisitsLimitExceededError, … , src/credit/ a code router DecidedBy.Code , route input through deps beside a model router, src/review/ parallel launches in waves a reviewer per section, then a critic beside two fact checker copies , src/topic/ a workflow that researches its subtopics itself ThisWorkflow , maxDepth , 264 . Point the CLI at it: cd examples/flow-patterns && npx agboss describe every workflow of its application More: Examples Showcase https://agboss.dev/examples/job-scout/ · Wiki → Example https://github.com/agbossjs/agboss/wiki/Example . Runtime package @agboss/core + dev/CI companion @agboss/cli ; the root @agboss/core is the authoring API, and subpath entries keep integrations focused: - @agboss/core — @Workflow , @Agent , @Router , @Arbiter , @Tool , @ToolInterceptor , @Injectable , @Action , @WorkflowStart / @WorkflowFinish , @Judge , @InputGuardrail / @OutputGuardrail , @PiiPolicy , @ChannelRole , @Compaction , InjectionToken , provide , env , secret , Secret , the context levels ApplicationContext , TenantContext , ExecutionContext , ContextValues , the path builder start , agent , router , action , route , caseOf , toAgent , toAction , toWorkflow , toParallelWorkflows , toFinish , ChildPlacement , … , WorkflowSettings , @Application , createApp , @Budget , the infrastructure contracts and SQLite / in-memory repositories Clock , IdGenerator , ChildExecutionQueueRepository , ExecutionHistoryRepository , MeshRequestRepository , … , Decision , observers, errors and types - @agboss/core/dto — field decorators @Text , @ListOf , … , the DTO wrappers listOf , oneOf , optional , variant and the standard DTOs - @agboss/core/units — usd , seconds , minutes , hours , kilobytes - @agboss/core/models — model providers @ModelProvider , OpenRouterModelProvider , DecisionsModelProvider , listed in @Application { providers } - @agboss/core/testing — testWith , the 10 unit runners testTool , testAction , testRouter , testArbiter , testRag , testJudge , testGuardrail , testToolInterceptor , testPii , testCompaction , the scripts replyWith , routeTo , when , waitFor , … , ToolFailure , mcpOf , VirtualClock , SequentialIdGenerator , VCR + @agboss/core/testing/setup : the matchers - @agboss/core/eval — @EvalSuite , EvalCascade , evalCase , turn , pastTurn , toolCall , toolInvariant , checkTrajectory , judgedBy - @agboss/core/mcp , /rag , /a2a , /memory — integrations @McpServer , @McpTool , @McpExpose , @Rag , @A2AAgent , @A2AExpose , a2aHttpListener , A2ACallerResolver , memory - @agboss/core/eslint — ESLint plugin agboss/no-component-state , agboss/no-direct-time Importing @agboss/core has no side effects: tracing, the MCP SDK and SQLite load only when an app uses them. The old entries @agboss/core/core , /graph , /router , /tool and /channels are deprecated re-exports for one minor release /concurrency went with the old flow DSL, 272 ; agboss migrate imports rewrites them and the renamed Router engine type → RouterEngine , root McpServer → McpExpose from @agboss/core/mcp , testing Duration → ClockDuration , TestClock → VirtualClock . Every entry's surface is in packages/agboss/api/ .api.md ; npm run api:update after an intended API change. packages/agboss/ the framework runtime published as @agboss/core packages/agboss-cli/ the CLI, static compiler & UI tools published as @agboss/cli examples/job-scout/ the example uses only the public API examples/flow-patterns/ the flow's patterns: a review loop, a code router, parallel launches scripted tests only make check — build, API reports, compiled docs, format, lint, types, tests with coverage for both packages. npm run dev — rebuild the framework on change. The framework never imports the examples, and the examples use only @agboss/core — both enforced by ESLint. One set per application, in environments/ next to the application file 261 . The contract is a plain class with declared fields only, declared once in the application: js import { AppEnvironment } from "./environments/app.environment.js"; @Application { name: "audit-application", version: "1.0.0", environment: AppEnvironment, // the contract: environments/app.environment.ts workflows: AuditWorkflow , budgets: AuditApplicationDailyBudget, AuditTenantDailyBudget, AuditExecutionBudget , } export class AuditApplication {} // environments/app.environment.ts — the contract: fields only, no values import type { Secret } from "@agboss/core"; export class AppEnvironment { auditUrl : string; databaseUrl : Secret; port : number; debug : boolean; } Each environment is a plain object typed by the contract, in <name .environment.ts — the file name is the environment's name --env prod → prod.environment.ts : python import { env, secret } from "@agboss/core"; import type { AppEnvironment } from "./app.environment.js"; export const environment: AppEnvironment = { auditUrl: env "AUDIT URL" , // a process variable, read when the app starts databaseUrl: secret "DATABASE URL" , // a Secret: only from a process variable, no default port: env.integer "PORT", { default: 8080 } , debug: env.flag "DEBUG", { default: false } , }; python import { secret } from "@agboss/core"; import type { AppEnvironment } from "./app.environment.js"; export const environment: AppEnvironment = { auditUrl: "http://localhost:4000", // a value in the file databaseUrl: secret "DATABASE URL" , // .env : e.g. pglite://memory — dev without Docker port: 8080, debug: true, }; - A field missing in an environment, a mistyped one or one the contract lacks does not compile; a literal in a Secret field does not compile either, and a Secret is not a string . A value in the contract auditUrl: string = "…" — the environments are object literals, it would be ignored fails assembly: environment.contract-value AppEnvironment.auditUrl has a value — the contract declares fields only; put the value in each environment . A framework implementation listed in providers whose field the contract lacks fails with environment.missing-field . - There are no wrappers: no declare module , no export default , no defineEnvironment / fromEnv . agboss check writes interface Environment extends AppEnvironment {} into .agboss/types.d.ts , so components read the values as applicationContext.environment deps: ApplicationContext , 261 — no separate token , typed by the contract — never process.env ; the chosen environment's name is applicationContext.environmentName : js import { ApplicationContext, Injectable } from "@agboss/core"; @Injectable { deps: ApplicationContext } export class AuditStoreService { constructor private readonly applicationContext: ApplicationContext {} connectionString : string { return this.applicationContext.environment.databaseUrl.reveal ; // the only way to the value } } - A Secret prints as everywhere it could be printed — logs, traces, JSON, agboss describe , error messages; only .reveal gives the value. Secrets are process variables and only that: in Cloud Run a Secret Manager secret is bound to the variable at deploy --set-secrets=DATABASE URL=database-url:3 ; the framework calls no cloud SDK. - agboss chat the application of package.json loads dev ; --env staging loads staging.environment.ts every command that loads the application takes --env . An unknown name fails at once exit 3 listing the available ones; a variable without a value or default fails the start naming it, the field and the environment, never the value: DATABASE URL is not set AppEnvironment.databaseUrl, prod . agboss check validates the selected environment without running anything, creating every component the start creates, so it fails exactly when the start would; agboss check --env prod lists the process variables it needs — names only, each value or secret , optional or has a default when unset is fine, never a value the list for --set-env-vars / --set-secrets at deploy, 268 ; agboss describe shows the environment with secrets masked. - From code: createApp Application, { env: "staging" } . Tests run on test : testWith Application loads test.environment.ts and fails without it a test never reaches dev's addresses by accident ; testWith Application, { env: "dev" } names another. - Dev / prod parity 12-factor : the same providers — the same implementations and code — in every environment; only values differ. - environment is required: an application with no settings declares the framework's empty contract, @Application { environment: EmptyEnvironment } any contract without fields works the same , and needs no environment file — its dev and test are {} . An untyped caller without one gets an empty environment. - Model provider keys are part of it 266 : each @ModelProvider names the Secret field that holds its key apiKey: "openRouterApiKey" ; the built-ins read openRouterApiKey , set with openRouterApiKey: secret "OPENROUTER API KEY" in each environment that calls models — a test environment may leave it out tests script or replay models . A missing key fails the start of an app that calls the provider; agboss check without --models reads the contract's shape and writes the types without one. A base URL is read the same way: baseUrlField: "openRouterBaseUrl" with openRouterBaseUrl: env.optional "OPENROUTER BASE URL" — no { default } : unset, it is undefined and the provider uses its decorator's baseUrl 266 S87 . - env.optional "X" env.integer.optional , env.flag.optional reads a variable that may be unset — undefined then, for an optional field of the contract x?: string ; a set value is still checked, and agboss check --env marks it optional 266 S90 . @Agent { judges: AnswerGroundedJudge , maxRetries: 1 } runs every judge on the agent's reply. A judge is a @Judge { name, model, reply, deps } class implementing JudgeHandler<TReply ; the container creates it with its deps , and its own model is called through the model gateway, so its spend is in the run's cost report judge:<name , category review . A judge sees the agent's answer as its DTO 262 S115 : reply names what it judges, in every shape an agent's output has — a DTO class, oneOf A, B the reply is A | B , listOf XDto a readonly XDto or PlainTextDto for a text agent { text } — and judge { variant, reply, task, attempt } gets the validated answer object, never a serialized string, and variant , the class it validated as 262 S125 : the class of the answer tool the agent used, never guessed from the answer's shape. For a oneOf A, B judge JudgeInput<A | B is a discriminated union on variant , and isVariant input, A narrows reply to A ; a single DTO, listOf XDto or PlainTextDto judge has variant as that one class; a listOf oneOf A, B judge reads reply: readonly VariantOf<A | B — each item { variant, value } , narrowed by isVariant item, A . An agent whose output its judge does not judge fails assembly with judge.wrong-reply : a text agent with a DTO judge, a DTO agent with another class, a oneOf variant the judge does not cover, a list agent with a judge of one value or the other way round. A verdict is built with JudgeVerdict.passed { metrics? } or JudgeVerdict.failed { reason, metrics? } — the only way; a failed verdict's reason goes back to the agent for its retry, and once maxRetries retries are spent the run throws QualityGateError code: "step.agent.quality-gate" , rejections: { judge, reason } . A judge without a model fails at app start judge.no-model . A judge's model comes through the constructor deps: JudgeModel : a chat model judgeModel.invoke ... or a decision model judgeModel.decide { state, questions } — every model of OpenRouter's Decisions API: typesafe/jev-1.13 , openai/gpt-6-luna-decisions , perplexity/pplx-decider-v1 .1 -27b , cloudflare/clef -flash|-omni , upstage/solar-decide , inception/mercury-decide DECISION MODELS ; DecisionsModelProvider serves them, JevModelProvider is its deprecated alias . Questions come from Decision.noul yes/no → noul = P yes , Decision.choice → choice , probabilities , confidence and Decision.score levels lowest first → score = the level's index ; the answers are typed by them. state is a text, a JSON object, or text and image parts Decision.image dataUrl — png/jpeg/webp data URLs; Luna, pplx-decider and Clef read images . At most 200 questions per call; an answer that does not fit its question fails with model.decision.invalid-response . decide on a chat model or invoke on a decision model throws ModelKindError model.wrong-kind . js import { Decision, Judge, JudgeModel, JudgeVerdict, type JudgeHandler, type JudgeInput, } from "@agboss/core"; @Judge { name: "answer-grounded-judge", model: "openai/gpt-6-luna-decisions", reply: JobReportDto, // what it judges: the agent's output, as its DTO deps: JudgeModel, JOB SEARCH , } export class AnswerGroundedJudge implements JudgeHandler<JobReportDto { constructor private readonly judgeModel: JudgeModel, private readonly jobSearch: JobSearch, {} async judge { reply, task }: JudgeInput<JobReportDto : Promise<JudgeVerdict { const first = reply.jobs; if first === undefined || await this.jobSearch.exists first.url { return JudgeVerdict.failed { reason: "the first job does not exist" } ; } const a = await this.judgeModel.decide { state: { task, jobs: reply.jobs.map job = job.title , results: this.jobSearch.lastResults }, questions: { grounded: Decision.noul "Every job of the report appears in the results" , tone: Decision.choice "Tone of the report", { neutral: "Plain, factual", pushy: "Sells or pressures", } , quality: Decision.score "Overall usefulness", "useless", "partial", "complete" , }, } ; // a.grounded.noul: number; a.tone.choice: "neutral" | "pushy"; a.quality.score: number return a.grounded.noul 0.7 && a.tone.choice === "neutral" ? JudgeVerdict.passed { metrics: { quality: a.quality.score } } : JudgeVerdict.failed { reason: "Only report jobs from the search results, neutrally." } ; } } In tests, script a chat judge like an agent — mockLlm Judge .thenReturn replyWith "PASS" — and a decision judge with its answers by question id an option, P yes , a level's index or text : mockLlm AnswerGroundedJudge .thenReturn decideWith { grounded: 0.9, tone: "neutral", quality: 2 }, { cost: usd 0.0002 } ; on its own, testJudge AnswerGroundedJudge, … { variant, reply, task, attempt } takes reply as a plain object of its DTO, typed by the judge — another shape, or a variant with another class's value, does not compile. js import { Judge, JudgeVerdict, type JudgeHandler, type JudgeInput } from "@agboss/core"; import { isVariant, oneOf } from "@agboss/core/dto"; @Judge { name: "fair-decision-judge", model: "typesafe/jev-1.13", reply: oneOf OfferDto, RefusalDto } export class FairDecisionJudge implements JudgeHandler<OfferDto | RefusalDto { judge input: JudgeInput<OfferDto | RefusalDto : Promise<JudgeVerdict { if isVariant input, OfferDto { // input.variant is OfferDto, the class of the answer tool; input.reply is an OfferDto return Promise.resolve input.reply.salary 0 ? JudgeVerdict.passed : JudgeVerdict.failed { reason: "an offer pays something" } , ; } // input.reply is a RefusalDto return Promise.resolve input.reply.why.trim === "" ? JudgeVerdict.failed { reason: "a refusal says why" } : JudgeVerdict.passed , ; } } Routers and guardrails work on any decision model too @Router { model: "openai/gpt-6-luna-decisions" } : one choice question over the routes, options sorted so declaration order never changes the request. testWith Application @agboss/core/testing runs the whole application in each test — its real container and infrastructure, models by script, MCP servers stubbed, the network blocked, a VirtualClock and deterministic ids thread-1 , execution-1 , … per test, 313; an application that lists its own IdGenerator keeps it . Scripts are typed by the generated .agboss/types.d.ts agboss check , 262 : replyWith XDto, fields must be a class of the agent's output a class outside its oneOf does not compile , routeTo … a target of the router's routes — exactly one after .chooseOne … , the OnDemand targets it launches before .toParallelAgents … routeTo only with an Always route . when … binds turns to the node's input values, at any depth: a deep partial of each field's value the producer is not compared , undefined for an absent field, a listOf field by length and position, a oneOf element as variant XDto, { … } ; a call no script matches fails the test, naming its input. A script is an expectation: a thenReturn turn no call took, or a when … nothing matched, fails a test whose body passed thenReturnAlways never does . waitFor seconds 31 before a turn makes the call take that long on the test's clock. A model reply interpreter 267 is scripted the same way, its input the pause's { ask, reply } — mockLlm RefundReplyInterpreter .when { reply: "ok, but only half" } .thenReturn replyWith ToolCallApprovalDecisionDto, { approved: true, … } , one on a decision model with decideWith { approved: 0.9 } 267 S124 ; a code one is created by the container and replaced with mockOf Interpreter .interpret mockReturnValue ReplyInterpretation.understood { approved: true } . js import { expect } from "vitest"; import { replyWith, testWith, ToolFailure, waitFor } from "@agboss/core/testing"; import { seconds, usd } from "@agboss/core/units"; const test = testWith OfferApplication ; test "the reviewer asks for changes once, then approves", async { app, mockLlm, mockAction } = { mockLlm ReviewerAgent .when { draft: { text: "v1" } } .thenReturn replyWith ChangesRequestedDto, { notes: "shorter" } ; mockLlm ReviewerAgent .when { draft: { text: "v2" } } .thenReturn waitFor seconds 1 , replyWith DraftApprovedDto, {}, { cost: usd 0.01 } ; mockLlm EditorAgent .thenReturn replyWith "v2" ; await app.execute OfferWorkflowStart, shortlist ; expect mockLlm ReviewerAgent .toHaveBeenCalledTimes 2 ; expect mockLlm ReviewerAgent .toHaveReturned ChangesRequestedDto, { notes: "shorter" } ; expect mockAction SendOfferAction .toHaveBeenCalledWith { draft: { text: "v2" } } ; } ; test "a cancel from inside a mock cancels the execution", async { app, mockOf, mockTool } = { mockTool SearchJobsTool .thenFail ToolFailure.Timeout ; // the next call fails as a timeout would mockOf MailerService .send.mockImplementation = app.cancel "thread-1" .then = undefined ; await expect app.execute OfferWorkflowStart, shortlist .rejects.toFailWith ExecutionCancelledError, ; } ; Calls are checked with Vitest's names on mockLlm X and mockAction A the action still runs : .inputs , toHaveBeenCalledWith … the matcher of when , toHaveBeenCalledTimes n model calls; an action's executions , toHaveReturned XDto, fields? ; on anything else — a vi.fn , a mockOf … method — they are Vitest's own. toHaveBeenAskedWith checks the prompt itself. Errors are caused the real way — failWith ModelFailure.… , a rejecting mockOf … , mockTool Tool .thenFail ToolFailure.Timeout , scripts that reach a limit, app.cancel — and matched with rejects.toFailWith ErrorClass, { …fields, cause: CauseClass } through the cause chain; the testing API has no way to create a framework error. Parallel branches run one at a time in a test, in listed / item order TestConcurrency.Sequential , the default ; TestConcurrency.Real runs them as production does, and TestConcurrency.inOrder step A , step B makes them complete in that order — a race, a FailFast or a quorum gives the same result on every run. One component is tested on its own with a unit runner: testTool , testAction , testRouter , testArbiter , testRag , testJudge , testGuardrail , testPii — its own container overrides replace classes by classes , the environment , the frame of its step executionContext.signal with a timeout , SpendRecorder , its model by script; each call gives { output, spend } . js import { expect, it } from "vitest"; import { decideWith, override, step, TestConcurrency, testJudge, testTool, testWith, } from "@agboss/core/testing"; import { seconds } from "@agboss/core/units"; // the risks agent answers first, then the skills agent: the quorum counts them in that order const test = testWith QuickPanelApplication, { concurrency: TestConcurrency.inOrder step RisksAgent , step SkillsAgent , } ; test "the first two answers are counted", async { app } = { const result = await app.execute PanelWorkflowStart, candidate ; expect result.launches 0 ?.isQuorumReached .toBe true ; } ; it "searches the board it is given", async = { const runSearch = testTool SearchJobsTool, { overrides: override JobBoardService, FakeJobBoardService , } ; const { output, spend } = await runSearch { query: "TS" }, { timeout: seconds 1 } ; expect output.jobs .toContain "TS" ; expect spend.totalUsd .toBe 0 ; } ; it "a grounded reply passes", async = { const runJudge = testJudge GroundedJudge, { model: decideWith { grounded: 0.9 } } ; const reply = { text: "Acme hires TS engineers acme.example " }; // a PlainTextDto, as an object const { output } = await runJudge { variant: PlainTextDto, reply, task: "Find TS jobs", attempt: 0 } ; expect output.passed .toBe true ; } ; Every component reads the execution it runs in through its constructor 280 : deps: ExecutionContext , a parameter named executionContext — tools, actions, judges and services alike; there is no ctx parameter. It is data only and read-only, and every read gives the current execution and step one frame per node visit and per tool call , so it is safe in an component one instance for the app and in parallel branches. One execution has one id: its observer events event.executionId , executionContext.executionId , its record, its trace and its result ExecutionOutput.executionId carry the same one, also after a resume. What a node reads comes in its input — for a model, its input message each input field as field from producer , never through {{input.…}} in its instructions prompt.input-in-instructions ; the context carries no input and no metadata. run query: OrderQuery : Promise<OrderQuery { const { executionContext } = this; executionContext.executionId; // unique per execution, the same after a resume = ExecutionOutput.executionId executionContext.threadId; // the conversation ExecutionOutput.threadId executionContext.ownerId; // from execute …, { ownerId } : who the thread belongs to executionContext.tenant.tenantId; // the organization, "default" when none is passed executionContext.tenant.application.environmentName; // the application level, through the tenant executionContext.signal; // aborted by app.cancel threadId or the caller's signal executionContext.workflow; // { type, name, version, startedVersion, configHash } executionContext.step.idempotencyKey; // ${executionId}:${nodeId}:${visitNumber} :${itemIndex} :${callId} executionContext.step.callId; // the tool call's id undefined outside a tool call return Promise.resolve query ; } Read outside an execution in a constructor at start or after its step ended a forgotten promise , the context throws ExecutionContextUnavailableError context.unavailable — never undefined . await app.execute ChatWorkflowStart, { text: "Find me a backend job" }, { threadId, ownerId: userId, signal, tenant: { tenantId: "acme" } }, ; const { cancelled } = await app.cancel threadId, { tenantId: "acme", ownerId: userId } ; A thread created with an ownerId belongs to it: execute on that thread, resume and cancel with another owner or none throw ThreadOwnerError run.thread-owner before anything runs or is read. A thread belongs to its tenant too 261 : its key is tenantId + threadId , so another tenant's thread does not exist for the caller. execute with a threadId the tenant does not have yet creates that thread — the caller's own, idempotent id an order number, a ticket , bound to its ownerId ; the same id in another tenant is another thread 262 Q4 . An id that cannot be one empty, over 200 characters, a control character is InvalidThreadIdError run.invalid-thread-id ; cancel of a thread the tenant does not have is UnknownThreadError . resume and cancel take the tenant by its id omitted → "default" , and a resumed execution runs on the context values it started with. With nothing declared tenant: { tenantId?, weight? } is all there is weight , a positive integer, default 1, is the tenant's share for 266's TenantWeighted ; an application that declares @Application { tenantContext: ShopTenantContext, executionContext: ShopExecutionContext } — its own subclasses with DTO field decorators, identity only, never secrets — gets their values typed per start tenant: ContextValues<ShopTenantContext , execution: … , checked before the first step invalid → dto.invalid , an onExecutionRejected , the field named, never the value and frozen. Tool arguments a channel shows and ExecutionOutput.pending i .ask.arguments have the input DTO's sensitive fields through their action replacePart as written, a token or a kind as <field , 120 ; the tool itself still gets them whole. Pauses 267 . An execution may wait for several answers at once — one per tool call whose channel replied ChannelOutcome.awaitReply , in parallel branches too: a paused branch does not stop its siblings, the execution pauses only when nothing else can move, and result.pending lists every waiting pause PendingPause : answeredBy , agent , channel , itemIndex , childExecutionId , the question ask . A pause is answered by its id, never by its thread — app.resume { pauseId, decision }, options — found by tenantId, pauseId anywhere in the tree unknown, or another tenant's → UnknownPauseError , pause.unknown ; with other pauses left the execution pauses again with the rest; the result carries threadId and executionId . Who may answer is the pause's channel role's answeredBy : a PauseAnswerer.ThreadOwner pause lists its pauseId in result.pending and is resumed with the thread's ownerId another → ThreadOwnerError ; a PauseAnswerer.Channel pause's id is the right to answer it — only its channel got it ask.pauseId , result.pending leaves it out — and it is resumed with { answeredBy: "manager-17" } , recorded on the pause and in onExecutionResume ; the other credential or an empty answeredBy is PauseAnswererError pause.wrong-answerer . The decision is validated before it is recorded — a ToolCallApprovalDecisionDto approved , reason? , overrideArguments? only with approved: true , checked by the tool's input , else DtoValidationError and the pause keeps waiting: // a webhook: the finance manager pressed "Approve" on the message whose reply key is the pauseId const result = await app.resume { pauseId: replyKey, decision: { approved: true } }, { tenantId: "acme", answeredBy: "manager-17" }, ; Free-text replies 267 PR 3 . A webhook that only has the person's words passes them as they are — app.resume { pauseId, reply }, options , exactly one of decision or a non-empty reply — and the pause's role reads them with its @ReplyInterpreter replyInterpreter on the @ChannelRole , one interpreter per role: channel.shared-interpreter . The interpreter gets the pause's original question and the reply { ask, reply } ; what it gives is validated like a decision. DecidedBy.Model — a chat model answers through one answer tool, its static prompt / promptUrls its instructions, the question and the reply in the input message. For an approval role approves the model may be a decision model Jev, 267 S124 : it reads approve / refuse only — one Decision.noul "approved" , approved when P yes 0.5, the answer { approved } with no reason and no overrideArguments ; a question role, whose answer needs more than a yes / no, cannot name one reply-interpreter.decision-model . Either model's call goes through the provider resolved by serves , is checked against the tree's budgets first, counted in their ledger at once and in the execution's spend when the step takes the answer, and traced reply-interpreter:<name . DecidedBy.Code — the class's interpret input: InputOf<Self implements ReplyInterpreterHandler<Self , deps like any component , created by the container, returns its outcome 267 S124 : ReplyInterpretation.understood decision — validated like any decision — or ReplyInterpretation.notUnderstood { reason } for a reply it cannot read a plain object does not compile ; a throw is for an unexpected crash only. Either kind reads in the pause's execution frame — its ExecutionContext has the tenant, the owner and the waiting step, and the rate limits see the tenant. A model interpreter reads the question and the reply through the application's and the workflow's PII policies, like an agent: its answer is revealed before it is validated, a token no map knows is a decline, a block rule throws PiiRefusedError . A reply nobody can read — not understood, a model that gives no answer, an answer the role rejects, a crash — throws UninterpretableReplyError pause.uninterpretable-reply ; reason says why, cause is the error behind it, if any and the pause stays pending, so the webhook can ask again or answer with a decision ; a reply for a role without an interpreter is ReplyInterpreterMissingError pause.no-reply-interpreter , the pause untouched. @ReplyInterpreter { name: "refund-reply-interpreter", description: "Turns a manager's free-text reply into a refund decision", decidedBy: DecidedBy.Model, model: "moonshotai/kimi-k2.6", prompt: "The manager answered a refund approval in free text. Decide approve / reject.", } export class RefundReplyInterpreter {} @ChannelRole { name: "refund-approval-channel", description: "Approves card refunds", approves: RefundCardInputDto, answeredBy: PauseAnswerer.Channel, replyInterpreter: RefundReplyInterpreter, } export abstract class RefundApprovalChannel extends ChannelOf<RefundApprovalChannel {} // a webhook passes the text as it came await app.resume { pauseId: replyKey, reply: "ok, refund it" }, { answeredBy: "manager-17" } ; // approve / refuse on a decision model: one Decision.noul "approved" — no reason, no overrideArguments @ReplyInterpreter { name: "deposit-reply-interpreter", description: "Reads whether a clerk's reply approves a deposit return", decidedBy: DecidedBy.Model, model: "typesafe/jev-1.13", prompt: "The clerk answered a deposit return.", } export class DepositReplyInterpreter {} @ChannelRole { name: "deposit-approval-channel", description: "A clerk approves deposit returns", approves: DepositReturnDto, // an approval role: a decision model may read its replies answeredBy: PauseAnswerer.Channel, replyInterpreter: DepositReplyInterpreter, } export abstract class DepositApprovalChannel extends ChannelOf<DepositApprovalChannel {} A code interpreter returns its outcome: ReplyInterpretation.understood { approved: true } for a button value it knows, ReplyInterpretation.notUnderstood { reason: "not a button value" } for anything else Wiki → Pauses has the whole class . Who answered each pause 267 S107 . app.resume …, { record: true } or execute returns result.record.pauses : every resolved pause of the tree in the order asked — PauseAnswerRecord { pauseId undefined for a PauseAnswerer.Channel pause , executionId the execution it waited in: the root's or a child's , step, role, answeredBy, responder, resolution, askedAt, resolvedAt, decision } , PauseResolution.Decided ChannelOutcome.decided , no pause , Replied awaitReply + app.resume , Withdrawn a FailFast sibling failed or Cancelled app.cancel , or the tree ended ; the decision masked by the PII policies like the rest of the record, none when withdrawn or cancelled. Each child's record — result.children and result.record.children — lists the pauses its own steps asked as ChildExecutionRecord.pauses 267 S124 , a grandchild's in its own record; the root's record.pauses keeps the whole tree's. It is written when the pause is resolved into the execution records — ExecutionRecordRepository.savePauseAnswer , read back with findPauseAnswersByTenantIdAndRootExecutionId — the permanent history, so the retention below never changes it; the pause records are operational state. A resolved pause record Taken , Cancelled is kept @Application { pauseRecordRetention } — default hours 24 — after it was resolved, then removed by the recovery sweep PausedExecutionRepository.deleteResolvedBefore cutoff , on the Clock : within it a late answer is NotPausedError , after it UnknownPauseError ; a pending pause is never removed. Before its first step an execution reads each of its budgets README → FinOps : one exhausted — the tenant's day spent, say — refuses it with BudgetExceededError limit.budget , an onExecutionRejected , before anything is written: no thread a new one is created once the budgets pass , no record, no model call. execute and resume forward signal , onStream token and tool-call events and configurable extra LangGraph keys; the framework's own win . There is no untyped metadata or executionContext option 261 : what an execution carries is its typed context values — a channel, a guardrail or any component reads them through its injected ExecutionContext this.executionContext.tenant.tenantId , the project's own fields , and an MCP session createMcpService app, Mcp .connect transport, { tenant, execution, ownerId } or an A2A call a2aHttpListener app, { expose, callerResolver } , whose resolver returns them per request, 387; adapter.execute Start, request, onEvent, { tenant, execution, ownerId } passes them from its authenticated caller. app.cancel threadId aborts a running run — it stops before its next model or tool call and execute rejects with ExecutionCancelledError — or drops a paused one, whose pauses are withdrawn: their resume then throws NotPausedError ; cancelled is false when the thread had neither a thread the tenant does not have is UnknownThreadError . From app.close on, execute and resume are refused with ApplicationStoppingError app.stopping , an onExecutionRejected ; running executions go on and cancel still works. An execution tree is moved by one holder at a time 265, Q58 : execute and resume hold its lease seconds 30 , renewed every 10 s and before every checkpoint write, released when the pass ends . A resume first records its decision on its pause Pending → Resolved , atomic — of two resumes of one pause the second gets NotPausedError , as does an answer to a pause its step already took Taken or one withdrawn Cancelled : the thread was cancelled, or a sibling branch failed under FailFast — then waits while another call or instance holds the lease; the holder continues with every recorded answer of the tree in one pass and, before the tree rests, takes the answers recorded meanwhile, so the waiting call returns the tree's current output with its decision taken. An instance that lost the lease frozen past it stops and its call rejects with ExecutionLeaseLostError execution.lease-lost — no onExecutionError , no failed record: the new holder continues Wiki → Several-instances . An execution's record is ExecutionRecordStatus.Running while its tree moves. Recovery 265 : every instance looks for running roots at its start and every 30 s, takes the lease of each whose holder died its lease expired or stopped released it , and continues it from its last checkpoint — a decision recorded meanwhile first — so only the interrupted step runs again; a root started under another config is left to a compatible instance logged once , unless onIncompatibleResume says "resume" . Observers get onExecutionResume with reason: ResumeReason.Recovered ResumeReason.Answered for app.resume . With the in-memory defaults nothing survives a restart, so recovery needs persistent stores — the SQLite ones on one machine. app.close stops the sweep, runs onStop , waits for the running executions up to the shutdown timeout — @Application { shutdownTimeout } , app.close { timeout } , default seconds 25 — then interrupts them: each call rejects with ApplicationStoppingError , without onExecutionError , releases its lease at once and stays running , so another instance continues it without waiting for the lease to expire. createApp calls app.close on SIGTERM / SIGINT a second signal interrupts at once until the close finishes; testWith never listens. // one instance of a rolling deploy stops: what still runs after 10 s moves to another instance await app.close { timeout: seconds 10 } ; Health checks 300 : app.checkLiveness and app.checkReadiness are the instance's probes for an orchestrator Kubernetes, Cloud Run — the project's own server exposes them, the framework opens no endpoint. Liveness does no I/O: the instance Unhealthy , stopping , from app.close on and its recovery loop Unhealthy when its last sweep ended more than three sweep intervals ago on the Clock . Readiness adds every store's ping each 265 contract has one — a project's own implementation adds it; the SQLite ones run SELECT 1 , every model provider's circuit breaker as RateLimitRepository keeps it open → Degraded ; never a model call and the project's @HealthCheck s, listed in @Application { healthChecks } — all at once, each under its timeout stores and providers seconds 2 . A check that throws or passes its timeout is that component's Unhealthy with its reason ; neither call ever rejects. The report's status is its worst component's HealthStatus.Healthy | Degraded | Unhealthy , each component has its name , kind HealthComponentKind , status , reason and duration Wiki → Health-checks https://github.com/agbossjs/agboss/wiki/Health-checks . @HealthCheck { name: "crm-health-check", timeout: seconds 2 , deps: CrmClient } export class CrmHealthCheck implements HealthCheckHandler { constructor private readonly crmClient: CrmClient {} async check : Promise<HealthCheckResult { const isReachable: boolean = await this.crmClient.ping ; return isReachable ? HealthCheckResult.healthy : HealthCheckResult.unhealthy { reason: "CRM is unreachable" } ; } } // listed in the application: healthChecks: CrmHealthCheck const liveness: HealthReport = await app.checkLiveness ; // GET /livez → 503 unless Healthy const readiness: HealthReport = await app.checkReadiness ; // GET /readyz → 503 when Unhealthy In unit tests, testExecutionContext { … } from @agboss/core/testing is a frozen ExecutionContext : new PayOrder testExecutionContext ; its tenant and tenant.application are set with { tenantContext, tenant, application: { environment } } . Observers are registered only in @Application { observers: ... } 261 — one instance each, created by the container at start with their deps , called for every execution of the application filter by event.workflow.name === nameOf SupportWorkflow — nameOf C gives the name of any AGBoss-decorated class ; none listed → none is called. Each hook gets one event object, plain data, never the framework's internal state. Every execution event ExecutionEvent carries executionId , parentExecutionId , rootExecutionId , threadId , tenantId and workflow — a WorkflowRecord { name, version, startedVersion, configHash } , no class; a node event agent, router, tool, model, knowledge base, guardrail, action, channel, judge, onValuesOutdated , onLaunchItemsTruncated adds step , a StepRecord component — { name, kind, promptHash, schemaHash } , the join keys of agboss describe --json —, nodeId , visitNumber , copyNumber , itemIndex , idempotencyKey , callId , toolLoopIteration , validationAttempts — the serialized executionContext.step . onExecutionStart fires once per execution at execute ; one that pauses because nothing else can move emits onExecutionPause event.pending : every pause it waits for — again after a partial resume , app.resume and recovery emit onExecutionResume event.reason , event.decision , event.answeredBy , onExecutionEnd fires once when it ends at a finish event.finish : a ComponentRecord , event.spend and onExecutionError when it fails event.error — also after a resume; cancelling a paused execution is an onExecutionError with ExecutionCancelledError . A request refused before an execution starts or is located — another owner's thread, a resume of an unknown pause or one no longer waiting, an execute on an unknown thread or with an invalid input, an exhausted budget, a request after app.close — emits onExecutionRejected operation : ExecutionOperation.Execute | Resume | Cancel , threadId when given, tenantId , the error's stable code , a message without the input values; never an executionId and still throws. A resume refused as incompatible after a deploy IncompatibleResumeError is an onExecutionError on the paused execution; it stays paused. A write that renews a value of the path scope outdates what was built from the older one: onValuesOutdated fires once per such cascade the new value, each outdated value with its OutdatedReason ; never DTO values , and result.record.outdatedValues keeps the values themselves. Assembly rejects an observer with no hook or with a misspelled one did you mean onToolEnd? ; an observer that throws is a warning in the application's log observer.failed and never fails the execution. js import { Application, EmptyEnvironment, Injectable, type AgentStartEvent, type ExecutionEndEvent, type ExecutionRejectedEvent, type OnAgentStart, type OnExecutionEnd, type OnExecutionRejected, } from "@agboss/core"; @Injectable export class MetricsObserver implements OnExecutionEnd, OnAgentStart, OnExecutionRejected { onExecutionEnd event: ExecutionEndEvent : void { console.log ${event.workflow.name} ${event.executionId} tenant ${event.tenantId} cost $${event.spend.totalUsd} ; } onAgentStart event: AgentStartEvent : void { console.log ${event.step.component.name} visit ${event.step.visitNumber} of ${event.executionId} ; } onExecutionRejected event: ExecutionRejectedEvent : void { console.log ${event.operation} refused for ${event.tenantId}: ${event.code} ; } } @Application { name: "metrics-application", version: "1.0.0", environment: EmptyEnvironment, workflows: , observers: MetricsObserver , // the only place observers are registered } export class MetricsApplication {} The framework logs through the application's Logger 261 — infrastructure like the Clock : the built-in ConsoleLogger writes one line per entry to standard error; your own extends Logger write entry: LogEntry goes in @Application { providers } . At start, once, it logs only what the decorators say — what started, and the worst case of one call of each start in counts — then the startup warnings; no project code is called no maxSpend , nothing per tenant: 15:02:11 INFO Started job-scout-application 1.0.0 — environment prod, host scout-7f3a, process 41237 15:02:11 INFO Worst case of one chat-workflow-start call: 1 workflow execution, 1 at the same time, 12 agent and router steps agboss check prints the same worst case, from the same decorators, with how each number is made up 268 — maxItems , maxConcurrency , maxSteps or the longest path, maxDepth ; agboss describe prints it under each workflow's limits: Worst case of one vendor-screening-workflow-start call workflow executions 21 1 vendor-screening-workflow + 20 vendor-check-workflow maxItems 20 at the same time 4 1 vendor-screening-workflow + 3 vendor-check-workflow maxConcurrency 3 agent and router steps 22 2 in vendor-screening-workflow longest path + 20 × 1 in vendor-check-workflow longest path nesting depth 2 vendor-screening-workflow → vendor-check-workflow While it runs it logs only problems of the system — LogLevel.Warn at risk a recovery left to a compatible instance, an observer that threw , LogLevel.Error broken a failed recovery, a failed close — each with its stable code and the executionId / tenantId it is about. One execution's details are its trace, a tenant's spend is the cost ledger, a rejected execution is an observer event. The startup warnings app.warnings include the assembly warnings : tenant or application budgets on the built-in in-memory cost ledger application.in-memory-cost-ledger : each instance counts on its own, the counters reset on restart and pauses possible with the built-in in-memory paused executions or checkpoints application.in-memory-pauses , and PII tokens made with a key of each execution because @Application { pseudonymKey } is not set application.pii-instance-key : one value gets another token in each execution — errors under agboss check --strict , silent in tests testWith logs no start and no warning; an unlisted logger is silent there . Every model call is a usage record caller, model, tokens, USD in the run's spend ExecutionOutput.spend : total, per caller, per category and in the counters of every budget of the execution the application's CostLedgerRepository , in memory unless one is listed . Money limits are @Budget components 261 , all of them in @Application { budgets } written in config/budget.config.ts , one template — @Budget { name, scope, period?, workflow?, deps? } on a class that implements BudgetHandler , one method maxSpend : Usd | Promise<Usd : - BudgetScope.Execution — one full pass of app.execute : a workflow's own workflow: X , at most one or the one default no workflow for every workflow without its own; - BudgetScope.Tenant — one organization tenantId per BudgetPeriod.Day | Week | Month UTC ; - BudgetScope.Application — the whole application per period. Every workflow is covered budget.execution-budget-required , there is at least one tenant and one application budget budget.tenant-budget-required , budget.application-budget-required , and no workflow has two budget.duplicate-execution-budget , budget.duplicate-default-execution-budget — checked at assembly. maxSpend is read once per execution, at its start, in its ExecutionContext a budget injects it, or the project's tenant context, or a service such as billing — a trusted source, never the request body and kept for the whole execution, a resume included; the ledger keeps the last one read. Before the first step every budget is checked — one exhausted rejects the execution onExecutionRejected ; every model call's real cost is then counted in all of them, and before the next step or model call the first exhausted stops the execution with BudgetExceededError — budget { name } , scope , key the application's name, the tenantId or the execution's id , maxSpend , spent , and a sentence: tenant acme spent $40.05 today; tenant-daily-budget allows $40 . .onError BudgetExceededError, … takes it. Nothing is reserved: a budget protects from draining money, so parallel executions of one tenant may overrun it a little, and a budget is exceeded by at most the calls in flight when it was exhausted a cost is known after its call : within one tree every call counts the moment it is made, and the call that exhausts a budget aborts the in-flight calls of the parallel branches beside it 338 . A decision a tool's service makes through ROUTER FACTORY is the tool's spend tool:<name . A paid service that is not a model is recorded with SpendRecorder deps: SpendRecorder , in a @Tool or an @Action : the record joins the spend of the current tool call or step and counts in the same budgets. Called outside a step or a tool call, record throws SpendOutsideStepError spend.outside-step . // config/budget.config.ts — the tenant's own amount, from its server-side data import { Budget, BudgetPeriod, BudgetScope, type BudgetHandler } from "@agboss/core"; import { usd, type Usd } from "@agboss/core/units"; @Budget { name: "tenant-daily-budget", scope: BudgetScope.Tenant, period: BudgetPeriod.Day, deps: ShopTenantContext , } export class TenantDailyBudget implements BudgetHandler { constructor private readonly shopTenantContext: ShopTenantContext {} maxSpend : Usd { return usd this.shopTenantContext.dailyBudgetUsd ; } } @Budget { name: "execution-budget", scope: BudgetScope.Execution, deps: ExecutionContext } export class ExecutionBudget implements BudgetHandler { constructor private readonly executionContext: ExecutionContext {} maxSpend : Usd { return this.executionContext.tenant.weight 1 ? usd 0.5 : usd 0.1 ; // a bigger tenant } } A budget is unit-tested without the container — new TenantDailyBudget testExecutionContext { tenantContext: ShopTenantContext, tenant: { dailyBudgetUsd: 40 } } .tenant .maxSpend is usd 40 — and an application test reaches an exhausted one the real way: mockOf TenantDailyBudget .maxSpend.mockReturnValue usd 0.01 plus a scripted cost replyWith …, { cost: usd 0.02 } . Steps are not money: @Workflow { maxSteps } default agents + routers × 3; StepsLimitExceededError , checked at assembly too — limits.max-steps-too-low when no finish fits in a hand-set maxSteps , or when the default cannot hold the worst case of a per-item launch maxItems runs: set maxSteps , limits.branch-exceeds-max-steps , limits.max-steps-unused . js import { SpendRecorder, Tool, type ToolHandler } from "@agboss/core"; import { usd } from "@agboss/core/units"; @Tool { name: "web-search-tool", description: "Searches the web a paid API ", input: SearchQueryDto, output: SearchResultsDto, deps: SpendRecorder , } export class WebSearchTool implements ToolHandler<SearchQueryDto, SearchResultsDto { constructor private readonly spendRecorder: SpendRecorder {} run { query }: SearchQueryDto : Promise<SearchResultsDto { this.spendRecorder.record { service: "serp-api", cost: usd 0.002 } ; // → tool:web-search-tool return Promise.resolve { text: results for ${query} } ; } } A @PiiPolicy says which personal data the models never see as is 120 . Policies are listed in piiPolicies of @Application , @Workflow , @Agent and @Router : the lists add up, and an agent or a router removes an inherited one with excludePiiPolicies — for its own model and tools only; logs, traces, observer events and result.record stay masked by the application's and the workflow's lists. Masking happens only at the model boundary: what a model reads is masked, what it gives back is revealed before any DTO is validated, so the scope, the checkpoint, every tool, action and finish see real values. replaceWithToken is the reversible one — a tool gets the address the model only saw as <email:7f3a91 an HMAC of the value with pseudonymKey ; the token map is kept in the execution's checkpoint . A blockWithRefusal rule fails the execution with PiiRefusedError kind , refusal when the value comes in or is in an answer, and rejects only the call when it is in tool arguments or a tool result. @PiiPolicy { name: "customer-pii-policy", description: "Contact details hidden, cards refused, names found by a model", rules: pii PiiGroup.Contact, PiiAction.replaceWithKind , // phones, addresses, postal codes pii PiiKind.Email, PiiAction.replaceWithToken , // a kind rule beats its group's pii PiiKind.PersonName, PiiAction.replaceWithKind , pii PiiKind.CardNumber, PiiAction.blockWithRefusal , // the text from refusal kind , detectWithModel: "moonshotai/kimi-k2.6", pseudonymKey: secret "PII PSEUDONYM KEY" , } export class CustomerPiiPolicy implements PiiRefusal { refusal kind: PiiKind : string { return Please do not send a ${kind} here. ; } } @Injectable export class EmployeeDirectory { readonly ids: readonly string = "EMP-0042" ; } // a project's own detector: the framework applies action to every range it finds @PiiPolicy { name: "employee-id-pii-policy", action: PiiAction.replaceWithToken , deps: EmployeeDirectory , } export class EmployeeIdPiiPolicy implements PiiPolicyHandler { constructor private readonly employeeDirectory: EmployeeDirectory {} findMatches text: string : readonly PiiMatch { return this.employeeDirectory.ids.flatMap id = { const start = text.indexOf id ; return start < 0 ? : { start, end: start + id.length } ; } ; } } // a field without a format of its own: the same actions masking ones only export class TicketDto { @Text { prompt: "the customer's account", sensitive: PiiAction.replacePart { keepLast: 4 } } account : string; } Assembly checks the lists: pii.conflicting-rules two policies with different actions for one kind, naming both , pii.exclude-not-inherited , pii.missing-refusal , pii.unused-refusal , pii.kind-needs-model a name or an address without detectWithModel , pii.not-a-policy . Each pseudonymKey is read from its process variable when the app starts a missing one fails the start . The application's own key, @Application { pseudonymKey: "piiPseudonymKey" } , names a Secret field of its environment piiPseudonymKey: secret "PII PSEUDONYM KEY" , like a model provider's apiKey : the key of sensitive fields, of project detectors and of every policy without its own — so one value is one token on every instance, and logs and traces from several machines agree; a policy's own key wins, and a policy that needs the application's when it is not set fails the start, naming the field. Not set and not needed, each instance makes a key of its own: the start goes on with the warning application.pii-instance-key reveal still works — the token map is in the checkpoint — only logs and traces of two instances show one value as two tokens . Under testWith an unset key gets a fixed test key, and mockLlm CustomerPiiPolicy scripts its model detection pii:<policy in the spend . Wiki → Guards PII . Guardrails block safety ; judges correct quality . An @InputGuardrail checks what an agent's or a model router's model reads — its input message, masked by that element's PII policies, before the model is called; an @OutputGuardrail checks what an agent answers. Each asks its model one yes / no question — its prompt — a decision model through one Decision.noul , a chat model through one answer tool; its model or defaults.guardrail.model never defaults.router ; none → guardrail.no-model . At P yes ≥ threshold the execution fails with GuardrailBlockedError guardrail.blocked : refusal is the text to send instead, key the setting that decided guardrails.<name .threshold . A model that does not answer fails closed GuardFailedError . // a computed refusal: the class implements GuardrailRefusal, the execution through deps @InputGuardrail { name: "legal-advice-guardrail", description: "Blocks requests for legal advice", prompt: "Does the message ask for legal advice?", model: "typesafe/jev-1.13", threshold: 0.8, deps: ClinicExecutionContext, RefusalTextService , } export class LegalAdviceGuardrail implements GuardrailRefusal { constructor private readonly clinicExecutionContext: ClinicExecutionContext, private readonly refusalTextService: RefusalTextService, {} refusal : Promise<string { return this.refusalTextService.legalAdvice this.clinicExecutionContext.locale ; } } // a fixed refusal, the model from defaults.guardrail.model @OutputGuardrail { name: "no-legal-advice-guardrail", description: "Blocks answers that give legal advice", prompt: "Does the answer give legal advice?", threshold: 0.8, refusal: "I can't give legal advice. Please contact a lawyer.", } export class NoLegalAdviceGuardrail {} They are listed in guardrails of @Application , @Workflow , @Agent and @Router : the lists add up, excludeGuardrails removes an inherited one for an agent or a router. A model router takes the input guardrails; a code router calls no model and takes none. Assembly checks them all at once: -guardrail names, one refusal both → guardrail.refusal-twice ; neither does not compile, and is guardrail.missing-refusal at assembly , a question guardrail.no-prompt , a threshold in 0, 1 guardrail.threshold-invalid , guardrail.exclude-not-inherited , guardrail.not-a-guardrail , guardrail.output-on-router , guardrail.no-model-call . agboss describe prints each one's side, threshold, model, refusal and the elements it guards. In tests, mockLlm LegalAdviceGuardrail .thenReturn decideWith { blocks: 0.9 } blocks an unscripted guardrail passes , and testGuardrail LegalAdviceGuardrail, { model: decideWith { blocks: 0.9 } , executionContext: ClinicExecutionContext, execution: { locale: "he" } } "Can I sue?" gives { isBlocked, probability, refusal } . A thread's turns are its finished executions start <name : <input / finish <name : <output . Each agent and model router sees the last uncompactedTurns of them in full — set on @Application , @Workflow , @Agent or @Router , the lowest set value wins default 5, TurnLimit.ALL = every turn . What is older is summarised by a @Compaction , named by compaction on the same levels again the lowest wins; none anywhere → the window only : // a queue: every 5 turns older than the window become one summary, the latest 10 are kept @Compaction { name: "conversation-compaction", description: "Summarises old turns of the conversation", prompt: "Summarise the turns under Turns to compact : what was asked, decided and is still open.", model: "moonshotai/kimi-k2.6", strategy: CompactionStrategy.SummaryQueue, turnsBetweenCompactions: 5, summaryQueueLength: 10, summaryMaxTokens: 400, } export class ConversationCompaction {} // one running summary, rewritten from the previous one and the new turns the built-in prompt @Compaction { name: "code-context-compaction", description: "Keeps one summary of the code touched so far", model: "moonshotai/kimi-k2.6", strategy: CompactionStrategy.SingleSummary, turnsBetweenCompactions: 3, summaryMaxTokens: TokenLimit.MODEL MAX, } export class CodeContextCompaction {} // no summaries at all: only the window no model, no prompt, no parameters @Compaction { name: "no-summaries-compaction", description: "Only the window of recent turns", strategy: CompactionStrategy.None, } export class NoSummariesCompaction {} A compaction summarises everything older than the smallest uncompactedTurns among the agents and routers that use it, so no one loses a turn: a router that sees 1 turn and an agent that sees 3 share one compaction that summarises what is older than 1 — the agent sees its 3 turns in full and not the summary they already cover. summaryMaxTokens is the summary call's max tokens the model's server counts it; thinking is off on that call : a summary cut there is asked once more, shorter, and cut again fails the execution with CompactionError compaction — never a cut summary. A compaction runs lazily, before a new execution first reads its thread — never after a turn: a finished answer is always kept, a thread that ends pays for none, and a CompactionError fails the new execution before any of its work no model call, no step, no turn kept . The compaction's model reads the turns through the application's and the workflow's PII policies, its summary is revealed before it is stored, and each reader's own policies mask it on the way into its model. Spend is compaction:<name ; result.compacted says what each compaction did before the execution. In tests, mockLlm ConversationCompaction .thenReturn replyWith "…" scripts it replyWith "…", { truncated: true } is a summary cut at the limit ; unscripted, it writes a fixed summary. scripts/langfuse.sh up self-hosted Langfuse in Docker, keys written to .env Then every run is traced at http://localhost:3000 http://localhost:3000 . Details: Observability & Tracing Guide https://agboss.dev/guides/observability-and-tracing/ · Wiki → Tracing https://github.com/agbossjs/agboss/wiki/Tracing . Tickets move across the GitHub Project board of the repo: | Stage | Skill | Result | |---|---|---| | Triage | triage | business side clarified through quizzes; issue s created or updated, split into sub-issues if needed | | Backlog | spec-session | spec, implementation plan, automated + manual acceptance criteria — in the issue | | In progress → Test | implement | independent issues in parallel; branch + PR per issue, merged to main ; manual-test handoff | | Done | a human | after manual acceptance | Rules and the delivery pipeline: WORKFLOW.md https://github.com/agbossjs/agboss/blob/main/WORKFLOW.md · QUALITY.md https://github.com/agbossjs/agboss/blob/main/QUALITY.md · CLAUDE.md https://github.com/agbossjs/agboss/blob/main/CLAUDE.md . Full documentation lives at https://agboss.dev https://agboss.dev and in the GitHub Wiki https://github.com/agbossjs/agboss/wiki . - CONTRIBUTING.md https://github.com/agbossjs/agboss/blob/main/CONTRIBUTING.md — how a change goes from an issue to a merged pull request. - SECURITY.md https://github.com/agbossjs/agboss/blob/main/SECURITY.md — report a vulnerability privately to security@agboss.dev mailto:security@agboss.dev ; supported versions and what to expect. - CHANGELOG.md https://github.com/agbossjs/agboss/blob/main/CHANGELOG.md — what each release changes; the per-pull-request log with every breaking change is the Wiki's Changelog https://github.com/agbossjs/agboss/wiki/Changelog .