@tarkahq/sdk 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,701 @@
-# Temporary Holding Version
+# Tarka JavaScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official Tarka SDK for JavaScript and TypeScript. A resource API for
+inference, organizations, compute, storage, Git, and sandboxes, backed by
+generated protobuf bindings from the same contract as the
+[Python SDK](https://github.com/TarkaHQ/sdk-python).
+
+```js
+const models = await client.models.list();
+const text = await client.chat.text({ model, prompt: "Hello!" });
+const sandbox = await client.org(orgId).sandboxes.create({ template });
+const result = await sandbox.run('print("Hello from Tarka")');
+console.log(result.status, result.stdout);
+```
+
+- Node.js 22+, with ESM, CommonJS, and TypeScript declarations.
+- Wrappers for all 60 RPCs in the pinned API contract.
+- Arrays from lists, entities from reads and writes, async iterables from streams.
+- Organization context, readable statuses, and recoverable sandbox operations.
+- Two direct runtime dependencies: `@grpc/grpc-js` and `@bufbuild/protobuf`.
+- Raw transport access stays under `client.grpc` and `@tarkahq/sdk/grpc`.
+
+This version targets Node.js, including server applications. Browser and edge
+runtimes without Node's HTTP/2 support are outside its scope.
+
+Inference uses `tarka.inference.v1.InferenceService`. Regenerate native gRPC
+clients when upgrading from the previous inference namespace; RPC paths and
+generated import paths now use `v1`. The resource API is unchanged.
+
+## Installation
+
+The intended npm package name is `@tarkahq/sdk`. This repository does not imply
+that the package is already published. To use this version locally:
+
+```sh
+git clone https://github.com/TarkaHQ/sdk-javascript.git
+cd sdk-javascript
+npm ci
+npm pack
+# From your application directory:
+npm install /path/to/sdk-javascript/tarkahq-sdk-0.3.0.tgz
+```
+
+After publication, use `npm install @tarkahq/sdk`. Consumers need neither
+`protoc` nor an API checkout; the package includes generated code and types.
+
+## Quick start
+
+```js
+import { TarkaClient } from "@tarkahq/sdk";
+
+const accessToken = process.env.TARKA_API_KEY;
+const model = process.env.TARKA_MODEL;
+if (!accessToken || !model) {
+  throw new Error("Set TARKA_API_KEY and TARKA_MODEL");
+}
+
+const client = new TarkaClient({ accessToken, timeoutMs: 30_000 });
+try {
+  console.log(await client.models.list());
+  console.log(
+    await client.chat.text({
+      model,
+      prompt: "Say hello in Nepali.",
+      maxTokens: 100,
+    }),
+  );
+} finally {
+  client.close();
+}
+```
+
+CommonJS: `const { TarkaClient } = require("@tarkahq/sdk")`.
+Reuse one client across requests and close it on application shutdown.
+`close()` is idempotent and closes only connections owned by the SDK.
+Runnable, type-checked scripts are in [examples](examples).
+
+TypeScript declarations are included for ESM and CommonJS; no separate `@types`
+package is needed. Public methods and types include JSDoc for editor hovers,
+parameter descriptions, defaults, result semantics, and examples. JavaScript
+editors use the same declarations for autocomplete and hover documentation.
+Enable `// @ts-check` to also check types in a JavaScript file:
+
+```js
+// @ts-check
+import { TarkaClient } from "@tarkahq/sdk";
+
+/** @type {import("@tarkahq/sdk").ChatInput} */
+const input = { model: "your-model-alias", prompt: "Hello", maxTokens: 100 };
+
+/**
+ * @param {TarkaClient} client
+ * @param {import("@tarkahq/sdk").ChatInput} input
+ * @returns {Promise<string>}
+ */
+async function reply(client, input) {
+  return client.chat.text(input);
+}
+```
+
+Hover over input fields as well as methods for their documentation. For example,
+`timeoutMs` describes the client wait budget, `timeoutSeconds` describes the
+server limit, and chat `metadata` is distinguished from transport metadata.
+See [the JavaScript example](examples/chat.mjs) for a complete script. Explicit
+JSDoc annotations are useful for reusable helpers; direct SDK calls already
+infer their inputs and results.
+
+The default endpoint is `grpc.tarka.rest:443`. The SDK uses TLS and bearer
+authentication. Pass the token itself without `Bearer`. Environment variables
+are read by your application, not implicitly by the SDK.
+
+Use an account access token for provisioning. Inference accepts suitably scoped
+`tk_live_...` keys; sandboxes accept account tokens or keys with the `sandboxes`
+scope. Organization membership, product access, and model policy still apply.
+
+## API conventions
+
+| Operation            | Convention                                                                     |
+| -------------------- | ------------------------------------------------------------------------------ |
+| List                 | `list()` returns an array directly; no `.data`, `.items`, or service envelope. |
+| Get                  | `get(id)` returns the entity.                                                  |
+| Create / update      | Return the entity; no request or response wrapper objects.                     |
+| Delete               | Resolves to `undefined` (`Promise<void>`).                                     |
+| Revoke / cancel      | Return the updated entity.                                                     |
+| Stream               | An `AsyncIterable`; consume with `for await`.                                  |
+| Request settings     | `timeoutMs`, `signal`, and plain-object `metadata`.                            |
+| Organization context | Bind once with `client.org(orgId)`; nested calls omit `orgId`.                 |
+| Sandbox entities     | Lists, gets, creates, and waits return the same handle types.                  |
+
+Calls with no input need no `{}`. Request settings go directly to input-free
+methods, or after the input for other methods:
+
+```js
+await client.models.list({ timeoutMs: 10_000 });
+await client.models.get(model, { timeoutMs: 10_000 });
+await client.chat.text({ model, prompt: "Hello" }, { timeoutMs: 10_000 });
+```
+
+Methods with optional filters or input can be called with no arguments.
+To supply only request settings to those methods, pass `undefined` for the input:
+`client.catalog.list(undefined, { timeoutMs: 10_000 })`.
+
+Creation of API keys and storage credentials returns the normal entity fields
+plus its one-time secret. For example, an API key has `id`, `label`, and `secret`,
+rather than `{ apiKey, plaintextKey }`. Store the secret securely at creation;
+list calls do not return it.
+
+## Chat, models, and Responses
+
+```js
+const models = await client.models.list();
+const modelInfo = await client.models.get(model);
+const catalog = await client.catalog.list({ modality: "text" });
+
+const completion = await client.chat.create({
+  model,
+  messages: [{ role: "user", content: "Explain HTTP/2 briefly." }],
+  temperature: 0.2,
+});
+
+for await (const text of client.chat.streamText({
+  model,
+  system: "Be concise.",
+  prompt: "Explain HTTP/2 briefly.",
+})) {
+  process.stdout.write(text);
+}
+```
+
+Supply either `prompt` with an optional `system`, or a non-empty `messages`
+array. `create()` returns the full completion, including usage and tool calls;
+`stream()` returns full chunks. `text()` selects choice 0 and rejects if it
+contains no text. `streamText()` yields choice 0's text deltas, skipping usage
+and tool-call chunks. Streaming mode is selected by the method.
+
+`models` describes the inference-visible models. `catalog` exposes the control
+plane model catalog, including provisioning information and modality filtering.
+
+The JSON APIs accept ordinary OpenAI-compatible objects, retaining their
+original field names, and return the response body directly. They support
+forward-compatible fields without protobuf envelope objects:
+
+```js
+const completion = await client.chat.json.create({
+  model,
+  messages: [{ role: "user", content: "Hello" }],
+  max_tokens: 100,
+});
+console.log(completion.choices);
+
+const response = await client.responses.create({ model, input: "Hello" });
+console.log(response.id);
+
+for await (const event of client.responses.stream({ model, input: "Hello" })) {
+  console.log(event.type, event.data);
+}
+```
+
+JSON streams yield `{ type, data }`. Both JSON chat and Responses select
+`stream: false` for `create()` and `stream: true` for `stream()`.
+Responses also provides `get(id)`, `cancel(id)`, and `delete(id)`.
+JSON outputs use `JsonObject` / `JsonValue`; narrow dynamic values before using
+them in TypeScript. The typed chat API provides completion-specific types.
+
+## OCR and audio
+
+```js
+import { readFile, writeFile } from "node:fs/promises";
+
+const text = await client.ocr.text({ model: ocrModel, image: imageUrl });
+const transcript = await client.audio.transcriptions.text({
+  model: transcriptionModel,
+  file: await readFile("recording.wav"),
+  filename: "recording.wav",
+});
+const speech = await client.audio.speech.create({
+  model: speechModel,
+  input: "Hello from Tarka.",
+});
+await writeFile("speech.audio", speech.data);
+console.log(speech.contentType);
+```
+
+OCR takes either `image` or a non-empty `images` array. It offers `create()` and
+`stream()` for complete results, plus `text()` and `streamText()` for strings.
+Both `audio.transcriptions` and `audio.translations` offer `create()` and `text()`.
+
+`audio.speech.create()` collects the response into `{ data: Buffer, contentType }`.
+Use `audio.speech.stream()` for large outputs; it yields chunks of the same shape.
+`audio.voices` provides `create({ model, name, sample, consentSignedBy,
+consentDate, ... })`, `get(id)`, and `delete(id)` for voice cloning.
+
+## Organizations, keys, compute, storage, and Git
+
+```js
+const user = await client.user.get();
+const org = client.org(user.defaultOrgId); // No network request.
+
+const keys = await org.apiKeys.list();
+const key = await org.apiKeys.create({
+  label: "my-app",
+  scopes: ["inference"],
+});
+const usage = await org.usage.summary();
+
+const bucket = await org.storage.buckets.create({ name: "my-data" });
+const credential = await org.storage
+  .credentials(bucket.id)
+  .create({ label: "worker" });
+// credential includes accessKeyId, secretAccessKey, endpoint, and region.
+
+const repository = await org.repositories.create({
+  name: "my-project",
+  initialize: true,
+});
+```
+
+The complete resource surface is below. IDs are strings, inputs are objects,
+and each method accepts request settings in the last argument.
+
+| Resource                                       | Methods                                                                   |
+| ---------------------------------------------- | ------------------------------------------------------------------------- |
+| `client.models`                                | `list()`, `get(id)`                                                       |
+| `client.catalog`                               | `list({ modality? }?)`                                                    |
+| `client.chat`                                  | `create(input)`, `stream(input)`, `text(input)`, `streamText(input)`      |
+| `client.chat.json`                             | `create(body)`, `stream(body)`                                            |
+| `client.responses`                             | `create(body)`, `stream(body)`, `get(id)`, `cancel(id)`, `delete(id)`     |
+| `client.ocr`                                   | `create(input)`, `stream(input)`, `text(input)`, `streamText(input)`      |
+| `client.audio.transcriptions`, `.translations` | `create(input)`, `text(input)`                                            |
+| `client.audio.speech`                          | `create(input)`, `stream(input)`                                          |
+| `client.audio.voices`                          | `create(input)`, `get(id)`, `delete(id)`                                  |
+| `client.user`                                  | `get()`, `bootstrap({ orgName? }?)`                                       |
+| `client.organizations`                         | `list()`, `get(id)`, `create({ name, slug? })`                            |
+| `client.git`                                   | `ensureAccess()`                                                          |
+| `org`                                          | `get()`, `update({ name })`                                               |
+| `org.members`                                  | `list()`                                                                  |
+| `org.accessRequests`                           | `list({ product?, limit? }?)`, `create({ product, ... })`                 |
+| `org.apiKeys`                                  | `list()`, `create({ label?, scopes?, ... }?)`, `revoke(id, { reason? }?)` |
+| `org.quotas`                                   | `get()`, `update({ allowAllModels, ... })`                                |
+| `org.usage`                                    | `list({ limit? }?)`, `summary()`                                          |
+| `org.compute.resources`                        | `list({ resourceType? }?)`, `get(id)`                                     |
+| `org.compute.inferenceServices`                | `create({ name, modelAlias, ... })`                                       |
+| `org.compute.agentHosts`                       | `create({ name, image, ... })`                                            |
+| `org.compute.jobs`                             | `create({ name, image, command?, ... })`                                  |
+| `org.storage.buckets`                          | `list()`, `create({ name })`, `delete(id)`                                |
+| `org.storage.credentials(bucketId)`            | `list()`, `create({ label? }?)`, `revoke(id)`                             |
+| `org.repositories`                             | `list()`, `create({ name, ... })`, `delete(id)`                           |
+| `org.sandboxes`                                | `list()`, `get(id)`, `create({ template, ... })`, `delete(id)`            |
+| `org.sandboxes.templates`                      | `list()`, `get(id)`, `create(input)`, `delete(id)`                        |
+| `sandbox.executions`                           | `get(id)`, `create({ code, ... })`                                        |
+
+`org.quotas.update()` replaces the policy: omitted optional limits become
+unlimited. Pass the desired full policy, including `allowedModelAliases` when
+restricting models. List filters use the server's default limits; lists do not
+silently fetch additional pages. Exported input and result types describe every
+field and appear in editor completion.
+
+## Sandboxes and templates
+
+```js
+const sandboxes = client.org(orgId).sandboxes;
+const templates = await sandboxes.templates.list();
+const sandbox = await sandboxes.create({ template, timeoutSeconds: 600 });
+
+const execution = await sandbox.run(
+  'print("hello from Tarka")',
+  { timeoutSeconds: 30 },
+  { timeoutMs: 60_000 },
+);
+console.log(execution.status, execution.stdout, execution.stderr);
+await sandbox.delete();
+```
+
+`run()` waits for readiness, submits code, then waits for completion within
+**one total timeout**. To submit without waiting, call `sandbox.execute(code)`
+or `sandbox.executions.create({ code })`; both return an `Execution` handle.
+Fetch one with `sandbox.executions.get(id)` and finish waiting with `execution.wait()`.
+
+`Sandbox`, `SandboxTemplate`, and `Execution` handles expose `id`, `status`,
+`info` (the latest snapshot), `refresh()`, and `toJSON()`. Refreshing and waiting
+update the existing handle and return it. `list()`, `get()`, and `create()`
+return the same handle type for a resource. Handles keep their organization
+and resource IDs; you never pass that context again.
+
+Sandbox and template handles add `waitUntilReady()` and `delete()`.
+Execution handles add `wait()`, `stdout`, `stderr`, `exitCode`, and `outputTruncated`.
+Statuses are readable strings such as `"ready"`, `"running"`, `"succeeded"`,
+`"failed"`, and `"timed_out"`; runtimes are `"python"` or `"node"`.
+
+A finished execution is returned even when the code failed or reached its server
+time limit: inspect `status`, `exitCode`, `stderr`, and `outputTruncated`.
+Waiting on a failed sandbox/template or an unknown execution status throws
+`ResourceStateError`, with `resource` and the server snapshot in `info`.
+
+Create a template with exactly one dependency manifest. There are no protobuf
+`oneof` tags in the public input:
+
+```js
+const template = await sandboxes.templates.create({
+  alias: "python-with-numpy",
+  baseTemplateAlias: "your-python-base-alias",
+  requirementsTxt: "numpy==2.0.0",
+});
+await template.waitUntilReady({ timeoutMs: 300_000 });
+```
+
+The alternatives are `packageJson` and `pyprojectToml`, each containing the file
+contents as a string. Discover available base templates with `templates.list()`.
+
+## Timeouts and recovery
+
+Every request accepts `{ timeoutMs, signal, metadata }`. `timeoutMs` must be
+finite and non-negative; zero expires immediately. It overrides the client's
+default. Without a per-call or client timeout, ordinary RPCs have no SDK deadline.
+For a stream, the timeout covers its entire lifetime, not just gaps between chunks.
+
+Sandbox `run()`, `waitUntilReady()`, and execution `wait()` default to a **60-second
+total budget**, overriding the client default, with a **1-second poll interval**.
+Set `pollIntervalMs` to change polling. The budget includes requests and delays.
+`timeoutSeconds` in resource input is a server-side lifetime/execution limit;
+`timeoutMs` in request settings limits how long the client waits.
+
+Timeout or cancellation does not establish that a mutation failed. Code may
+still be running remotely. The sandbox helpers attach recovery context and a
+typed `resume()` to transient failures:
+
+```js
+import { ExecutionOperationError } from "@tarkahq/sdk";
+
+let execution;
+try {
+  execution = await sandbox.run('print("hello")', undefined, {
+    timeoutMs: 10_000,
+  });
+} catch (error) {
+  if (!(error instanceof ExecutionOperationError)) throw error;
+  console.log(error.code, error.recovery);
+  execution = await error.resume({ timeoutMs: 60_000 });
+}
+console.log(execution.status, execution.stdout);
+await sandbox.delete();
+```
+
+- If an execution ID is known, `resume()` polls that execution. It does not
+  submit the code again.
+- If creation/submission was not acknowledged, `resume()` repeats the original
+  request with the same idempotency key, allowing the server to deduplicate it.
+- If `run()` timed out before readiness, recovery waits for readiness and then
+  submits the preserved code and key.
+- A resumed `run()` still waits for execution completion. A resumed `execute()`
+  only completes submission, just like the original method.
+- Recovery starts a fresh timeout and cancellation scope. The previous aborted
+  signal and deadline are discarded. Metadata and polling interval are retained
+  unless overridden. A further transient failure carries another resumable error.
+
+`SandboxOperationError`, `TemplateOperationError`, and `ExecutionOperationError`
+all extend `OperationError<T>` and `TarkaError`. Each provides `code`, `recovery`,
+and `resume(options?)`, returning the original operation's entity type.
+Recovery details include the operation, organization, available resource IDs,
+and idempotency key. Code, stdin, and manifests are kept privately for replay;
+they are not included in `recovery` or serialized error fields.
+
+Keys are generated automatically for sandbox/template creation and execution.
+You can supply your own `idempotencyKey` for durable application workflows.
+The API contract guarantees deduplication for **24 hours**, with unchanged
+request content. Resume within that window; replay after it can create a new
+resource or execution. The SDK does not automatically retry mutations or resume
+partially consumed inference streams.
+
+An error's `resume()` lives in memory. Across process restarts, save your chosen
+key and original input for unacknowledged mutations, or save IDs and reattach:
+
+```js
+const sandbox = await client.org(orgId).sandboxes.get(sandboxId);
+const execution = await sandbox.executions.get(executionId);
+await execution.wait({ timeoutMs: 60_000 });
+```
+
+Aborting a wait stops polling; it does not delete the sandbox or necessarily
+stop submitted code. Keep the sandbox available while recovering, then delete
+it when finished. Other provisioning mutations lack this idempotency contract:
+after a timeout, inspect their state before deciding whether to retry.
+
+## Streaming, cancellation, and errors
+
+```js
+import { TarkaError } from "@tarkahq/sdk";
+
+const controller = new AbortController();
+try {
+  for await (const text of client.chat.streamText(
+    { model, prompt: "Write a short sentence." },
+    {
+      timeoutMs: 60_000,
+      signal: controller.signal,
+      metadata: { "x-request-id": "my-request" },
+    },
+  )) {
+    process.stdout.write(text);
+  }
+} catch (error) {
+  if (error instanceof TarkaError && error.code === "deadline_exceeded") {
+    console.error("The request timed out");
+  } else {
+    throw error;
+  }
+}
+```
+
+Streams start on iteration and preserve Node stream backpressure. Calling
+`controller.abort()` cancels the active RPC; breaking out of `for await` also
+cancels it. Metadata accepts strings, Buffers, and arrays of those values;
+binary keys must end in `-bin`.
+
+Resource methods normalize transport failures to `TarkaError`, with a readable
+`message`, string `code`, plain trailing `metadata`, and the original error as
+`cause`. Typical codes include `deadline_exceeded`, `cancelled`, `unavailable`,
+`unauthenticated`, `permission_denied`, `not_found`, and `invalid_argument`.
+Local argument validation throws `TypeError`. Native gRPC error objects and
+numeric status codes are available only through `client.grpc` calls.
+
+## Values and serialization
+
+Public fields use camelCase, except opaque OpenAI JSON bodies. Bytes are Node
+`Buffer`s, timestamps are `Date`s, and 64-bit integers are `bigint`s to preserve
+precision. Use bigint literals for input limits, such as `1_000_000n`. Optional
+values remain `undefined`; explicit zero and false are preserved.
+
+Sandbox `JSON.stringify(handle)` serializes its latest snapshot. For other
+entities containing bigints, choose a JSON representation explicitly:
+
+```js
+const json = JSON.stringify(usage, (_key, value) =>
+  typeof value === "bigint" ? value.toString() : value,
+);
+```
+
+## Advanced gRPC access
+
+Normal application code needs only `@tarkahq/sdk`. Every underlying RPC remains
+available through `client.grpc`, with generated envelopes, enums, and native
+call options and errors:
+
+```js
+const response = await client.grpc.inference.listModels();
+await client.grpc.provisioning.getCurrentUser({ timeoutMs: 10_000 });
+await client.grpc.sandboxes.listSandboxes({ orgId });
+```
+
+Transport utilities and generated codecs are isolated in these exports:
+
+```js
+import {
+  Channel,
+  credentials,
+  status,
+  createChannel,
+  createServiceClient,
+} from "@tarkahq/sdk/grpc";
+import {
+  ChatCompletionRequest,
+  InferenceServiceDefinition,
+} from "@tarkahq/sdk/grpc/inference/v1";
+import { UsageSummary } from "@tarkahq/sdk/grpc/provisioning/v1";
+import { ExecuteRequest } from "@tarkahq/sdk/grpc/sandboxes/v1";
+```
+
+`@tarkahq/sdk/grpc` also exports `inference`, `provisioning`, and `sandboxes`
+codec namespaces. Codecs offer `create`, `fromPartial`, `encode`, `decode`,
+`fromJSON`, and `toJSON`. Raw enums are numeric and raw oneofs use
+`{ $case, value }`. Native call options support absolute `deadline`, gRPC
+`Metadata`, credentials, and interceptors in addition to SDK request settings.
+The earlier deadline wins when both `deadline` and `timeoutMs` are given.
+
+Use `channelCredentials: credentials.createSsl(ca)` for custom TLS roots,
+`target` for a different endpoint, and `channelOptions` for gRPC configuration.
+The authenticated `createChannel(accessToken, options)` helper requires TLS.
+Alternatively, supply a channel whose authentication and lifecycle you own:
+
+```js
+const channel = new Channel(
+  "localhost:50051",
+  credentials.createInsecure(),
+  {},
+);
+const local = new TarkaClient({ channel, timeoutMs: 10_000 });
+try {
+  await local.models.list();
+} finally {
+  channel.close();
+}
+```
+
+An injected channel cannot be combined with `accessToken`, `target`, or channel
+configuration. `client.close()` leaves caller-owned channels open.
+
+## Migrating from 0.1
+
+Version 0.2 deliberately makes resource wrappers the default API.
+
+| Before                                                  | Now                                                                             |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `client.inference.listModels()`                         | `client.models.list()`; returns the array                                       |
+| `client.provisioning.getCurrentUser()`                  | `client.user.get()`                                                             |
+| `client.provisioning.createApiKey({ orgId, ...input })` | `client.org(orgId).apiKeys.create(input)`; secret is `.secret`                  |
+| `client.sandboxes.forOrg(orgId)`                        | `client.org(orgId).sandboxes`                                                   |
+| `sandbox.getExecution(id)`                              | `sandbox.executions.get(id)`; returns an `Execution` handle                     |
+| `sandbox.run(code, { timeoutMs, timeoutSeconds })`      | `sandbox.run(code, { timeoutSeconds }, { timeoutMs })`                          |
+| Numeric sandbox/execution statuses                      | String statuses, such as `"ready"` and `"succeeded"`                            |
+| Sandbox lists returning plain snapshots                 | Lists of `Sandbox` handles; use `.info` for snapshots                           |
+| `SandboxStateError` / `ExecutionStateError`             | `ResourceStateError`, with `.resource` and `.info`                              |
+| Native SDK errors with numeric codes                    | `TarkaError` with string codes; resumable operation errors for sandbox recovery |
+| Direct services / `client.channel`                      | `client.grpc.inference`, `.provisioning`, `.sandboxes`, `.channel`              |
+| Transport imports from package root                     | Imports from `@tarkahq/sdk/grpc`                                                |
+| `@tarkahq/sdk/inference/v2` (and other codec paths)     | `@tarkahq/sdk/grpc/inference/v1` (and corresponding service paths)              |
+
+Raw RPC signatures remain available under `grpc`, including optional empty
+requests and the older `rpc({}, options)` form.
+
+## Development and generation
+
+Building and testing need only this repository. Regeneration also needs the
+authoritative API checkout, normally at `../api`, at the revision recorded in
+`api-source.json`:
+
+```sh
+npm ci
+npm run generate                        # Uses ../api
+npm run generate -- --api-dir /path/to/api
+npm run check:generated                 # Compares without modifying files
+npm run verify                         # Format, types, tests, build, package test
+```
+
+`scripts/generate.mjs` discovers every `.proto` under `api/proto/tarka` and runs
+the pinned `protoc` from `grpc-tools` with the pinned `ts-proto` plugin. Annotation
+imports live in `proto/third_party`; well-known types come from `grpc-tools`.
+There is no global compiler requirement or runtime code generation.
+
+Generated TypeScript is checked in under `src/generated`; do not edit it by
+hand. `api-source.json` records the API commit, source/import hashes, and
+generator settings. Generation does not fetch or change the API checkout.
+When the contract adds an RPC, add its resource wrapper: the coverage test
+asserts that every generated RPC is exercised through the public resource API.
+
+CI checks generation against the recorded revision and verifies Node 22 and 24.
+Tests use local gRPC servers, including TLS/authentication, streaming,
+cancellation, all 60 wrapped RPCs, and recovery after lost acknowledgements.
+They do not require Tarka credentials or call production. The package test
+installs a tarball into an isolated consumer, checks TypeScript types, and runs
+ESM and CommonJS consumers. That test needs npm registry access for dependencies.
+
+## Preparing an npm release
+
+1. Confirm the package name and access to the `@tarkahq` scope.
+2. Select the API revision, regenerate, and review generated and wrapper changes.
+3. Set the version in `package.json` and `package-lock.json`.
+4. Run `npm run check:generated`, `npm run verify`, and `npm pack --dry-run`.
+5. Run the `SDK release` workflow on `main` with `publish=true` after reviewing its package artifact.
+
+There is no automatic publication workflow.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+
+## Gateway connection settings
+
+Gateway create, update, get and list responses expose `endpoints` when routing
+is configured. `apiBaseUrl` accepts published operation paths;
+`apiAudience` is the exact OAuth resource without `/api`. `mcpUrl` and
+`mcpAudience` are the same MCP endpoint. `issuer` identifies the environment's
+OAuth issuer. Use these server-provided settings instead of constructing URLs.
+They are available for setup before publication and do not grant access.
+
+`client.gateway.listPrivateServices()` lists controller-observed services for an
+organization and realm. Set a target's `serviceId` and `servicePath` instead of
+`url` for a private destination. Only a `ready` service can be published; a
+redeployment requires a new gateway publication. Its exact credential scope is
+`tarka-service://<service-id>` in `allowedOrigins`.
+
+## Trusted agent harness
+
+Use `RuntimeClient` in trusted server-side harness code. The token provider must
+supply a current OAuth token with `runtime.execute` for the realm's exact runtime
+resource. The server derives the customer, agent and consent; platform API keys
+cannot establish that identity.
+
+```ts
+import { RuntimeClient } from "@tarkahq/sdk";
+
+const runtime = new RuntimeClient({
+  origin: gatewayOrigin,
+  realmId,
+  tokenProvider: currentRuntimeOAuthToken,
+});
+await runtime.withRun(
+  {
+    gateway_id: gatewayId,
+    transport: "api",
+    permissions: [{ resource: capabilityId, action: "invoke" }],
+  },
+  async (run) => {
+    const response = await run.api("/records");
+    const toolResult = await response.json();
+    // Pass only the approved result to the model.
+  },
+);
+```
+
+For MCP, start with `transport: "mcp"` and pass `run.mcpFetch` as the MCP
+Streamable HTTP transport's fetch implementation, using `run.audience` as its
+endpoint. It rejects every other URL and supplies only the narrow run bearer.
+
+Keep the client, run handle and parent token provider outside model-visible
+state, prompts, tool arguments, workspace files and logs. Register specific tool
+closures. Metadata, JSON serialization and normal inspection omit credentials.
+The SDK does not isolate hostile code in its own process.
+
+The harness serializes renewal and renews near expiry on demand. An uncertain
+renewal disables later tool calls; issuance and tool actions are never retried
+automatically. `withRun` completes on success and attempts cancellation if the
+callback fails, preserving the callback's error. `finish()` explicitly stops a
+run. Read streamed responses promptly: rotating a credential while an earlier
+stream remains open may cause that stream's authorization check to terminate it.
+
+### Independent messaging consumers
+
+An assigned agent worker uses its autonomous Ory token for the runtime audience
+after the customer links a provider account and approves the channel's tools.
+Both customer and agent need channel `use` permission. Identity and tool scope
+come from the gateway.
+
+```ts
+for await (const message of runtime.messages(channelId, { signal })) {
+  // Give only prompt to the model as user input. Build tool closures around
+  // message.api(...) or message.mcpFetch inside trusted harness code.
+  const result = await executeAgentTurn(message.prompt, message);
+  await message.reply(result);
+}
+```
+
+`claimMessage(channelId)` returns one message or `null`. The iterator polls
+successfully empty queues every five seconds and cancels an unfinished run on
+advance or exit. A private `reply()` finishes the run, accepts at most 2,000
+Unicode characters and has no recipient argument. Failed or uncertain claims
+and replies propagate without retry. Keep the message handle outside model
+state; inspection and JSON serialization omit its prompt and credentials.
+
+## Publishing
+
+The `SDK release` workflow runs verification, creates the npm tarball and a
+SHA-256 checksum, and uploads them as a reviewable artifact. A dry run is the
+default. Publishing runs only on `main` with `publish=true`, uses the exact tested
+tarball, and attaches it to a GitHub release.
+
+Configure npm's trusted publisher for `@tarkahq/sdk`, owner `TarkaHQ`, repository
+`sdk-javascript`, workflow `release.yml`, environment `npm`, and the publish
+permission. The package owner must establish the package and publisher identity
+before the first automated release. The workflow uses a GitHub-hosted runner and
+OIDC, with no stored npm token. npm does not generate provenance from a private
+source repository. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).