jb/paseo

Files

T

Mohamed BoudraandGitHub 7954babca6 Publish the TypeScript SDK and integration guides (#3141 )

* feat(client): publish the TypeScript SDK surface

Make the high-level client API usable for external integrations and document complete agent, workspace, provider, event, and recipe flows.

* fix(client): correlate provider snapshots by daemon cwd

Return the daemon's canonical snapshot identity so waitForReady can match updates for relative, tilde, and otherwise non-canonical paths without duplicating filesystem rules in the SDK.

* test(server): make snapshot cwd assertion portable

* fix(client): gate canonical provider snapshot waits

Older daemons do not expose the canonical snapshot identity needed to correlate workspace updates safely. Require the advertised capability and fail with an update-host message instead of guessing across workspaces.

2026-08-10 13:22:20 +02:00

3.5 KiB

Raw Blame History

title, description, nav, order, category

title	description	nav	order	category
Providers with the SDK	Select a provider and model, discover available configurations, and configure an agent session.	Providers	54	TypeScript SDK

Providers with the SDK

Every agent configuration names both the provider and model:

config: {
  provider: "codex/gpt-5.5",
}

The first / separates the provider from the model. Model IDs can contain additional slashes.

Configure a session

const agent = await client.agents.create({
  config: {
    provider: "codex/gpt-5.5",
    modeId: "full-access",
    thinkingOptionId: "high",
    featureValues: {
      web_search: false,
    },
  },
  cwd: process.cwd(),
  prompt: "Implement the accepted plan and run focused tests.",
});

Field	Meaning
`provider`	Required `provider/model` selection.
`modeId`	Provider operating or permission mode.
`thinkingOptionId`	Provider reasoning level.
`featureValues`	Values for features returned by `providers.listFeatures()`.
`options`	Provider-native settings such as sandbox and permission rules.
`systemPrompt`	Additional system or developer instructions.
`mcpServers`	Session-scoped MCP servers.
`toolPolicy`	Exact preapproval rules for MCP tools.

Provider options lists the accepted sandbox and permission settings.

Discover installed providers and models

const snapshot = await client.providers.waitForReady({
  cwd: process.cwd(),
  timeoutMs: 60_000,
});

for (const entry of snapshot.entries) {
  if (entry.status !== "ready") continue;

  for (const model of entry.models ?? []) {
    console.log(`${entry.provider}/${model.id}`);
  }
}

An entry finishes as ready, unavailable, or error. snapshot() returns immediately and can include loading entries.

Select a discovered model

const snapshot = await client.providers.waitForReady({ cwd: process.cwd() });
const entry = snapshot.entries.find((candidate) => candidate.status === "ready");
const model = entry?.models?.find((candidate) => candidate.isDefault) ?? entry?.models?.[0];

if (!entry || !model) throw new Error("No provider model is ready");

const agent = await client.agents.create({
  config: {
    provider: `${entry.provider}/${model.id}`,
  },
  cwd: process.cwd(),
  prompt: "Summarize this repository.",
});

Discover modes, thinking levels, and features

const models = await client.providers.listModels("codex", { cwd: process.cwd() });
const modes = await client.providers.listModes("codex", { cwd: process.cwd() });

const selectedModel = models.models[0]?.id;
const selectedMode = modes.modes[0]?.id;
if (!selectedModel) throw new Error("No Codex model is available");

const features = await client.providers.listFeatures({
  provider: `codex/${selectedModel}`,
  cwd: process.cwd(),
  modeId: selectedMode,
});

Use IDs returned by the daemon. Provider installations and configured models differ between hosts.

Diagnose an unavailable provider

const result = await client.providers.diagnostic("codex");
console.error(result.diagnostic);

Host-level profiles, binaries, credentials, and custom providers belong in Custom providers.

3.5 KiB Raw Blame History