Amplifier SDK

Seven Lines

A typed client for Amplifier's runtime stream

amplifier-app-newtui · sdk/python + sdk/typescript · v0.1.0

The surface

Amplifier's runtime speaks one versioned JSONL stream anyone can build on

The amplifier-app-newtui repo — a full-screen Textual TUI for the Amplifier platform, built on amplifier-core and amplifier-foundation — serializes its normalized UIEvent queue as JSONL. The same surface the TUI renders is now a stable stream any host can consume.

And it just gained a first-class client →

1session.started — the run begins
2runtime.event — a typed UIEvent with a kind
3turn.completed — the terminal result
4error — a structured failure record

SHIPPED · v0.1.0

The proof

Two idiomatic clients landed together in a single commit

On 2026-07-20, Michael J. Jabbour committed 5aa358d, "Implement priority-zero TUI hardening and SDKs" — the Python and TypeScript SDKs added side by side. The promise is concrete, not aspirational.

So why build a client at all? →

5aa358d

Single commit, both SDKs

+859

Insertions across 10 sdk/ files

2

Parallel clients: Python & TypeScript

0.1.0

Declared version, both packages

The complication

Consuming the raw stream by hand is protocol archaeology

The stream is powerful but hostile to use directly. Without a client you re-parse JSON lines, re-check the schema version, guard against sequence drift, and rebuild every typed record and error mode yourself.

The SDK exists to remove exactly this →

1Re-parse JSON on every line by hand
2Re-check the schema version on each record
3Guard sequence drift — are records in order?
4Rebuild typed records & errors yourself

One shared surface

The SDK wraps the runtime's normalized UIEvent queue — nothing more

Per kernel/jsonl.py, the wire envelope "only adds a stable, sequenced wire envelope around those events; it never reconstructs events or reaches into amplifier-core." The TUI, CI, and SDK therefore share one runtime behavior surface.

Here's how the SDK reaches it →

# kernel/jsonl.py — schema_version 1
SCHEMA_VERSION = 1

# the four record types on the wire
session.started
runtime.event   # event: UIEvent
turn.completed
error

The mechanism

It's a subprocess bridge: stdout JSONL is the only API surface

The client spawns one CLI process per run — Python uses subprocess.Popen(shell=False), TypeScript uses node:child_process spawn. The prompt goes over stdin; versioned JSONL comes back over stdout. No duplicated runtime logic.

And on the way back, it validates everything →

# the SDK invokes the CLI's jsonl mode
<cmd> run --output-format jsonl [--bundle X]

# prompt -> stdin, JSONL -> stdout
child.stdin.end(prompt)

The mechanism

The client does the archaeology for you — and raises typed errors

_validate_record rejects any schema_version != 1, enforces monotonic sequence numbers ("expected JSONL sequence N, got M"), and rejects unknown record types — converting a hostile stream into a validated, typed contract.

Which is what makes the payoff possible →

1ProtocolError — malformed / incompatible JSONL
2ProcessError — no valid terminal record (carries returncode + stderr)
3AmplifierRunError — a valid terminal "error" record

The payoff

The same runtime power, in ~7 fully-typed lines — either language

Each README quickstart is 7 non-blank lines of idiomatic, zero-runtime-dependency code. stream() yields typed records; run() returns a typed RunResult. Python dependencies = []; TypeScript ships only dev deps.

One pattern, generalized →

# python quickstart — 7 non-blank lines
for record in client.stream(prompt, bundle="newtui"):
    if record["type"] == "runtime.event":
        print(record["event"]["kind"])

result = client.run(prompt, bundle="newtui")
print(result.response)

The takeaway

One versioned surface, two idiomatic clients, zero dependencies

The TUI, CI, and your own app all build on the same runtime behavior surface. The SDK — AmplifierClient with stream() and run() over a 4-member typed record union — means no protocol archaeology required.

Shared surface + thin typed clients: the reusable win.

Sources

Research Methodology

Primary source: michaeljabbour/amplifier-app-newtui (public GitHub), branch main, HEAD 19a0589. SDKs under sdk/python and sdk/typescript; wire protocol in src/amplifier_app_newtui/kernel/jsonl.py.

Feature status: SHIPPED — both packages declare v0.1.0; landed 2026-07-20 in commit 5aa358d.

Commands run:

gh repo view michaeljabbour/amplifier-app-newtui --json name,description,isPrivate,pushedAt,url
git log --format='%h %ai %an %s' -- sdk/ ; git show 5aa358d --stat -- sdk/ (single commit, +859 across 10 files)
wc -l sdk/python/src/amplifier_newtui_sdk/__init__.py (288) and wc -l sdk/typescript/src/index.ts (285), test/client.test.ts (117, 3 node:test cases)
cat sdk/python/pyproject.toml ; cat sdk/typescript/package.json (Python dependencies=[]; TS devDependencies only)
cat src/amplifier_app_newtui/kernel/jsonl.py (SCHEMA_VERSION 1; four record types)
grep -n 'output-format' src/amplifier_app_newtui/main.py (click.Choice includes 'jsonl')
grep -rin -E 'http server|fastapi|uvicorn|websocket|event-stream|EventSource' → zero matches (transport is subprocess + JSONL, not HTTP/SSE)

Gaps: Publication to PyPI ("amplifier-newtui-sdk") / npm ("@amplifier/newtui-sdk") was not verified — no registry lookup was run. GitHub last push (2026-07-22) is after the local clone's HEAD.

Primary contributor: Michael J. Jabbour — sole author of SDK commit 5aa358d and repo HEAD. Python pyproject.toml declares author "Microsoft MADE:Explorations Team".