API reference

The package has seven entry points. Anything not listed here is internal and may change in a patch release.

`just-another-sdk`

Agents

Export	Kind	Description
`Agent`	class	`new Agent(config)`, `.run()`, `.stream()`, `.session()`, `.resumable()`, `.resume()`, `.resumeApproval()`, `.clone()`, `.withTools()`, `.withHandoffs()`
`AgentSession`	type	What `.session(id)` returns: `run`, `stream`, `messages()`, `pop()`, `clear()`, `store`
`run`	function	`run(config, input, options)` — shorthand for a one-shot agent
`runAgent`	function	The loop itself, if you want it without the `Agent` wrapper
`AGENT_DEFAULTS`	const	`maxTurns: 10`, `maxHandoffs: 5`, `toolTimeoutMs: 30000`, `modelTimeoutMs: 120000`, `onToolError: 'return'`, `maxRetries: 2`, `retryDelayMs: 250`, `maxRetryDelayMs: 10000`, `maxOutputRetries: 1`
`AgentConfig`	type	Constructor options — see Agents
`RunOptions`	type	Per-run options
`AgentInput`	type	`string \| ModelMessage[]`
`ToolErrorPolicy`	type	`'return' \| 'throw'`

Tools

Export	Kind	Description
`tool`	function	Defines a tool. Overloaded for schema and no-argument forms
`ToolRegistry`	class	Name-indexed view over an agent's tools
`Tool`, `AnyTool`	type	A defined tool
`ToolSpec`, `NullaryToolSpec`	type	Arguments to `tool()`
`ToolContext`	type	Second argument to a handler: `runId`, `toolCallId`, `agentName`, `turn`, `signal`
`ToolHandler`	type	`(input, context) => output`

Built-in tools

just-another-sdk/tools — see Built-in tools.

Export	Kind	Description
`webTools`	function	All four keyless tools at once
`getWeather`, `geocode`, `wikipedia`, `currencyConvert`	function	Individually. No API key; fixed endpoints
`httpFetch`, `readUrl`	function	Arbitrary URLs. `allow` list required
`webSearch`	function	`webSearch(client)` — you supply the vendor
`extractText`	function	The HTML → prose scrub `readUrl` uses
`PURE_BUILTINS`	const	The five automatic tools, for composing with `builtins: false`
`calculate`, `currentTime`, `dateMath`, `unitConvert`, `think`	const	The automatic tools individually
`UrlPolicy`, `BlockedUrlError`	type/class	`{ allow, maxBytes?, maxRedirects?, methods?, headers?, fetch? }`
`SearchClient`, `SearchQuery`, `SearchResult`	type	The search interface you implement
`WebToolOptions`	type	`{ baseUrl?, fetch?, timeoutMs?, userAgent? }`

just-another-sdk/tools/fs — a separate entry so node:fs stays out of edge bundles.

Export	Kind	Description
`fileTools`	function	`read_file`, `list_directory`, `search_files`, and with `write` two more
`FileToolsOptions`	type	`{ root, write?, maxReadBytes?, maxWriteBytes?, maxEntries? }`
`PathEscapeError`	class	Thrown when a path would leave the root

Export	Kind	Description
`HandoffTarget`	type	An `Agent`, an `AgentConfig`, or a `HandoffSpec`
`HandoffSpec`	type	`{ agent, filter?, describe?, toolName?, description? }`
`HandoffRefusal`	type	`'max_handoffs' \| 'cycle' \| 'already_transferring'`
`AgentLike`	type	Anything with `toConfig()` — how a target is accepted without a runtime import

Results

Export	Kind	Description
`RunResult`	type	What `run()` resolves with. Includes `agentName` and `agentPath`
`RunStep`	type	One model call: `kind` (`turn`/`repair`/`resume`), `agentName`, text, tool calls, results, usage, timing
`StopReason`	type	`'finish' \| 'max_turns'`
`isComplete`	function	`result.stopReason === 'finish'`

Export	Kind	Description
`streamAgent`	function	`streamAgent(config, input, options)` — the functional form of `.stream()`
`StreamedRun`	type	Async-iterable and awaitable. `.runId`, `.completed`, `.textStream()`, `.toTextStream()`, `.toResponse()`, `.toEventStream()`, `.toEventResponse()`, `.abort()`

Streaming over HTTP

Export	Kind	Description
`readEventStream`	function	Client side: parses `toEventResponse()` back into events
`ReadEventStreamOptions`	type	`{ cursor }` — tracks the last `id:` for reconnecting
`EventStreamOptions`	type	`include`, `fromIndex`

Resumable streams

Export	Kind	Description
`memoryStreamStore`	function	Bounded in-memory recordings. One process only
`StreamStore`	type	`append`, `read`, `finish`, `status`
`StreamStatus`	type	`{ count, done, outcome? }`
`StreamOutcome`	type	`'finish' \| 'error'`
`ResumableRun`	type	What `.resumable()` returns
`ResumableOptions`	type	`RunOptions` plus `streamId`
`FollowOptions`	type	`startTimeoutMs`, `idleTimeoutMs`, plus the above

