REFERENCE

SDK reference

Complete reference for @taskclan/sdk. TypeScript-first, works in Node 18+, edge runtimes, and any server environment.

Installation

npm install @taskclan/sdk

new Taskclan(options)

Creates a client. All requests inherit these defaults.

Option	Type	Default	Description
`apiKey`	`string`	,	Secret key (required). Server-side only.
`baseUrl`	`string`	`https://api.taskclan.com`	Override the API host.
`defaultProfile`	`Profile`	`"t1-flow"`	Profile used when a call omits one.
`timeout`	`number`	`60000`	Request timeout in ms.
`maxRetries`	`number`	`2`	Automatic retries for transient errors.

import { Taskclan } from "@taskclan/sdk";

const taskclan = new Taskclan({
  apiKey: process.env.TASKCLAN_API_KEY,
  defaultProfile: "t1-flow",
});

taskclan.run(params)

Runs a goal to completion and resolves with a RunResult.

Param	Type	Description
`goal`	`string`	What you want done (required).
`profile`	`"t1-core" \| "t1-flow" \| "t1-max"`	Intelligence profile. Defaults to the client default.
`input`	`Record<string, unknown>`	Structured input the goal can reference.
`tools`	`Tool[]`	Typed tools the run may call. See Agents & tools.
`verify`	`boolean`	Run the evaluation layer before returning.
`maxTokens`	`number`	Upper bound on generated tokens.
`signal`	`AbortSignal`	Cancel an in-flight run.

RunResult

Field	Type	Description
`id`	`string`	Run identifier.
`output`	`string`	Final text output.
`data`	`unknown`	Structured output when produced.
`steps`	`StepTrace[]`	Plan, tool calls and results.
`usage`	`{ inputTokens, outputTokens, costUsd }`	Usage & cost for the run.
`model`	`string`	The model the profile routed to.

taskclan.run.stream(params)

Same params as run(), but returns an async iterable of StreamEvents.

Event `type`	Payload	Emitted when
`plan`	`{ steps }`	The run forms a plan.
`text`	`{ delta }`	A chunk of output text is ready.
`tool_call`	`{ name, input }`	A tool is about to run.
`tool_result`	`{ name, output }`	A tool returned.
`done`	`{ result }`	The run finished; carries the RunResult.
`error`	`{ error }`	The run failed.

const stream = await taskclan.run.stream({ goal: "Write a haiku about the sea" });

for await (const event of stream) {
  if (event.type === "text") process.stdout.write(event.delta);
  if (event.type === "done") console.log("\n", event.result.usage);
}

tool(definition)

Defines a typed tool. See Agents & tools for the full pattern.

Field	Type	Description
`name`	`string`	Unique, snake_case identifier.
`description`	`string`	What the tool does (the model reads this).
`input`	`ZodSchema`	Input schema; validated before `run`.
`run`	`(input) => Promise<unknown>`	Your handler.

Studio & Engine namespaces

taskclan.studio.generate() / edit(), multimodal creation. See the Studio guide.
taskclan.engine.run(workflow, options), deterministic workflows. See the Engine guide.

Errors

All failures throw a TaskclanError with a type, code, status, requestId, and a boolean retryable. See Errors & rate limits.

import { TaskclanError } from "@taskclan/sdk";

try {
  await taskclan.run({ goal: "..." });
} catch (err) {
  if (err instanceof TaskclanError) {
    console.error(err.status, err.code, err.requestId);
  }
}