​

SDKs and the control-plane API

The Kheish daemon is the durable orchestration engine. The SDKs are a thin integration layer over its HTTP control plane. Nothing an SDK does is magic — every call maps to a documented /v1/... endpoint, and everything an SDK “remembers” is actually durable state inside the daemon.

​

Environment conventions

• KHEISH_BASE_URL — the daemon control-plane URL. Defaults to http://127.0.0.1:4000.
• KHEISH_TOKEN — the bearer token. Optional: only needed when the daemon has control-plane auth enabled (which it should for anything non-loopback).

export KHEISH_BASE_URL="https://kheish.internal.example.com"
export KHEISH_TOKEN="…admin-or-readonly bearer token…"

​

The four SDKs

​

Python — kheish-sdk

pip install kheish-sdk

from kheish import Kheish, Route

with Kheish.from_env() as client:
    run = client.responses.create(
        session="demo",
        prompt="Reply with one sentence about why typed SDKs help integrators.",
        route=Route.openai("gpt-5.4"),
    )
    result = run.wait(raise_on_failure=True)
    print(result.output_text)

• client.responses — high-level prompt/files/assets/boards facade
• client.sessions — durable session lifecycle, persona defaults, route policy, reply targets
• client.runs — run inspection, debug bundles, cancellation
• client.approvals and client.questions — the explicit human-loop control plane
• client.tasks — daemon task inspection and stop controls
• client.assets — upload, download, save
• client.personas — create, update, inspect
• client.schedules — create, trigger, pause, resume, cancel
• client.agents and client.mailboxes — sidechains, mailbox posting, nickname management
• client.runtime, client.secrets, client.auth_accounts, client.connectors — runtime admin
• client.playbooks and client.flows — playbook lifecycle and flow execution
• client.learning and client.capture — daemon learning state and capture provisioning
• client.channels, client.projects, client.boards — collaborative control-plane resources
• client.observations and client.derivations — durable input pipelines
• client.events and client.raw — global event stream and escape hatch
• ExternalDaemonClient — for Python sidecars using the external connector ingress contract

​

TypeScript — @kheish/sdk

npm install @kheish/sdk

import { Kheish, Route } from "@kheish/sdk";

const client = Kheish.fromEnv();

const run = await client.responses.create({
  session: "demo",
  prompt: "Reply with one sentence about typed SDKs.",
  route: Route.openai("gpt-5.4")
});

const result = await run.wait({ raiseOnFailure: true });
console.log(result.output_text);

​

Go

go get github.com/kheish/kheish-sdks/go

package main

import (
	"context"
	"fmt"

	kheish "github.com/kheish/kheish-sdks/go"
)

func main() {
	client := kheish.NewFromEnv()
	health, err := client.Healthz(context.Background())
	if err != nil {
		panic(err)
	}
	fmt.Println(health)

	session, err := client.Sessions().Create(
		context.Background(),
		kheish.NewSession("demo").
			ThreadID("demo").
			Capability(kheish.NewCapabilityScope().AllowSkill("documents")).
			Credential(kheish.NewCredentialScope().AllowRoute("openai")),
	)
	if err != nil {
		panic(err)
	}
	fmt.Println(session)

	run, err := client.Sessions().SubmitRun(
		context.Background(),
		"demo",
		kheish.NewRunInput("Hello from Go.").
			Idempotency("demo-1").
			Route("openai").
			Source("sdk", "go", "readme").
			AddInputItem(kheish.TextInput("Keep the answer concise.")).
			WithGeneration(kheish.NewGeneration().WithModel("gpt-5.4").TemperatureValue(0.2)),
	)
	if err != nil {
		panic(err)
	}
	fmt.Println(run)
}

​

Rust