The Redis adapter is in just-another-sdk/streams.

Sessions

Export	Kind	Description
`memorySession`	function	Bounded in-memory store. `{ maxSessions, maxMessagesPerSession }`
`SessionStore`	type	`load(id, options?)`, `append`, `clear`, and optional `pop`
`LoadOptions`	type	`{ limit }` — a hint the store may honour
`ContextPolicy`	type	`maxMessages`, `maxTokens`, `countTokens`, `summarize`
`SummarizeOptions`	type	`model`, `prompt`, `keepRecent`, `maxOutputTokens`, `timeoutMs`
`trimHistory`	function	Applies a `ContextPolicy` to a message list
`estimateTokens`	function	The default `characters / 4` estimator
`isSummaryMessage`	function	Whether a message is a stored recap
`MemorySessionOptions`	type

Configured as session and context on AgentConfig, and sessionId on RunOptions. The backed adapters are in just-another-sdk/sessions. See Sessions.

Reliability

Export	Kind	Description
`RetryPolicy`	type	`maxRetries`, `retryDelayMs`, `maxRetryDelayMs`, `retryOn`

Configured as flat fields on AgentConfig, alongside fallbacks: ModelProvider[]. See Errors → Retries.

Events

Export	Kind	Description
`consoleTracer`	function	Ready-made listener that prints a readable trace
`ConsoleTracerOptions`	type	`verbose`, `color`, `write`, `maxValueLength`
`EventEmitter`	class	The run's event bus
`AgentEvent`	type	Union of every event
`AgentEventType`	type	`'run.start' \| 'model.request' \| …`
`EventOfType<T>`	type	Narrows `AgentEvent` by `type`
`EventListener`	type	`(event: AgentEvent) => void`
`RunStartEvent` … `RunErrorEvent`	type	Individual event shapes
`ModelRetryEvent`	type	`attempt`, `maxAttempts`, `delayMs`, `discardedText`
`ModelFallbackEvent`	type	`fromModelId`, `toModelId`, `index`, `error`
`OutputInvalidEvent`	type	`attempt`, `maxAttempts`, `issues`, `repairing`
`GuardrailTriggeredEvent`	type	`guardrail`, `stage`, `action`, `toolName?`, `reason?`
`HandoffStartEvent`	type	`from`, `to`, `toolName`, `reason?`, `carriedCount`
`HandoffRefusedEvent`	type	`from`, `to`, `cause`, `reason`
`ApprovalRequiredEvent`	type	`turn`, `calls`
`ApprovalResolvedEvent`	type	`toolCallId`, `toolName`, `approved`, `reason?`
`SessionLoadEvent`	type	`sessionId`, `messageCount`, `droppedCount`, `truncated`
`SessionSummarizeEvent`	type	`coveredCount`, `foldedCount`, `keptCount`, `error?`
`SessionSaveEvent`	type	`sessionId`, `appendedCount`

Errors

Export	Code
`AgentError`	base class for all of the below
`ConfigurationError`	`configuration_error`
`AuthenticationError`	`authentication_error`
`RateLimitError`	`rate_limit_error` — carries `retryAfterMs`
`ProviderError`	`provider_error` — carries `status`
`NetworkError`	`network_error`
`TimeoutError`	`timeout_error`
`AbortError`	`aborted`
`InvalidToolInputError`	`invalid_tool_input` — carries `issues`
`ToolExecutionError`	`tool_execution_error`
`ToolNotFoundError`	`tool_not_found`
`InvalidSchemaError`	`invalid_schema`
`InvalidOutputError`	`invalid_output` — carries `issues`, `rawText`, `attempts`
`GuardrailError`	`guardrail_blocked` — carries `guardrail`, `stage`, `subject`
`ApprovalRequiredError`	`approval_required` — carries `suspension`
`isAgentError`	narrowing helper
`toAgentError`	wraps any thrown value as an `AgentError`
`AgentErrorCode`, `SchemaIssue`	types

Messages

Export	Kind	Description
`userMessage`, `assistantMessage`, `toolMessage`, `textPart`	function	Constructors
`isTextPart`, `isToolCallPart`, `isToolResultPart`	function	Narrowing
`messageText`	function	Concatenated text of a message
`addUsage`, `ZERO_USAGE`	function/const	Usage arithmetic
`ModelMessage`, `SystemMessage`, `UserMessage`, `AssistantMessage`, `ToolMessage`	type	Message shapes
`ContentPart`, `TextPart`, `ToolCallPart`, `ToolResultPart`	type	Content shapes
`Usage`, `MessageRole`	type

Schema interop

