Sessions

A session is one agent run, in its own disposable sandbox, on its own git branch. kortix.session(projectId, sessionId) binds both ids and is the single handle for everything a session does.

const s = kortix.session(projectId, sessionId);

Lifecycle

await s.get();                 // session detail
await s.update({ /* … */ });   // rename, settings
await s.start();               // provision + boot the runtime
await s.restart();             // restart the runtime (may re-provision a new sandbox)
await s.stop();                // stop the runtime without deleting the session
await s.commit();              // commit the agent's work
await s.setSharing(intent);    // sharing / visibility
await s.delete();

restart() and delete() both forget this handle's cached runtime (a restart may land on a different sandbox); stop() does the same without deleting the session itself.

Previews & public shares

await s.previews();            // candidate preview ports the runtime exposes
await s.publicShares.list();
await s.publicShares.create(input);
await s.publicShares.revoke(shareId);

Audit & transcript

await s.audit(limit?);         // per-session audit trail of executor-gated agent actions
await s.transcript(options?);  // compact server-side transcript (text + tool calls, no tool inputs/outputs)

transcript() is callable with project-scoped session tokens, so it's the right read for a scoped/embedded host that only has a session token.

The runtime

The session owns its runtime, so these resolve the active sandbox for you — you pass a port or a URL, never a sandbox id.

const { ok, health } = await s.health();
// health?.runtimeReady · health?.status · health?.version …

const url = s.previewUrl(3000, '/docs');       // → the live preview URL
const fixed = s.proxyUrl('http://localhost:8080');

s.health() never throws SessionNotReadyError — it's safe to poll before the session has ever resolved a runtime. s.previewUrl() and s.proxyUrl() do require a resolved runtime; call s.ensureReady() first (or s.send() / s.abort(), which call it internally).

Talking to the agent

These are the opinionated wrappers over the runtime — the right entry points for a script, server, worker, or any non-React host. Each auto-provisions the runtime via ensureReady() internally, resolves the OpenCode session id for you, and always acts against this handle's own resolved runtime — never whatever sandbox happens to be globally "active" — so two handles on two different sessions never cross wires.

await s.ensureReady();                 // provision/resume the runtime; idempotent
s.setModel({ providerID, modelID });   // sticky model for subsequent send()s
s.setAgent('build');                   // sticky agent for subsequent send()s

await s.send('Refactor the auth module');           // prompt the agent
await s.send('One-off task', { model, agent });     // per-call override
await s.abort();                                     // abort the current run

Call s.ensureReady() (or send/abort, which call it internally) before .runtime, .previewUrl(), or .proxyUrl() — those throw SessionNotReadyError if this handle hasn't resolved a runtime yet. .health() is the exception: it never throws and is safe to call anytime.

Streaming events — s.stream()

For live message / part / event streaming from a non-React host, use s.stream() — a framework-free facade over the same primitive useSession uses internally. It handles connect/reconnect/backoff and a 15s heartbeat watchdog.

const handle = await s.stream({
  onEvent: (event) => console.log(event),
  onGapRehydrate: (gapMs) => console.log('reconnected, gap:', gapMs),
});
// later
handle.close();

In a React app, prefer useSession(projectId, sessionId) instead — the hook that owns the whole runtime (start, SSE, readiness) and returns the thread, send, and the boot phase.

The typed runtime — s.runtime

s.runtime is the typed OpenCode v2 client, scoped to this session and reached only through the SDK — the escape hatch for anything not covered by send/abort/stream. It requires a resolved runtime (call s.ensureReady() first, or use it after send/abort/stream have run).

await s.ensureReady();

// send a prompt (equivalent to s.send(), shown for the raw client)
await s.runtime.session.prompt({
  sessionID: (await s.ensureReady()).opencodeSessionId,
  parts: [{ type: 'text', text: 'Refactor the auth module' }],
});

Files — s.files

s.files is the session-scoped equivalent of the top-level @kortix/sdk files export: the same 12-op workspace surface, but every call auto-provisions via ensureReady() and always targets this handle's own resolved runtime — never the module-global "active" sandbox. This fixes a cross-session bleed bug: a host juggling multiple open sessions that called the global files.list() could silently read/write the wrong sandbox.

await s.files.list(dirPath);
await s.files.read(filePath);
await s.files.readBlob(filePath);
await s.files.status();
await s.files.findFiles(query, { type: 'file', limit });
await s.files.findText(pattern);
await s.files.upload(file, targetPath?, filename?);
await s.files.create(filePath);
await s.files.copy(sourcePath, destPath);
await s.files.remove(filePath);
await s.files.mkdir(dirPath);
await s.files.rename(from, to);