[dependencies]
kheish = { path = "../rust" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

use kheish::{
    CapabilityScope, Client, CreateSessionRequest, CredentialScope, GenerationConfig,
    SubmitInputItem, SubmitRunRequest,
};

#[tokio::main]
async fn main() -> kheish::Result<()> {
    let client = Client::from_env();
    let health = client.healthz().await?;
    println!("{health}");

    let session = client
        .sessions()
        .create(
            CreateSessionRequest::new("demo")
                .thread_id("demo")
                .capability_scope(CapabilityScope::new().allow_skill("documents"))
                .credential_scope(CredentialScope::new().allow_route("openai")),
        )
        .await?;
    println!("session: {session}");

    let run = client
        .sessions()
        .submit_run(
            "demo",
            SubmitRunRequest::new("Hello from Rust.")
                .idempotency_key("demo-1")
                .route("openai")
                .source("sdk", "rust", "readme")
                .input_item(SubmitInputItem::text("Keep the answer concise."))
                .generation(GenerationConfig::new().model("gpt-5.4").temperature(0.2)),
        )
        .await?;
    println!("run: {run}");
    Ok(())
}

kheish = { path = "../rust", features = ["blocking"] }

fn main() -> kheish::Result<()> {
    let client = kheish::blocking::Client::from_env();
    println!("{}", client.healthz()?);
    println!("{}", client.sessions().create(kheish::CreateSessionRequest::new("demo"))?);
    Ok(())
}

​

Choosing an SDK

​

The fire-and-wait pattern

from kheish import Kheish, Route

with Kheish.from_env() as client:
    run = client.responses.create(
        session="demo",
        prompt="Reply with one sentence about why typed SDKs help integrators.",
        route=Route.openai("gpt-5.4"),
    )
    result = run.wait(raise_on_failure=True)
    print(result.output_text)

• A route — Route.openai("gpt-5.4") etc. If you omit it you get the daemon’s default route, which is fine for demos but surprising in production when an operator changes the daemon default.
• An idempotency key, especially in a service that retries. The Go/Rust submit path takes one directly (Idempotency("…") / .idempotency_key("…")); the daemon uses it to collapse duplicate submissions instead of running twice.

​

The session-first pattern

from kheish import Kheish, ReplyTarget, Route

with Kheish.from_env() as client:
    persona = client.personas.create(
        {
            "display_name": "Support FR",
            "soul": "Reply in French, keep answers concise, and be operational.",
        }
    )
    session = client.sessions.create(
        "support-ticket-42",
        persona=persona.persona_id,
        route=Route.openai("gpt-5.4"),
        reply_targets=[ReplyTarget.raw("sdk", "stdout")],
    )
    run = session.responses.create(
        prompt="Réponds au ticket en 3 phrases maximum."
    )
    print(run.wait(raise_on_failure=True).output_text)

• Personas are snapshotted at bind time. The session captures the persona as it was when bound. Updating the persona record later does not retroactively change an already-bound session. This is deliberate — it keeps a long-running session stable — but it means “I updated the persona and nothing changed” is expected, not a bug. Rebinding a persona is a session mutation and only allowed while the session is idle (a rebind on a busy session returns 409).
• Route policy persists. The session’s route becomes the default for its runs, so you set it once instead of on every call.
• Reply targets persist. Set the session’s reply-target defaults once and every run’s output routes there (see webhooks). Reply-target edits are prospective — a run snapshots its reply targets at submission, so changing the session default does not re-route an in-flight run.
• Capability and credential scopes live on the session. The Go/Rust quickstarts show AllowSkill(...) / allow_route(...) — these narrow what the session’s runs can reach, fail-closed.

​

Human in the loop

from kheish import Kheish

with Kheish.from_env() as client:
    run = client.responses.create(
        session="ops-demo",
        prompt="Ask questions if context is missing, and request approval before risky actions.",
    )
    blocked = run.wait_until_blocked(timeout=120)

    if blocked.requires_approval:
        blocked.approve_all("approved by operator")

    if blocked.requires_question:
        answers = {}
        for question in blocked.get().pending_questions[0].questions:
            if question.options:
                answers[question.id] = [question.options[0].id]
            else:
                answers[question.id] = "No extra input from the operator."
        blocked.answer(answers)

    print(run.wait(raise_on_failure=True).output_text)

• Questions can be multiple-choice or free-text. The loop above answers option-bearing questions with an option id list and free-text questions with a string. Real integrations surface these to a human UI instead of auto-answering.
• Approvals and questions are durable. They survive a daemon restart — the run stays in waiting_for_approval / waiting_for_user_question and resumes when you resolve it. Your integration can crash and reconnect and the pending work is still there.
• A shell-heavy run may need more than one approval wave. Do not assume a single approve_all unblocks everything; loop until the run reaches a terminal status.
• Timeouts are yours to own. wait_until_blocked(timeout=…) bounds how long you wait for the run to reach a blocked-or-terminal state; it does not put a deadline on the human.

​

The run wait/poll lifecycle

• queued — submitted, waiting for a slot
• running — executing
• waiting_for_approval — paused on a pending approval
• waiting_for_user_question — paused on a pending structured question
• completed — finished successfully; outputs populated
• failed — finished with an error string
• interrupted — interrupted (for example, a normal input run displaced during restart repair, or an explicit sessions interrupt)
• cancelled — cancelled via runs cancel

• The lifecycle only moves forward. Normal execution goes queued → running, then running → one of the waiting or terminal states, and waiting runs resume to running or settle terminally. running → queued is reserved for daemon restart recovery of replayable daemon-owned work. An ordinary API mutation that tries to rewind lifecycle state returns 409 application/problem+json with domain runs and code run_state_conflict. Do not try to force a run backwards.
• GET /v1/runs/{run_id} is the source of truth for the route and model actually used. RunView.request (a compact RunRequestSummary) exposes the resolved provider (route selector) and model. Do not infer the model from what you requested; read what the run used.
• One session runs one thing at a time. Submitting /input while a run is active or queued returns 409 with domain sessions, code session_busy. Use the detached /runs submission (what Go/Rust SubmitRun does) when you want work to queue behind existing work instead of being rejected.

​

Poll vs. stream

   POLL:   loop { GET /v1/runs/{id}; sleep; } until terminal
           simple, stateless, fine for short runs and batch jobs.

   STREAM: GET /v1/runs/{id}/stream  (Server-Sent Events)
           live events: started, output, waiting_for_*, completed, failed…
           reconnect with Last-Event-ID or ?cursor=<event_id>.

• Data events carry monotone decimal-string ids. Typed heartbeat keepalives are id-less and do not advance the reconnect cursor — do not treat a heartbeat as progress.
• Reconnect with Last-Event-ID or ?cursor=<event_id>; if both are present the larger numeric cursor wins.
• The daemon emits typed stream_gap notices when your cursor is older than the bounded replay window, predates the current event-id epoch after a restart, or you fell behind as a slow consumer. Gap payloads carry skipped, reason, scope, skipped_is_estimate, and an optional resume_after_id. Handle gaps by reconciling with a GET list/get rather than assuming you saw every event.
• The CLI streaming commands abort if one SSE frame exceeds 1 MiB; use list/get endpoints for bulk output reconciliation.

​

Structured input and output contracts

PUT /v1/sessions/{id}/input-contract    { "schema": { …JSON Schema… } }
PUT /v1/sessions/{id}/output-contract   { "schema": { …JSON Schema… },
                                          "max_repair_attempts": N }

​

Setting a contract

# input contract: the daemon rejects any run whose payload does not match
curl -X PUT http://127.0.0.1:4000/v1/sessions/orders/input-contract \
  -H "Authorization: Bearer $KHEISH_TOKEN" -H "Content-Type: application/json" \
  -d '{"schema":{"type":"object","properties":{"order_id":{"type":"string"},"amount":{"type":"number"}},"required":["order_id","amount"]}}'

# output contract: the daemon coerces the model output toward this shape,
# retrying repair up to max_repair_attempts
curl -X PUT http://127.0.0.1:4000/v1/sessions/orders/output-contract \
  -H "Authorization: Bearer $KHEISH_TOKEN" -H "Content-Type: application/json" \
  -d '{"schema":{"type":"object","properties":{"status":{"type":"string"},"note":{"type":"string"}},"required":["status"]},"max_repair_attempts":2}'

​

Running against a contract

​

Webhooks as reply targets

• session_id and thread_id
• content — the plain-text fallback
• parts — the structured output parts (text, attachment, …)
• resolved_parts — parts with attachments resolved
• artifacts and artifact_attachments — daemon-owned artifact references emitted with the output
• metadata

from kheish import Kheish, ReplyTarget

with Kheish.from_env() as client:
    client.sessions.set_reply_targets(
        "orders",
        reply_targets=[ReplyTarget.http("https://your-app.example.com/kheish-webhook",
                                        headers={"x-source": "kheish"})],
    )

• Delivery is durable and retried. A reply target that returns 429 is retried with backoff (the daemon honours Retry-After). Repeated failure dead-letters the delivery, which you can inspect and replay (GET /v1/deliveries/dead-letter, POST /v1/deliveries/{id}/replay).
• Reply targets snapshot at run/task creation. Editing the session default is prospective — an already-submitted run keeps the targets it captured. So a webhook change does not retroactively re-route in-flight work.
• Operator delivery views are redacted. GET /v1/deliveries exposes the plugin, a target digest, attempts, safe error codes, timestamps, counts, and the run_id — but not raw reply addresses or payload metadata. Your webhook URL does not leak through the operator delivery API.

​

Assets and multimodal input

• Inline — embed the bytes in the run payload as an inline_asset item (or a legacy attachments entry). The daemon materializes an asset from it. Inline assets require both a non-empty file_name and non-empty content_base64.
• Reference — upload the asset once via POST /v1/assets, get an asset_id, and reference it from many runs with an asset_reference item. Upload once, reuse many times.

   UPLOAD ONCE:
   POST /v1/assets  { file_name, media_type, content_base64 }  ->  { asset_id }

   REFERENCE FROM A RUN (preferred, provider-neutral input_items):
   input_items: [
     { type: "text",            text: "Summarize the attached spec." },
     { type: "asset_reference", asset_id: "asset-123" },
     { type: "inline_asset",    file_name: "note.txt",
                                media_type: "text/plain",
                                content_base64: "…" },
     { type: "board_reference", board_id: "board-1", revision_id: "rev-1" }
   ]

   READ OUTPUT ARTIFACTS BACK:
   run output -> parts / artifacts (asset ids) -> GET /v1/assets/{id}/raw (admin)

​

Scheduling recurring work

curl -X POST http://127.0.0.1:4000/v1/schedules \
  -H "Authorization: Bearer $KHEISH_TOKEN" -H "Content-Type: application/json" \
  -d '{
        "session_id": "daily-digest",
        "recurrence": { "type": "cron", "expression": "0 8 * * *", "timezone": "UTC" },
        "payload": { "type": "request", "request": { "content": "Produce the daily digest." } }
      }'

