@roj-ai/sdk 0.1.36 → 0.2.1

package/src/platform/fs.ts

@@ -10,6 +10,18 @@ import type { FileHandle } from 'node:fs/promises'
 
 export type { Dirent, FileHandle, Stats }
 
+/**
+ * Positional-read handle — the subset of `node:fs/promises` FileHandle the SDK uses.
+ *
+ * Narrower than `FileHandle` so a platform exposing only raw fds can implement it.
+ * `FileHandle` satisfies it.
+ */
+export interface ReadableFileHandle {
+	stat(): Promise<Stats>
+	read(buffer: Buffer, offset: number, length: number, position: number): Promise<{ bytesRead: number; buffer: Buffer }>
+	close(): Promise<void>
+}
+
 export interface FileSystem {
 	readFile(path: string): Promise<Buffer>
 	readFile(path: string, encoding: 'utf-8' | 'utf8'): Promise<string>
@@ -22,17 +34,113 @@ export interface FileSystem {
 	readdir(path: string, options: { withFileTypes: true }): Promise<Dirent[]>
 
 	stat(path: string): Promise<Stats>
+	/**
+	 * Like `stat`, but reports the link itself instead of following it. Answers for
+	 * a link whose target is gone, where `realpath` rejects.
+	 */
+	lstat(path: string): Promise<Stats>
 	access(path: string, mode?: number): Promise<void>
 
 	unlink(path: string): Promise<void>
 	rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>
 	cp(source: string, dest: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>
 
-	open(path: string, flags?: string): Promise<FileHandle>
+	open(path: string, flags?: string): Promise<ReadableFileHandle>
 
 	/** Returns true if path exists and is accessible; never throws for missing paths. */
 	exists(path: string): Promise<boolean>
 
 	/** Resolves symlinks and returns the canonical pathname. */
 	realpath(path: string): Promise<string>
+
+	/**
+	 * Optional. Every entry under `dir`, with the metadata a stat would return.
+	 *
+	 * Walking with readdir and stat asks the platform one question per entry and
+	 * gives it no way to see that they belong together; asking for the subtree does.
+	 * Absent on a plain node:fs platform, where the walk is what it would do anyway.
+	 *
+	 * `exclude` and `excludeHidden` are passed in so the platform can skip a
+	 * subtree rather than return it for the caller to discard.
+	 */
+	walk?(dir: string, options?: WalkOptions): Promise<WalkEntry[]>
+
+	/**
+	 * Optional. Every byte of every path, asked for once.
+	 *
+	 * Reports per path instead of throwing, because a batch that threw on the first
+	 * missing file would send the caller back to asking one at a time. Entries come
+	 * back in the order they were asked for.
+	 */
+	readFiles?(paths: readonly string[]): Promise<ReadFilesEntry[]>
+
+	/** Optional. Write a set of files as one operation. */
+	writeFiles?(entries: readonly WriteFilesEntry[], options?: WriteFilesOptions): Promise<void>
+
+	/**
+	 * Optional. Remove a set of paths as one operation.
+	 *
+	 * Raises what `rm` raises, for the same reasons. A failure partway through
+	 * leaves the paths before it removed.
+	 */
+	rmFiles?(paths: readonly string[], options?: { recursive?: boolean; force?: boolean }): Promise<void>
+
+	/**
+	 * Optional. Run `fn` with reads served from a per-operation cache, where the
+	 * platform has one.
+	 *
+	 * A hint and nothing more: the same calls return the same answers with or
+	 * without it. Prefer a verb where one fits — a verb cannot be forgotten the way
+	 * a wrapper can.
+	 */
+	scopeReads?<T>(fn: () => Promise<T>): Promise<T>
+}
+
+/** One entry under a walked directory. */
+export interface WalkEntry {
+	/** Absolute path. */
+	path: string
+	/**
+	 * `other` covers what a walk can find but not classify — a FIFO, a socket.
+	 * A symlink is reported as one whether or not its target resolves, so a
+	 * broken link is still listed rather than silently dropped.
+	 */
+	type: 'file' | 'directory' | 'symlink' | 'other'
+	/**
+	 * Bytes as `stat` reports them, so a symlink carries its target's size: the
+	 * loop this verb replaces follows the link, and a walk that did not would
+	 * disagree with it. 0 for a directory, and for a link whose target is gone.
+	 */
+	size: number
+	mtime: number
+}
+
+/** One path's answer from `readFiles`, in the order it was asked for. */
+export interface ReadFilesEntry {
+	path: string
+	/** The bytes, or absent when `error` says why there are none. */
+	content?: Buffer
+	/** The code `readFile` would have thrown for this path. */
+	error?: string
+}
+
+export interface WriteFilesEntry {
+	path: string
+	content: string | Uint8Array
+}
+
+export interface WriteFilesOptions {
+	/** Create the directories the entries need, as `mkdir -p` would. Off by default. */
+	createParents?: boolean
+}
+
+export interface WalkOptions {
+	/** Levels to descend. 1 is the directory's own children; unlimited when absent. */
+	depth?: number
+	/** Entries to return at most, in traversal order. */
+	limit?: number
+	/** Names never returned and, for a directory, never descended into. */
+	exclude?: readonly string[]
+	/** The same, for every name beginning with a dot. */
+	excludeHidden?: boolean
 }

package/src/platform/git.ts

@@ -0,0 +1,67 @@
+/**
+ * Git adapter interface.
+ *
+ * Deliberately not a git binding: it names the questions `git-status` asks, so a
+ * host can answer them however it can — a `git` process, or a library over a VFS.
+ */
+
+/** Every operation is scoped to one working tree. */
+export interface GitRepoOptions {
+	/** Working-tree directory of the repository. */
+	dir: string
+}
+
+/**
+ * One non-clean path, following git's XY convention: `index` is the staged
+ * delta against HEAD, `worktree` the unstaged delta against the staged version.
+ */
+export interface GitStatusEntry {
+	path: string
+	index: ' ' | 'A' | 'M' | 'D'
+	worktree: ' ' | 'A' | 'M' | 'D' | '?'
+}
+
+export interface GitCommit {
+	oid: string
+	/** Full commit message, subject line first. */
+	message: string
+	/** Commit time in ms since epoch, like every other SDK timestamp. */
+	committedAt: number
+}
+
+export interface GitLogOptions extends GitRepoOptions {
+	/** Ref to walk back from. Defaults to HEAD. */
+	ref?: string
+	/** Max commits to return. Unbounded when omitted. */
+	depth?: number
+}
+
+export interface GitCountAheadOptions extends GitRepoOptions {
+	/** Ref the count is measured from. */
+	base: string
+	/** Ref being measured. Defaults to HEAD. */
+	ref?: string
+}
+
+/**
+ * Read-only git queries over a working tree.
+ *
+ * Every method rejects when `dir` is not inside a repository; callers read that
+ * as "no git state to report", not as a host failure.
+ */
+export interface GitClient {
+	/** Paths that are not clean — `git status --porcelain`. */
+	status(options: GitRepoOptions): Promise<GitStatusEntry[]>
+
+	/** Commits reachable from `ref`, newest first — `git log`. */
+	log(options: GitLogOptions): Promise<GitCommit[]>
+
+	/** Commits in `ref` but not in `base` — `git rev-list --count <base>..<ref>`. */
+	countAhead(options: GitCountAheadOptions): Promise<number>
+
+	/**
+	 * Branch new commits are measured against — the remote's HEAD, where the host
+	 * can read one. `undefined` means unknown, so the caller applies its own default.
+	 */
+	defaultBranch(options: GitRepoOptions): Promise<string | undefined>
+}

package/src/platform/index.ts

@@ -7,17 +7,67 @@
  */
 
 import type { FileSystem } from './fs.js'
+import type { FsRevision } from './fs-revision.js'
+import type { GitClient } from './git.js'
+import type { LLMCallStore } from './llm-call-log.js'
 import type { ProcessRunner } from './process.js'
+import type { Scheduler } from './scheduler.js'
+import type { SessionLogStore } from './session-log.js'
+import type { ShellRunner } from './shell.js'
 
-export type { Dirent, FileHandle, FileSystem, Stats } from './fs.js'
+export type {
+	Dirent,
+	FileHandle,
+	FileSystem,
+	ReadableFileHandle,
+	ReadFilesEntry,
+	Stats,
+	WalkEntry,
+	WalkOptions,
+	WriteFilesEntry,
+	WriteFilesOptions,
+} from './fs.js'
+export type { FsRevision } from './fs-revision.js'
+export type { GitClient, GitCommit, GitCountAheadOptions, GitLogOptions, GitRepoOptions, GitStatusEntry } from './git.js'
+export type { LLMCallOutcome, LLMCallPage, LLMCallRow, LLMCallStatus, LLMCallStore } from './llm-call-log.js'
 export type { ChildProcess, ExecFileOptions, ExecFileResult, ProcessRunner, SpawnOptions } from './process.js'
+export { createTimerScheduler, isLiveScheduler } from './scheduler.js'
+export type { LiveScheduler, Scheduler, WakeHandler } from './scheduler.js'
+export type { SessionLogPage, SessionLogStore } from './session-log.js'
+export type { ShellConfinement, ShellGrant, ShellLimits, ShellRunner, ShellRunOptions, ShellRunResult } from './shell.js'
 
 /**
  * Aggregate platform capabilities passed through the system at bootstrap.
+ *
+ * `fs`, `process` and `scheduler` are required — every host has them, even if a
+ * process table is only a stub. The rest are optional: a host that omits one is
+ * not degraded, it is a host whose callers take the path they took before the
+ * port existed.
  */
 export interface Platform {
 	fs: FileSystem
 	process: ProcessRunner
+	/** Delayed re-entry into the agent loop. Required: every host can schedule. */
+	scheduler: Scheduler
+	/** Runs the shell tool's command lines. Absent on a host with no shell at all. */
+	shell?: ShellRunner
+	/** Git over the host's repositories. Absent on hosts that cannot run git. */
+	git?: GitClient
+	/**
+	 * Cheap "has the filesystem changed" counter. Absent on hosts that cannot
+	 * answer it, which then recompute whatever they would have gated on.
+	 */
+	fsRevision?: FsRevision
+	/**
+	 * Rows for the per-session log. Absent on hosts with real files, which keep
+	 * writing `sessions/<id>/session.log` and cursoring it by byte offset.
+	 */
+	sessionLog?: SessionLogStore
+	/**
+	 * Rows for the LLM call log. Absent on hosts with real files, which keep
+	 * writing `sessions/<id>/calls/<callId>.json` and listing that directory.
+	 */
+	llmCallLog?: LLMCallStore
 	/** Absolute path to the OS temp directory (equivalent to `os.tmpdir()` on Node/Bun). */
 	tmpDir: string
 }

package/src/platform/llm-call-log.ts

@@ -0,0 +1,86 @@
+/**
+ * LLM call-log store adapter.
+ *
+ * `LLMLogger` keeps the complete request and response of every inference. As
+ * files that is one JSON blob per call, written twice and read back in between.
+ * On a host whose filesystem is itself SQLite, rows are cheaper.
+ *
+ * The row is split rather than held as one blob so `complete` is a bounded
+ * `UPDATE` that never re-reads or re-writes the request it belongs to.
+ */
+
+/** The three states a logged call can be in. */
+export type LLMCallStatus = 'running' | 'success' | 'error'
+
+/**
+ * One logged call, as columns. Scalars are what a listing filters, orders and
+ * pages on; the rest is JSON the store carries without reading.
+ */
+export interface LLMCallRow {
+	/** UUIDv7. Sortable, so it is both the identity and the order — see `list`. */
+	callId: string
+	agentId: string
+	createdAt: number
+	status: LLMCallStatus
+	/** Copied out of `request` so a listing can show it without parsing the blob. */
+	model: string
+	/** Serialized `LLMCallRequest`. Written once and never rewritten. */
+	request: string
+	completedAt?: number
+	durationMs?: number
+	providerRequestId?: string
+	/** Serialized `LLMCallResponse`. Absent while the call is still running. */
+	response?: string
+	/** Serialized `LLMCallMetrics`. Absent until the call succeeds. */
+	metrics?: string
+	/** Serialized `LLMCallError`. Absent unless the call failed. */
+	error?: string
+}
+
+/** Everything a finished call adds to its row. The request is never part of it. */
+export interface LLMCallOutcome {
+	status: 'success' | 'error'
+	completedAt: number
+	durationMs: number
+	providerRequestId?: string
+	response?: string
+	metrics?: string
+	error?: string
+}
+
+export interface LLMCallPage {
+	calls: LLMCallRow[]
+	/** Calls the session holds, before `limit`/`offset` — what the UI shows as the count. */
+	total: number
+}
+
+export interface LLMCallStore {
+	/**
+	 * Largest value one column can hold, where the host has a ceiling. The caller
+	 * clamps `request` to it rather than letting an oversized prompt turn a logged
+	 * call into a failed inference. Absent means no ceiling and no clamping.
+	 */
+	readonly maxBlobBytes?: number
+
+	/** Record a call that has just started. */
+	create(sessionId: string, row: LLMCallRow): Promise<void>
+
+	/**
+	 * Attach the outcome to a call already recorded. A call id the store does not
+	 * hold is not an error — a reap between the two halves of one inference is
+	 * exactly that case.
+	 */
+	complete(sessionId: string, callId: string, outcome: LLMCallOutcome): Promise<void>
+
+	get(sessionId: string, callId: string): Promise<LLMCallRow | null>
+
+	/**
+	 * One page of a session's calls, newest first, ordered by `callId` descending.
+	 * UUIDv7 is time-ordered and fixed width, so that order is chronological and
+	 * total — two calls in the same millisecond still page without overlapping.
+	 */
+	list(sessionId: string, options: { limit: number; offset: number }): Promise<LLMCallPage>
+
+	/** Drop every call held for one session, and report how many went. */
+	delete(sessionId: string): Promise<number>
+}

package/src/platform/scheduler.ts

@@ -0,0 +1,71 @@
+/**
+ * Scheduler adapter interface.
+ *
+ * The agent loop re-enters through this port instead of a bare `setTimeout`, so
+ * a host with no live process between wakes can drive it — on Cloudflare,
+ * `ctx.storage.setAlarm()` then `alarm()`.
+ */
+
+/** Called when a wake armed for `key` comes due. */
+export type WakeHandler = (key: string) => void | Promise<void>
+
+export interface Scheduler {
+	/** Wake `key` after `delayMs`. Replaces any pending wake for the same key. */
+	wake(key: string, delayMs: number): Promise<void>
+	cancel(key: string): Promise<void>
+}
+
+/**
+ * A scheduler that delivers its own wakes, because the process that armed them
+ * is still alive. Hosts that deliver out-of-band implement plain {@link Scheduler}
+ * and call `SessionManager.dispatchWake` from their own handler.
+ */
+export interface LiveScheduler extends Scheduler {
+	/** Register where due wakes are delivered. Replaces any previous handler. */
+	onWake(handler: WakeHandler): void
+}
+
+export function isLiveScheduler(scheduler: Scheduler): scheduler is LiveScheduler {
+	return 'onWake' in scheduler && typeof scheduler.onWake === 'function'
+}
+
+/**
+ * `setTimeout`-backed scheduler for hosts with a live process.
+ *
+ * Arms and clears synchronously, so the cancel-then-wake sequence callers issue
+ * without awaiting cannot land out of order.
+ */
+export function createTimerScheduler(): LiveScheduler {
+	const timers = new Map<string, ReturnType<typeof setTimeout>>()
+	let handler: WakeHandler | undefined
+
+	const clear = (key: string): void => {
+		const timer = timers.get(key)
+		if (timer === undefined) return
+		clearTimeout(timer)
+		timers.delete(key)
+	}
+
+	return {
+		onWake(next: WakeHandler): void {
+			handler = next
+		},
+
+		async wake(key: string, delayMs: number): Promise<void> {
+			clear(key)
+			timers.set(
+				key,
+				setTimeout(() => {
+					timers.delete(key)
+					const dispatched = handler?.(key)
+					// The handler owns its own error reporting; there is nothing a timer can do.
+					if (dispatched) void dispatched.catch(() => {})
+				}, delayMs),
+			)
+		},
+
+		async cancel(key: string): Promise<void> {
+			clear(key)
+		},
+	}
+}

package/src/platform/session-log.ts

@@ -0,0 +1,39 @@
+/**
+ * Session-log store adapter.
+ *
+ * `session.log` is the detailed record of one session. On a host with real files
+ * it is a JSONL file appended to, which is the right shape there. On a host whose
+ * filesystem is itself SQLite it is not, so this port lets it spend rows instead.
+ *
+ * Optional: a host without a table is unchanged — `SessionManager` writes the file
+ * it always wrote and `logs.tail` cursors it by byte offset.
+ */
+
+export interface SessionLogPage {
+	/** One serialized JSON object per entry, without the trailing newline. */
+	lines: string[]
+	/**
+	 * Cursor to hand back as `since` on the next read.
+	 *
+	 * Opaque and only comparable with itself: a file-backed log counts bytes and a
+	 * store-backed one counts entries, and no caller may assume which.
+	 */
+	offset: number
+}
+
+export interface SessionLogStore {
+	/**
+	 * Record one already-serialized line.
+	 *
+	 * Returns nothing rather than a promise, and must never throw: logging sits on
+	 * the agent loop's path and nothing there awaits it. A store that cannot write
+	 * drops the line, exactly as a failed file append is swallowed.
+	 */
+	append(sessionId: string, line: string): void
+
+	/** Entries recorded after `since`, and the cursor that follows them. */
+	read(sessionId: string, since: number): Promise<SessionLogPage>
+
+	/** Drop every entry held for one session, and report how many went. */
+	delete(sessionId: string): Promise<number>
+}

package/src/platform/shell.ts

@@ -0,0 +1,89 @@
+/**
+ * Shell adapter interface.
+ *
+ * The shell tool assembles and validates a command line; running it is the
+ * host's business. A host with a process table spawns `/bin/sh`; one without
+ * answers from an in-process interpreter over its own filesystem.
+ *
+ * Resource limits are the host's business too, and two `ulimit` values only look like
+ * guards: `-v` (RLIMIT_AS) bounds mapped address space, not memory in use; `-t`
+ * (RLIMIT_CPU) sums CPU across threads and resets in each child. Bound wall time instead.
+ */
+
+/**
+ * How a runner confines what a command may touch.
+ *
+ * `paths` honours the grants below; `host` is a filesystem that holds nothing
+ * but this session, so the grants are redundant; `none` cannot confine at all,
+ * and the caller decides whether that is acceptable.
+ */
+export type ShellConfinement = 'paths' | 'host' | 'none'
+
+/** One path the command may reach, and where the host finds it. */
+export interface ShellGrant {
+	/** Path as the command sees it. */
+	path: string
+	/**
+	 * Where the host reads it from, when that differs. A runner that has to mount
+	 * the confinement needs the pair; absent means the command's path is the host's.
+	 */
+	source?: string
+	mode: 'rw' | 'ro'
+}
+
+export interface ShellRunOptions {
+	/** One command line, already assembled and escaped by the caller. */
+	command: string
+	cwd: string
+	env?: Record<string, string>
+	stdin?: string
+	timeoutMs: number
+	/**
+	 * What the command may reach. Meaningful only under `paths` confinement, and
+	 * ordered: a grant is applied after the ones before it, so a later grant may
+	 * narrow an earlier one.
+	 */
+	grants?: readonly ShellGrant[]
+	/** Whether a confined command may reach the network. Default: false. */
+	network?: boolean
+	/** Interpreter for `command`. A host with a single interpreter ignores it. */
+	shell?: string
+	/** Caps for a confined command; ignored when the command runs unconfined. */
+	limits?: ShellLimits
+}
+
+/**
+ * Caps a host applies to a confined command. An omitted field takes the host's
+ * default; `null` asks for no cap at all, for a host where one does more harm
+ * than good — an old kernel that counts processes per uid rather than per namespace.
+ */
+export interface ShellLimits {
+	/** Largest file the command may write, in bytes. */
+	fileSizeBytes?: number | null
+	/** Concurrent processes. On Linux this is per-uid, not per-process. */
+	processes?: number | null
+}
+
+export interface ShellRunResult {
+	stdout: string
+	stderr: string
+	exitCode: number
+	/** Set when the host terminated the command rather than the command exiting. */
+	signal?: string
+	timedOut: boolean
+	/** Set when either stream hit the host's output ceiling. */
+	truncated?: boolean
+}
+
+export interface ShellRunner {
+	/** Declared, not assumed: a caller that needs confinement checks it before running. */
+	readonly confinement: ShellConfinement
+
+	/**
+	 * Run one command line to completion and buffer its output.
+	 *
+	 * Resolves with a non-zero `exitCode` rather than rejecting — a failed command
+	 * is an answer. Rejects only when the host could not run it at all.
+	 */
+	run(options: ShellRunOptions): Promise<ShellRunResult>
+}

package/src/plugins/agent-status/plugin.ts

@@ -45,6 +45,7 @@ export const agentStoppedNotificationSchema = z.object({
 export type AgentStoppedNotification = z.infer<typeof agentStoppedNotificationSchema>
 
 export const agentStatusPlugin = definePlugin('agent-status')
+	.order(50)
 	.notification('agentStatus', {
 		schema: z.object({
 			sessionId: sessionIdSchema,