# Sdk

The hard rules for editing `@kortix/sdk` (packages/sdk), a PUBLISHED npm package with...

- Repository: https://github.com/kortix-ai/suna (20345 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add kortix-ai/suna --skill sdk -g -a claude-code -y`
Codex: `npx skills add kortix-ai/suna --skill sdk -g -a codex -y`
Cursor: `npx skills add kortix-ai/suna --skill sdk -g -a cursor -y`
Gemini CLI: `npx skills add kortix-ai/suna --skill sdk -g -a gemini-cli -y`

## Description

The hard rules for editing `@kortix/sdk` (packages/sdk), a PUBLISHED npm package with constraints no other package in this repo has: TDD is mandatory for the public surface and the stream/transport behavior (failing test first, gates run and pasted every turn, explicit shippable YES/NO/NOT YET); exported names INCLUDING types are a public API contract and renaming one is a breaking change; the `version` field is inert and must never be hand-bumped; adding an export requires three synchronized edits; and a static import-graph tripwire enforces the framework-free core. Load WHENEVER you add, edit, rename, move, export, test, or delete anything under packages/sdk, or touch its streaming/transport layer.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# `@kortix/sdk`

Read the repo-root `AGENTS.md` first, it covers the monorepo (worktrees, the local
stack, verification standard, release topology). This file covers only what is
specific to **this package**, and the traps that have no analogue elsewhere in
the repo.

> ### Three rules before you touch anything
>
> 1. **Write the failing test first** for every change to an exported name, a
>    public behavior, or the stream/transport layer. RED → GREEN → REFACTOR.
>    *A test you have never seen fail is not a test.* An internal refactor with
>    no behavior change adds no test: typecheck plus the existing tests prove it.
>    A test that pins an internal detail and goes red on such a refactor is
>    deleted (the repo testing philosophy, 2026-10-16). The full loop is in
>    **Test-driven, always** below.
> 2. **Never hand back a red suite.** Loop, run, read, fix, re-run, until every
>    test passes. **Loop on the code, never on the test.** Deleting, skipping,
>    weakening, or filtering a test to reach green is forbidden. If the test
>    itself is wrong, or it caught a *pre-existing* bug, stop the loop and say so.
> 3. **Run the gates and paste the output before you answer.** `typecheck` +
>    `test` + `smoke:install`. Then state plainly: **is this shippable to
>    production, YES, NO, or NOT YET?** Never "should work". Never "looks
>    correct".
>
> This package is on npm. A mistake here lands in a stranger's build, not in your
> PR. See **Test-driven, always** below.

## The mental model: what this SDK actually is

Learn this once and most questions answer themselves.

**This SDK talks to two completely different upstreams and hides the seam.**

The rest: https://github.com/kortix-ai/suna/blob/HEAD/.agents/skills/sdk/SKILL.md