• request — a full session input request fired at each occurrence.
• observation_materialization — materialize captured observations on a cadence.
• flow_start — start a referenced Playbook Flow at each fire; the daemon records the root run as scheduled work.

• Cron timezone defaults to UTC. Set it explicitly if you mean local time.
• Recurring flow_start schedules derive a unique flow_id and idempotency_key per fire. Explicit identifiers are only accepted on one-shot schedules; a one-shot with neither derives both, and supplying one preserves it without synthesizing the other.
• When a nested schedule request uses only input_items, content can be omitted.

​

Idempotency, retries, and duplicate submissions

• Python/TypeScript responses.create accepts an idempotency key; Go’s NewRunInput(...).Idempotency("order-8842") and Rust’s SubmitRunRequest::new(...).idempotency_key("order-8842") set it explicitly.
• Derive the key from something stable in your domain — an order id, a message id, a webhook delivery id — not from a random value, or retries will not collapse.
• Idempotency composes with the run state machine: a retry that lands after the original completed returns the completed run, so your wait sees the real result rather than starting a duplicate.

​

Sidechains, agents, and mailboxes

• Agents / sidechains (client.agents) let a run spawn a bounded child agent for a sub-task and get a structured result back — a reviewer, a researcher, a checker — without the parent losing its own context. Spawns are bounded by a daemon-owned spawn-policy quota (recorded in spawn-policy-ledger.json), so a runaway fan-out cannot exhaust the daemon.
• Mailboxes (client.mailboxes) are how sessions post messages to each other and manage nicknames. A mailbox post is accepted (202) and delivered as a mailbox_delivery run in the target session.
• Channels and projects (client.channels, client.projects) are the collaborative surfaces: public conversations with turn leases and thread-work, and daemon-owned projects with members, linked channels, and project tasks.

