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 same runtime in place
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() preserves the session's established sandbox identity and refreshes the handle's cached readiness state. If the original provider object is unavailable, restart fails explicitly instead of attaching an empty replacement. delete() removes the runtime; stop() clears readiness 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);