SDK Reference

The complete surface of the CloudPeek client from @cloudpeek/core/agent. This inventory is locked by tests in the package — a method appears here if and only if it exists on the client — and breaking changes to it bump the package's major version.

Initialization

Method	What it does
`CloudPeek.init(options)`	Configure the module default instance the static namespaces delegate to.
`CloudPeek.create(options)`	Build an independent instance (tests, multiple runtimes per process).
`CloudPeek.as(principal)`	Principal-bound view of the default runtime (multi-tenant embedders).
`CloudPeek.on(eventType, handler)`	Subscribe to lifecycle events; `"*"` for all. Returns an unsubscribe function.
`CloudPeek.dispose()`	Abort in-flight runs and close the database.
`CloudPeek.initialized`	Whether `init()` has been called.

Options

Option	Purpose
`database`	`":memory:"`, `"sqlite:///path.db"`, or a Postgres URL. SQLite schema is always created by the SDK.
`migrate`	Postgres only: opt in to running core migrations. Without it, a missing schema fails closed.
`migrationsDir`	Override the packaged migrations directory.
`llm` / `model`	Explicit LLM configuration, or a model override for the environment-derived default.
`principal`	Default `PrincipalContext` (`tenantId`, `userId?`, `roles?`, `token?`, `displayName?`).
`executeDynamicTool` / `resolveDynamicToolRoute`	In-process custom tool execution and optional name routing.
`runbookProvider`	Playbook source enabling `playbook_list` / `playbook_execute`.
`wikiManager`	Pre-built core `WikiManager` enabling the `wiki_*` built-ins.
`memoryService`	Backing service enabling `memory_*` built-ins and `CloudPeek.memory`.
`eventPublisher`	Lifecycle event hook (same stream as `on()`).
`maxContextTokens`	Context window override; defaults to a per-model lookup.

`CloudPeek.agent`

Method	What it does
`run(opts)`	Run the agent to completion. Returns the result with status `completed`, `failed`, `incomplete`, or `requires_action`, plus `runId`.
`stream(opts)`	Same run as an async iterable of live events. Approval gates only fire here.
`resume(runId, outputs)`	Continue a run that stopped with `requires_action`, supplying client-side tool results.
`cancel(runId)`	Stop an in-flight run cooperatively. Returns `false` for unknown ids.

Run options: input, instructions, agentsMd (behaviour profile layered below the core rules and above instructions), maxIterations (default 10), agentName, hitlMode (disabled / approval_only / external_only / external_write_only / full), planMode, model, tools (each optionally isReadOnly), history, principal, signal, runId.

`CloudPeek.sessions`

Every operation is tenant-scoped: sessions belonging to another tenant fail closed as not-found.

Method	What it does
`get(sessionId)`	Fetch one session with its state and metadata.
`list(filter?)`	List the principal tenant's sessions.
`status(sessionId)`	Lightweight status check.
`pause(sessionId)` / `resume(sessionId)`	Pause at the next safe point / resume a paused session.
`complete(sessionId)` / `cancel(sessionId)`	Mark finished / cancel and release resources.

`CloudPeek.hitl`

Method	What it does
`pending(runId?)`	Approvals waiting on a human, optionally filtered to one run.
`approve(approvalId)`	Approve a pending tool call; the paused run continues.
`deny(approvalId)`	Reject it; the agent receives the rejection as context.

Approve/deny are scoped to the initiating user's principal.userId; unauthorized callers are rejected and the approval stays visible in pending().

`CloudPeek.llm`

Direct model access on the configured provider — no agent loop.

Method	What it does
`text(prompt, opts?)`	One completion, plain text back.
`json(prompt, opts?)`	One completion, parsed JSON back.
`embed(input)`	Embedding vector(s) for the input.

`CloudPeek.memory`

Requires a configured memoryService; otherwise every method throws a structured not-configured error.

Method	What it does
`add(content, opts?)`	Store a memory for the principal's tenant.
`search(query, opts?)`	Semantic search over stored memories.
`list(opts?)`	All memories in scope.
`delete(memoryId, opts?)`	Remove one memory.

All four accept an optional operationId to scope memories to one operation.

Errors

Error	Thrown when
`CloudPeekNotInitializedError`	A static namespace is used before `init()`.
`CloudPeekNotConfiguredError`	A namespace's backing service isn't configured, no principal is available, or `resume()` is called without outputs or for an unknown run.
`CloudPeekSchemaError`	The Postgres schema is missing and `migrate: true` was not passed.

All three carry stable name values for programmatic handling.

Stability

@cloudpeek/core/agent is a curated surface: its exports and the per-namespace method inventories above are asserted exactly by the package's surface-lock tests, and semver on the package tracks this surface. Types re-exported here (AgenticExecutor, the persistence and LLM seams) let advanced embedders bypass the facade and construct the runtime directly with the same contract.