Export	Kind	Description
`validate`	function	Validate a value against any Standard Schema
`resolveJsonSchema`	function	Derive JSON Schema from a validator schema
`SchemaSubject`	type	Whose schema is being converted, for error wording
`registerJsonSchemaConverter`	function	Teach the SDK a validator's converter
`isStandardSchema`	function	Runtime guard
`StandardSchemaV1`, `InferSchemaOutput`, `ValidationResult`	type
`JsonSchema`, `ObjectJsonSchema`	type

Guardrails

Export	Kind	Description
`InputGuardrail`, `OutputGuardrail<T>`, `ToolGuardrail<T>`, `AnyToolGuardrail`	type	The three kinds — see Guardrails
`GuardrailVerdict<T>`, `ToolGuardrailVerdict`	type	`allow` · `replace` · `reject` · `requireApproval`
`GuardrailAllow`, `GuardrailRewrite<T>`, `GuardrailReject`, `GuardrailRequireApproval`	type	The individual verdict shapes
`GuardrailContext`, `OutputGuardrailContext`, `ToolGuardrailSubject<T>`	type	What a `check` receives
`ApprovalSuspension`, `PendingApproval`, `PendingToolCall`	type	A suspended run, as plain JSON
`ApprovalDecision`	type	`{ toolCallId, approved, reason? }`

Re-exported from the root so writing a provider needs only one import: ModelProvider, ModelRequest, ModelResponse, ModelCallOptions, ModelStreamChunk, ToolDefinition, ToolChoice, FinishReason, ResponseFormat, plus the helpers textOf and toolCallsOf.

Utilities

Export	Description
`createId`	Sortable prefixed id, e.g. `run_m9x2k1p_a7f3z9`
`redact`, `redactHeaders`, `redactString`	Secret redaction — see Errors

`just-another-sdk/providers`

Export	Description
`anthropic(modelId, options?)`	Claude, natively
`google(modelId, options?)`	Gemini, natively
`gemini(modelId, options?)`	Alias of `google`
`openai(modelId, options?)`	OpenAI Chat Completions
`openrouter(modelId, options?)`	OpenRouter
`compatible(modelId, options)`	Any OpenAI-compatible endpoint
`createOpenAICompatibleProvider(config)`	The shared OpenAI transport, for building on

Option types are exported alongside each: AnthropicOptions, GoogleOptions, OpenAIOptions, OpenRouterOptions, CompatibleOptions, and OpenAICompatibleConfig.

`just-another-sdk/sessions`

Runtime-neutral: every adapter here takes a client you already have, so nothing in this entry point imports a Node builtin.

Export	Description
`redisSession(client \| options)`	`node-redis` or `ioredis`, detected
`postgresSession(client \| options)`	`pg`, `postgres.js`, Drizzle, Prisma, or a query function
`drizzleSession(db \| options)`	Drizzle, via `db.$client`
`prismaSession(client \| options)`	Prisma, via `$queryRawUnsafe` / `$executeRawUnsafe`
`memorySession`, `trimHistory`, `estimateTokens`	Re-exported from the root
`assertValidSessionId`	The guard every adapter applies to an untrusted id
`SessionStore`, `ContextPolicy`	types
`RedisClient`, `NodeRedisLike`, `IoRedisLike`, `RedisSessionOptions`	types
`PostgresClient`, `PgClientLike`, `PostgresJsLike`, `PrismaLike`, `DrizzleLike`, `SqlQuery`, `PostgresSessionOptions`	types

`just-another-sdk/sessions/file`

Export	Description
`fileSession(dir \| options)`	One JSONL file per session. Needs `node:fs`
`FileSessionOptions`	type

`just-another-sdk/sessions/sqlite`

Export	Description
`sqliteSession(path \| options)`	Needs `node:sqlite`, so Node ≥ 22.5
`SqliteSessionOptions`	type

`just-another-sdk/streams`

Export	Description
`memoryStreamStore(options?)`	Default recordings store. One process only
`redisStreamStore(client \| options)`	Multi-instance. `node-redis` or `ioredis`
`startResumable`, `resumeStream`	Functional forms of `.resumable()` / `.resume()`
`StreamStore`, `StreamStatus`, `StreamOutcome`, `ResumableRun`, `ResumableOptions`, `FollowOptions`	types
`RedisStreamClient`, `NodeRedisStreamLike`, `IoRedisStreamLike`, `RedisStreamStoreOptions`	types

`just-another-sdk/testing`

Export	Description
`mockProvider(script, options?)`	A scripted, offline provider
`collectEvents()`	Records a run's events for assertions
`MockProvider`, `MockTurn`, `MockToolCall`, `MockProviderOptions`, `EventCollector`	types

See Testing for usage.

Version policy

While the package is 0.x, minor versions may contain breaking changes; they are documented in the changelog. New members are added to the AgentEvent and AgentErrorCode unions in minor releases, so switch on them with a default branch.