Code Mode API

Code Mode runs TypeScript with generated caplets.<id> handles. Prefer discovery methods first, then call downstream tools with compact, decision-ready inputs and outputs.

Common Code Mode recipes

Guard against unavailable backends before you spend work on discovery:

const h = caplets.osv;
const ready = await h.check();
if (!ready.ok) {
  return { ok: false, reason: ready.error.message };
}

Discover, describe, and call the best matching tool:

const h = caplets.osv;
const tools = await h.searchTools("package version", { limit: 5 });
const tool = tools.items[0];
if (!tool) return { ok: false, reason: "No matching tool" };

const details = await h.describeTool(tool.name);
const result = await h.callTool(tool.name, {
  ecosystem: "npm",
  name: "react",
  version: "18.2.0",
});

return {
  tool: tool.name,
  callOk: result.ok,
  evidence: result.ok ? result.data : result.error.message,
  schemaKnown: details.ok,
};

Page through larger result sets with nextCursor:

const h = caplets.github;
const repos = [];
let cursor: string | undefined;
do {
  const page = await h.tools({ limit: 25, cursor });
  repos.push(...page.items.map((item) => item.name));
  cursor = page.nextCursor;
} while (cursor && repos.length < 100);

return { count: repos.length, repos };

Use resources and prompts when a Caplet exposes reusable context:

const h = caplets.docs;
const resources = await h.searchResources("configuration", { limit: 3 });
const first = resources.items[0];
const content = first?.uri ? await h.readResource(first.uri) : undefined;

const prompts = await h.searchPrompts("review", { limit: 3 });

return {
  resources: resources.items.map((item) => item.uri),
  firstResourceOk: content?.ok ?? false,
  prompts: prompts.items.map((item) => item.name),
};

Read execution logs through the generated debug handle when a Caplet returns a log ref:

const result = await caplets.debug.readLogs({
  logRef: "caplet-run-log-ref",
  limit: 100,
});

return {
  nextCursor: result.nextCursor,
  errors: result.entries.filter((entry) => entry.level === "error"),
};

Runtime handles

interface CapletHandle<Id extends string> {
  readonly id: Id;
  /** Show this Caplet card, without tool/resource/prompt schemas. */
  inspect(): Promise<CapletCard<Id>>;
  /** Check backend readiness/auth; expected unavailable states return ok:false. */
  check(): Promise<CapletsResult<BackendCheckResult>>;
  /** List tool summaries for the discovery pass; may be empty. */
  tools(input?: PageInput): Promise<Page<ToolSummary>>;
  /** Search tool summaries for the discovery pass; may be empty. */
  searchTools(query: string, input?: PageInput): Promise<Page<ToolSummary>>;
  /** Get schema, callSignature, types, examples; prefer outputSchema/outputTypeScript over observed hints. */
  describeTool(name: string): Promise<CapletsResult<ToolDescriptor>>;
  /** Call one tool; expected failures return ok:false. Filter bulky data in script before returning. */
  callTool(name: string, args?: unknown): Promise<CapletsResult<unknown>>;
  /** List readable resources for the discovery pass; many backends expose none. */
  resources(input?: PageInput): Promise<Page<ResourceSummary>>;
  /** Search readable resources for the discovery pass; many backends expose none. */
  searchResources(query: string, input?: PageInput): Promise<Page<ResourceSummary>>;
  /** List resource templates for the discovery pass; many backends expose none. */
  resourceTemplates(input?: PageInput): Promise<Page<ResourceTemplateSummary>>;
  /** Read one resource by URI; unsupported/missing resources return ok:false. */
  readResource(uri: string): Promise<CapletsResult<ResourceReadResult>>;
  /** List reusable prompts for the discovery pass; many backends expose none. */
  prompts(input?: PageInput): Promise<Page<PromptSummary>>;
  /** Search reusable prompts for the discovery pass; many backends expose none. */
  searchPrompts(query: string, input?: PageInput): Promise<Page<PromptSummary>>;
  /** Get one prompt by name and args; unsupported/missing prompts return ok:false. */
  getPrompt(name: string, args?: unknown): Promise<CapletsResult<PromptResult>>;
  /** Complete a prompt or resource-template argument. */
  complete(input: CompleteInput): Promise<CapletsResult<CompleteResult>>;
}

interface DebugApi {
  readLogs(input: ReadLogsInput): Promise<ReadLogsResult>;
}

type Page<T> = { items: T[]; nextCursor?: string; truncated?: boolean };

type CapletsResult<T> =
  | { ok: true; data: T; meta?: CapletsMeta }
  | { ok: false; error: CapletsError; meta?: CapletsMeta };

type ToolSummary = {
  /** Exact downstream tool identifier for describeTool(name) and callTool(name,args). */
  name: string;
  title?: string;
  description?: string;
  /** Optional author-supplied hint for when to prefer this tool. */
  useWhen?: string;
  /** Optional author-supplied hint for when to avoid this tool. */
  avoidWhen?: string;
  /** True when the tool declares that it only reads data. */
  readOnlyHint?: boolean;
  /** True when the tool declares that it may perform destructive writes. */
  destructiveHint?: boolean;
};

type ToolDescriptor = {
  id?: string;
  tool?: unknown;
  inputSchema?: unknown;
  outputSchema?: unknown;
  callSignature?: string;
  inputTypeScript?: string;
  outputTypeScript?: string;
  observedOutputShape?: ObservedOutputShape;
  examples?: unknown[];
};

type ReadLogsInput = { logRef: string; cursor?: string; limit?: number };

type ReadLogsResult = { entries: CodeModeLogEntry[]; nextCursor?: string };