@tetral-ai/sdk 0.110.0-alpha.1

package/src/resources/messages.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './messages/index';

package/src/resources/models.ts

@@ -0,0 +1,274 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as BetaAPI from './beta/beta';
+import { APIPromise } from '../core/api-promise';
+import { Page, type PageParams, PagePromise } from '../core/pagination';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Models extends APIResource {
+  /**
+   * Get a specific model.
+   *
+   * The Models API response can be used to determine information about a specific
+   * model or resolve a model alias to a model ID.
+   */
+  retrieve(
+    modelID: string,
+    params: ModelRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ModelInfo> {
+    const { betas } = params ?? {};
+    return this._client.get(path`/v1/models/${modelID}`, {
+      ...options,
+      headers: buildHeaders([
+        { ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * List available models.
+   *
+   * The Models API response can be used to determine which models are available for
+   * use in the API. More recently released models are listed first.
+   */
+  list(
+    params: ModelListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ModelInfosPage, ModelInfo> {
+    const { betas, ...query } = params ?? {};
+    return this._client.getAPIList('/v1/models', Page<ModelInfo>, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        { ...(betas?.toString() != null ? { 'anthropic-beta': betas?.toString() } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export type ModelInfosPage = Page<ModelInfo>;
+
+/**
+ * Indicates whether a capability is supported.
+ */
+export interface CapabilitySupport {
+  /**
+   * Whether this capability is supported by the model.
+   */
+  supported: boolean;
+}
+
+/**
+ * Context management capability details.
+ */
+export interface ContextManagementCapability {
+  /**
+   * Indicates whether a capability is supported.
+   */
+  clear_thinking_20251015: CapabilitySupport | null;
+
+  /**
+   * Indicates whether a capability is supported.
+   */
+  clear_tool_uses_20250919: CapabilitySupport | null;
+
+  /**
+   * Indicates whether a capability is supported.
+   */
+  compact_20260112: CapabilitySupport | null;
+
+  /**
+   * Whether this capability is supported by the model.
+   */
+  supported: boolean;
+}
+
+/**
+ * Effort (reasoning_effort) capability details.
+ */
+export interface EffortCapability {
+  /**
+   * Whether the model supports high effort level.
+   */
+  high: CapabilitySupport;
+
+  /**
+   * Whether the model supports low effort level.
+   */
+  low: CapabilitySupport;
+
+  /**
+   * Whether the model supports max effort level.
+   */
+  max: CapabilitySupport;
+
+  /**
+   * Whether the model supports medium effort level.
+   */
+  medium: CapabilitySupport;
+
+  /**
+   * Whether this capability is supported by the model.
+   */
+  supported: boolean;
+
+  /**
+   * Indicates whether a capability is supported.
+   */
+  xhigh: CapabilitySupport | null;
+}
+
+/**
+ * Model capability information.
+ */
+export interface ModelCapabilities {
+  /**
+   * Whether the model supports the Batch API.
+   */
+  batch: CapabilitySupport;
+
+  /**
+   * Whether the model supports citation generation.
+   */
+  citations: CapabilitySupport;
+
+  /**
+   * Whether the model supports code execution tools.
+   */
+  code_execution: CapabilitySupport;
+
+  /**
+   * Context management support and available strategies.
+   */
+  context_management: ContextManagementCapability;
+
+  /**
+   * Effort (reasoning_effort) support and available levels.
+   */
+  effort: EffortCapability;
+
+  /**
+   * Whether the model accepts image content blocks.
+   */
+  image_input: CapabilitySupport;
+
+  /**
+   * Whether the model accepts PDF content blocks.
+   */
+  pdf_input: CapabilitySupport;
+
+  /**
+   * Whether the model supports structured output / JSON mode / strict tool schemas.
+   */
+  structured_outputs: CapabilitySupport;
+
+  /**
+   * Thinking capability and supported type configurations.
+   */
+  thinking: ThinkingCapability;
+}
+
+export interface ModelInfo {
+  /**
+   * Unique model identifier.
+   */
+  id: string;
+
+  /**
+   * Model capability information.
+   */
+  capabilities: ModelCapabilities | null;
+
+  /**
+   * RFC 3339 datetime string representing the time at which the model was released.
+   * May be set to an epoch value if the release date is unknown.
+   */
+  created_at: string;
+
+  /**
+   * A human-readable name for the model.
+   */
+  display_name: string;
+
+  /**
+   * Maximum input context window size in tokens for this model.
+   */
+  max_input_tokens: number | null;
+
+  /**
+   * Maximum value for the `max_tokens` parameter when using this model.
+   */
+  max_tokens: number | null;
+
+  /**
+   * Object type.
+   *
+   * For Models, this is always `"model"`.
+   */
+  type: 'model';
+}
+
+/**
+ * Thinking capability details.
+ */
+export interface ThinkingCapability {
+  /**
+   * Whether this capability is supported by the model.
+   */
+  supported: boolean;
+
+  /**
+   * Supported thinking type configurations.
+   */
+  types: ThinkingTypes;
+}
+
+/**
+ * Supported thinking type configurations.
+ */
+export interface ThinkingTypes {
+  /**
+   * Whether the model supports thinking with type 'adaptive' (auto).
+   */
+  adaptive: CapabilitySupport;
+
+  /**
+   * Whether the model supports thinking with type 'enabled'.
+   */
+  enabled: CapabilitySupport;
+}
+
+export interface ModelRetrieveParams {
+  /**
+   * Optional header to specify the beta version(s) you want to use.
+   */
+  betas?: Array<BetaAPI.AnthropicBeta>;
+}
+
+export interface ModelListParams extends PageParams {
+  /**
+   * Header param: Optional header to specify the beta version(s) you want to use.
+   */
+  betas?: Array<BetaAPI.AnthropicBeta>;
+}
+
+export declare namespace Models {
+  export {
+    type CapabilitySupport as CapabilitySupport,
+    type ContextManagementCapability as ContextManagementCapability,
+    type EffortCapability as EffortCapability,
+    type ModelCapabilities as ModelCapabilities,
+    type ModelInfo as ModelInfo,
+    type ThinkingCapability as ThinkingCapability,
+    type ThinkingTypes as ThinkingTypes,
+    type ModelInfosPage as ModelInfosPage,
+    type ModelRetrieveParams as ModelRetrieveParams,
+    type ModelListParams as ModelListParams,
+  };
+}

package/src/resources/shared.ts

@@ -0,0 +1,112 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export interface APIErrorObject {
+  message: string;
+
+  type: 'api_error';
+}
+
+export interface AuthenticationError {
+  message: string;
+
+  type: 'authentication_error';
+}
+
+export interface BillingError {
+  message: string;
+
+  type: 'billing_error';
+}
+
+/** A Tetral Engine write cannot proceed because durable state has changed. */
+export interface ConflictError {
+  message: string;
+
+  type: 'conflict_error';
+}
+
+export type ErrorObject =
+  | InvalidRequestError
+  | AuthenticationError
+  | BillingError
+  | ConflictError
+  | PermissionError
+  | NotFoundError
+  | RequestTooLargeError
+  | RateLimitError
+  | GatewayTimeoutError
+  | APIErrorObject
+  | NotImplementedError
+  | OverloadedError;
+
+export interface ErrorResponse {
+  error: ErrorObject;
+
+  request_id: string | null;
+
+  type: 'error';
+}
+
+export type ErrorType =
+  | 'invalid_request_error'
+  | 'authentication_error'
+  | 'permission_error'
+  | 'not_found_error'
+  | 'conflict_error'
+  | 'request_too_large'
+  | 'not_implemented'
+  | 'rate_limit_error'
+  | 'timeout_error'
+  | 'overloaded_error'
+  | 'api_error'
+  | 'billing_error';
+
+export interface GatewayTimeoutError {
+  message: string;
+
+  type: 'timeout_error';
+}
+
+export interface InvalidRequestError {
+  message: string;
+
+  type: 'invalid_request_error';
+}
+
+export interface NotFoundError {
+  message: string;
+
+  type: 'not_found_error';
+}
+
+/** A Tetral Engine route is recognized but is not implemented by this deployment. */
+export interface NotImplementedError {
+  message: string;
+
+  type: 'not_implemented';
+}
+
+export interface OverloadedError {
+  message: string;
+
+  type: 'overloaded_error';
+}
+
+export interface PermissionError {
+  message: string;
+
+  type: 'permission_error';
+}
+
+export interface RateLimitError {
+  message: string;
+
+  type: 'rate_limit_error';
+}
+
+/** A Tetral Engine request exceeded the route's admitted body or item limit. */
+export interface RequestTooLargeError {
+  message: string;
+
+  type: 'request_too_large';
+}

package/src/resources/top-level.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {};

package/src/resources.ts

@@ -0,0 +1 @@
+export * from './resources/index';

package/src/streaming.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/streaming instead */
+export * from './core/streaming';

package/src/tools/agent-toolset/fs-util.ts

@@ -0,0 +1,157 @@
+/**
+ * Shared, Node-only filesystem helpers for the agent toolset's file tools:
+ * path confinement (symlink-aware), an atomic write, and language-independent
+ * error messages. Kept out of `node.ts` so the tool implementations stay focused
+ * and these helpers can be reused by every file tool.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ToolError } from '../../lib/tools/ToolError';
+
+/** Mode for directories the file tools create — not world-writable under a 0 umask. */
+export const DIR_CREATE_MODE = 0o755;
+/** Mode for files the file tools create. */
+export const FILE_CREATE_MODE = 0o644;
+
+/** `realpath` `p`, or return `p` unchanged when it cannot be resolved. */
+async function realpathOrSelf(p: string): Promise<string> {
+  try {
+    return await fs.realpath(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Fully resolve `abs`: `realpath` the longest existing ancestor and re-append
+ * the rest, but never re-append a component that is itself a symlink — read the
+ * link and continue from its target instead. This handles paths being created
+ * (write/edit) without letting a symlink leaf (e.g. a dangling one pointing
+ * outside a confinement root) slip through unresolved.
+ */
+export async function canonicalize(abs: string): Promise<string> {
+  const tail: string[] = [];
+  let prefix = abs;
+  let hops = 0;
+  for (;;) {
+    let real: string;
+    try {
+      real = await fs.realpath(prefix);
+    } catch {
+      let isLink = false;
+      try {
+        isLink = (await fs.lstat(prefix)).isSymbolicLink();
+      } catch {
+        /* prefix truly doesn't exist (ENOENT) — fall through and walk up */
+      }
+      if (isLink) {
+        // Resolve the symlink ourselves and retry; `tail` (the part below it)
+        // still applies to the link's target. The hop cap matches Linux
+        // MAXSYMLINKS — the same threshold at which `realpath` itself would
+        // have returned ELOOP — so a cycle of unresolvable links terminates.
+        if (++hops > 40) {
+          throw new ToolError(`path ${JSON.stringify(abs)} has too many levels of symbolic links`);
+        }
+        prefix = path.resolve(path.dirname(prefix), await fs.readlink(prefix));
+        continue;
+      }
+      const parent = path.dirname(prefix);
+      if (parent === prefix) return abs; // walked past the FS root without a hit
+      tail.push(path.basename(prefix));
+      prefix = parent;
+      continue;
+    }
+    return tail.length ? path.join(real, ...tail.reverse()) : real;
+  }
+}
+
+/**
+ * Resolve `p` and confine it to `root`.
+ *
+ * Absolute and relative inputs go through the same canonicalise-then-contain
+ * check — an absolute path that lands inside `root` is permitted, only paths
+ * that resolve *outside* are rejected. Every symlink in `p` (including the
+ * leaf, even a dangling one) is resolved before the confinement check, and the
+ * resolved path is what the caller then operates on, so a symlink inside `root`
+ * that points outside it can neither pass the check nor be followed afterwards.
+ *
+ * Residual TOCTOU: a component could still be swapped for a symlink between this
+ * call and the eventual `fs` operation. Closing that fully needs per-component
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; this is why a
+ * sandbox is still recommended for the toolset as a whole.
+ */
+export async function confineToRoot(
+  root: string,
+  p: string,
+  opts?: { allowOutside?: boolean },
+): Promise<string> {
+  const allowOutside = opts?.allowOutside ?? false;
+  const realRoot = await realpathOrSelf(path.resolve(root));
+  const abs = path.resolve(realRoot, p);
+  if (allowOutside) return abs;
+  const real = await canonicalize(abs);
+  // A filesystem root (or Windows drive root) already ends with the
+  // separator; appending another would reject every in-root path.
+  const rootSep = realRoot.endsWith(path.sep) ? realRoot : realRoot + path.sep;
+  if (real !== realRoot && !real.startsWith(rootSep)) {
+    throw new ToolError(`path ${JSON.stringify(p)} escapes workdir`);
+  }
+  return real;
+}
+
+/**
+ * Atomically write `content` to `targetPath`: write a sibling temp file, fsync
+ * it, then rename over the target. The rename is atomic on most filesystems, so
+ * a crash mid-write never leaves the target half-written.
+ */
+export async function atomicWriteFile(targetPath: string, content: string): Promise<void> {
+  const dir = path.dirname(targetPath);
+  const tempPath = path.join(dir, `.tmp-${process.pid}-${randomUUID()}`);
+  let handle: fs.FileHandle | undefined;
+  try {
+    handle = await fs.open(tempPath, 'wx', FILE_CREATE_MODE);
+    await handle.writeFile(content, 'utf-8');
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await fs.rename(tempPath, targetPath);
+  } catch (err) {
+    if (handle) await handle.close().catch(() => {});
+    await fs.unlink(tempPath).catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * Map a thrown filesystem error to a consistent, language-independent message,
+ * so the model sees the same wording regardless of the runtime (Node's raw
+ * `ENOENT: no such file...` text would otherwise leak through). Falls back to
+ * the raw error message for codes we don't special-case.
+ */
+export function fsErrorMessage(err: unknown, file: string): string {
+  const code = (err as { code?: string } | null)?.code;
+  switch (code) {
+    case 'ENOENT':
+      return `${file}: no such file or directory`;
+    case 'EACCES':
+    case 'EPERM':
+      return `${file}: permission denied`;
+    case 'ENOTDIR':
+      return `${file}: not a directory`;
+    case 'EISDIR':
+      return `${file}: is a directory`;
+    case 'ELOOP':
+      return `${file}: too many levels of symbolic links`;
+    case 'ENAMETOOLONG':
+      return `${file}: file name too long`;
+    case 'ENOSPC':
+      return `${file}: no space left on device`;
+    case 'EMFILE':
+    case 'ENFILE':
+      return `${file}: too many open files`;
+    default:
+      return `${file}: ${err instanceof Error ? err.message : String(err)}`;
+  }
+}

package/src/tools/agent-toolset/node.browser.ts

@@ -0,0 +1,90 @@
+/**
+ * Browser stub for `tools/agent-toolset/node`.
+ *
+ * The real module implements the `agent_toolset_20260401` tools on top of Node
+ * built-ins (`node:child_process`, `node:fs`, …), which browser bundlers cannot
+ * resolve. The `browser` field in `package.json` substitutes this stub in
+ * browser builds so the SDK bundles cleanly for web targets; Node runtimes and
+ * node-target bundles ignore the mapping and load the real implementation.
+ *
+ * Every value export here throws an {@link AnthropicError} when used — the
+ * agent toolset only works in Node.js or a Node-compatible runtime. Type
+ * exports are re-exported from the real module (erased at build time), so
+ * type-level usage is unaffected.
+ */
+
+import { AnthropicError } from '../../core/error';
+import type { Anthropic } from '../../client';
+import type { BetaRunnableTool } from '../../lib/tools/BetaRunnableTool';
+import type { AgentToolContext } from './node';
+
+export type { AgentToolContext } from './node';
+
+function nodeOnly(name: string): never {
+  throw new AnthropicError(`${name} requires Node.js or a Node-compatible runtime`);
+}
+
+export function setupSkills(_ctx: AgentToolContext): Promise<() => Promise<void>> {
+  return nodeOnly('setupSkills');
+}
+
+export function resolveSkillVersion(_client: Anthropic, _skillId: string, _version: string): Promise<string> {
+  return nodeOnly('resolveSkillVersion');
+}
+
+export function extractSkillArchive(_resp: Response, _dest: string): Promise<void> {
+  return nodeOnly('extractSkillArchive');
+}
+
+export function betaAgentToolset20260401(_ctx: AgentToolContext): BetaRunnableTool[] {
+  return nodeOnly('betaAgentToolset20260401');
+}
+
+export function resolvePath(_ctx: AgentToolContext, _p: string): Promise<string> {
+  return nodeOnly('resolvePath');
+}
+
+export class BashSession {
+  constructor(_dir: string, _env?: NodeJS.ProcessEnv) {
+    nodeOnly('BashSession');
+  }
+
+  get closed(): boolean {
+    return nodeOnly('BashSession');
+  }
+
+  exec(
+    _command: string,
+    _opts: { timeoutMs?: number; signal?: AbortSignal | null | undefined } = {},
+  ): Promise<{ output: string; exitCode: number }> {
+    return nodeOnly('BashSession');
+  }
+
+  close(): void {
+    nodeOnly('BashSession');
+  }
+}
+
+export function betaBashTool(_ctx: AgentToolContext): BetaRunnableTool {
+  return nodeOnly('betaBashTool');
+}
+
+export function betaReadTool(_ctx: AgentToolContext): BetaRunnableTool {
+  return nodeOnly('betaReadTool');
+}
+
+export function betaWriteTool(_ctx: AgentToolContext): BetaRunnableTool {
+  return nodeOnly('betaWriteTool');
+}
+
+export function betaEditTool(_ctx: AgentToolContext): BetaRunnableTool {
+  return nodeOnly('betaEditTool');
+}
+
+export function betaGlobTool(_ctx: AgentToolContext): BetaRunnableTool {
+  return nodeOnly('betaGlobTool');
+}
+
+export function betaGrepTool(_ctx: AgentToolContext): BetaRunnableTool {
+  return nodeOnly('betaGrepTool');
+}