​

Bridging an external connector sidecar

• The ingress routes (POST /v1/connectors/external/{name}/events and /events/batch) sit outside the control-plane auth middleware — they are authenticated by the connector’s own shared_token, not the admin token. If no shared token is configured, allow_unauthenticated_ingress=true must be explicit.
• A connector that creates sessions dynamically must opt in with session_policy={"create_if_missing": true} in its runtime connector config; otherwise it can only route to existing sessions.
• The bundled Python sidecar helpers submit ingress protocol_version = 2 by default and fall back to 1 when talking to an older daemon, so you do not hand-manage the protocol version.
• remote_http external connectors reject loopback, private, link-local, and metadata-network targets by default (SSRF hardening); set allow_private_network=true only for trusted local sidecars, and note the daemon never follows redirects and re-validates resolved addresses on every fetch.

​

A guided tour of the control-plane API

• sessions — durable containers: create, input, route policy, capability/credential scope, reply targets, persona binding, input/output contracts, memory context/search
• runs — execution attempts: list, get (source of truth for route+model used), cancel, debug bundles, external actions
• questions & approvals — the human-loop control plane
• tasks — background daemon tasks: list, output, stop
• schedules — durable schedules + wakeups: create, trigger, pause, resume, cancel
• learnings & memory — learning-candidates, learnings, revoke-matching, learning-skills (promoted procedural skills)
• runtime — /v1/status, /v1/capabilities, /v1/runtime, learning-policy, secrets, auth subjects/leases, hooks, debug-level, connectors/external/metrics, routes overlay
• connectors — runtime connectors + ingress definitions (http/slack/telegram/external)
• assets — daemon-owned assets and documents (upload/download/raw)
• boards — immutable visual revisions
• personas — persona records + session persona binding
• channels — public conversations, members, messages, leases, stimuli, thread-work
• projects — projects, members, linked channels, project tasks
• playbooks & flows — playbook lifecycle + Flow execution/streaming
• observations & derivations — observation sources, observations, materializations and durable derivations
• docs — GET /v1/docs — the daemon’s own documentation manifest
• logs — GET /v1/logs — bounded ring of daemon tracing events
• streams — SSE: events, sessions/, runs/, flows/

• connector ingress — /v1/connectors/{http,slack,telegram}/{name}, /v1/connectors/external/{name}/events[/batch], /v1/connectors/external/{name}/credentials/{key}
• observation upload — /v1/observation-sources/{id}/observations (source-scoped bearer token, not the admin token)

• Sessions and runs — the core. Create sessions, submit input or detached runs, inspect run status/route/model, fetch debug bundles, read the derived memory-context view. Reference: Sessions and runs API.
• Schedules — recurring or one-shot work: request, observation_materialization, or flow_start payloads. Recurring schedules derive a per-fire id and idempotency key. Reference: Tasks, schedules, and agents API.
• Learnings and memory — the daemon’s durable learning store and promoted procedural skills, plus the automatic learning policy. Reference: Learnings API.
• Runtime — the operator surface: status, capabilities, route/model, secrets, brokered auth subjects/leases, hooks, debug level. Reference: Runtime API.
• Connectors — transports the daemon owns and the ingress the daemon accepts. Reference: Connectors API.
• Assets — the daemon-owned asset model behind attachments and outputs. Reference: Assets API.
• Docs and logs — GET /v1/docs returns the daemon’s documentation manifest; GET /v1/logs?limit=N returns the bounded ring buffer of daemon tracing events (default 1,000, ring capacity 5,000) that powers the Kheish Air logs explorer.

​

Status codes you will actually handle

​

Use via SDK in Kheish Air

• The right install line and env vars for the chosen language (pip install kheish-sdk, npm install @kheish/sdk, go get github.com/kheish/kheish-sdks/go, cargo add kheish), with KHEISH_BASE_URL prefilled from your console connection settings and a reminder that KHEISH_TOKEN is only needed when the daemon requires auth.
• The idiomatic call for that language — Python/TypeScript use responses.create + wait, Go and Rust use the session-first SubmitRun path with an idempotency key — all targeting the exact session you clicked from.
• Contract-aware payloads. If the session enforces a structured input contract, the snippet includes a payload skeleton derived from the schema (numbers become 1, booleans true, strings "<field>", arrays [], nested objects recurse) plus a comment warning that the payload must match the schema or the daemon rejects the run. If there is no contract, it sends a plain example prompt.

​

FAQ

​

Related reading

• Running Kheish in production — the operator side of the same daemon: state root, backups, upgrades, observability.
• Sessions and runs — the execution model your calls drive.
• Architecture — how the daemon, SDKs, and connectors fit together.
• Security — trust zones, tokens, and CORS boundaries.
• Quickstart — from zero to a first run.
• Reference: Control plane API, Sessions and runs API, Runtime API, Questions and approvals API, Connectors API, Learnings API, Tasks, schedules, and agents API, Assets API.