@onlooker-community/adapter-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 Onlooker Community

package/README.md

@@ -0,0 +1,134 @@
+# @onlooker-community/adapter-sdk
+
+Foundational SDK for Onlooker **runtime adapters**. Defines the contract every adapter implements, the abstract base class that handles the cross-runtime concerns, and the canonical event writer.
+
+An adapter sits between a runtime (Claude Code, Cursor, Copilot, ...) and the canonical Onlooker event bus. It does two things:
+
+1. **Translate** runtime-native events into canonical [`OnlookerEvent`](https://github.com/onlooker-community/schema) envelopes.
+2. **Deliver** plugin decisions back to the runtime in its native format (block / allow / inject context).
+
+## Install
+
+```sh
+npm install @onlooker-community/adapter-sdk
+```
+
+This package declares `@onlooker-community/schema` as a peer dependency. Install it explicitly:
+
+```sh
+npm install @onlooker-community/schema
+```
+
+## The contract
+
+```ts
+import type { OnlookerRuntimeAdapter } from "@onlooker-community/adapter-sdk";
+```
+
+Every adapter declares:
+
+- `runtimeId` — one of the canonical strings from `schema.event.v1.json` (`claude-code`, `cursor`, `copilot`, `gemini`, `custom`).
+- `version` — the adapter's own semver string.
+
+…and implements two clusters of methods:
+
+**Event ingestion (runtime → canonical events):**
+
+- `onSessionStart`, `onSessionEnd`
+- `onFileWrite`, `onFileEdit`
+- `onShellExec`, `onWebFetch`
+- `onAgentSpawn`, `onAgentComplete`
+
+Each receives the runtime-native payload as `unknown`, normalises it, and returns an `OnlookerEvent`.
+
+**Decision delivery (plugin decisions → runtime):**
+
+- `blockOperation(reason)`
+- `allowOperation()`
+- `injectContext(content)`
+
+These are best-effort by contract — adapters must never throw out of them.
+
+## Building one — extend `BaseAdapter`
+
+```ts
+import { BaseAdapter } from "@onlooker-community/adapter-sdk";
+import type { OnlookerEvent } from "@onlooker-community/schema";
+
+export class ClaudeCodeAdapter extends BaseAdapter {
+  constructor(machineId: string) {
+    super({ runtimeId: "claude-code", version: "0.1.0", machineId });
+  }
+
+  onSessionStart(raw: unknown): OnlookerEvent {
+    const sid = (raw as { session_id: string }).session_id;
+    this.startSession(sid);
+    return this.writeEvent({
+      plugin: "claude-code",
+      event_type: "session.start",
+      payload: {
+        cwd: process.cwd(),
+        project_name: null,
+        git_branch: null,
+        git_commit: null,
+      },
+      session_id: sid,
+    });
+  }
+
+  // ... rest of the on* + decision-delivery methods
+}
+```
+
+`BaseAdapter` handles:
+
+- **Session ID generation and tracking** — `newSessionId()` mints UUIDs; `startSession(sid)` initialises a per-session sequence counter.
+- **Sequence counter per session** — each call to `buildEvent` / `writeEvent` reads-then-increments the counter for `session_id` so events within a session carry monotonic sequence numbers.
+- **`createEventBase()` equivalent** — the shared envelope fields (`id`, `schema_version`, `runtime`, `machine_id`, `timestamp`, `session_id`, `sequence`) come from `buildEvent`.
+- **`writeEvent(event)`** — appends to `~/.onlooker/<runtimeId>/<plugin>/<session_id>.jsonl`.
+
+## Canonical event layout
+
+Events land at:
+
+```text
+~/.onlooker/<runtimeId>/<plugin>/<session_id>.jsonl
+```
+
+…one JSON line per event, matching the [canonical envelope](https://github.com/onlooker-community/schema/blob/main/schemas/event.v1.json).
+
+Tests and alternate installs can override the root by passing `eventWriterOptions: { rootDir }` to the `BaseAdapter` constructor.
+
+## Test helpers
+
+`EventWriter` and `eventLogPath` are exported for adapters that want to bypass `BaseAdapter` (e.g. integration tests, runtime probes):
+
+```ts
+import { EventWriter, eventLogPath } from "@onlooker-community/adapter-sdk";
+
+const writer = new EventWriter({ rootDir: "/tmp/onl-test" });
+writer.write(event);
+console.log(writer.pathFor(event));
+```
+
+## Local development
+
+After cloning, `npm install` runs `simple-git-hooks` via `prepare` and
+installs a `pre-push` hook that mirrors CI:
+
+```sh
+npm run verify    # biome ci → typecheck → test → build
+```
+
+The same four commands run in GitHub Actions, so a green `verify` is a
+green PR. To skip the hook in an emergency, `SKIP_SIMPLE_GIT_HOOKS=1 git push`.
+
+To auto-fix Biome lint, format, and import-sort findings in one go:
+
+```sh
+npm run fix       # biome check --write
+```
+
+## License
+
+Apache-2.0

package/dist/base-adapter.d.ts

@@ -0,0 +1,108 @@
+import type { EventType, OnlookerEvent, PayloadFor, RuntimeId } from "@onlooker-community/schema";
+import { EventWriter, type EventWriterOptions } from "./event-writer.js";
+import type { OnlookerRuntimeAdapter } from "./types.js";
+export interface BaseAdapterOptions {
+    /**
+     * Optional override for the event writer. Tests pass a writer
+     * configured against a temp dir; production code leaves this off
+     * and gets the default ~/.onlooker writer.
+     */
+    eventWriter?: EventWriter;
+    /**
+     * Equivalent to passing `new EventWriter({ rootDir })`. Kept as a
+     * convenience so adapters don't have to import EventWriter just to
+     * change the root.
+     */
+    eventWriterOptions?: EventWriterOptions;
+}
+/**
+ * Shape the subclass passes to `buildEvent` when creating a canonical
+ * event. The base class fills in everything else (id, schema_version,
+ * runtime, machine_id, timestamp, session_id, sequence).
+ */
+export interface BuildEventParams<T extends EventType> {
+    plugin: string;
+    event_type: T;
+    payload: PayloadFor<T>;
+    session_id: string;
+    adapter_id?: string;
+    cost_usd?: number;
+    token_count?: number;
+}
+/**
+ * Abstract base every OnlookerRuntimeAdapter extends.
+ *
+ * Subclasses must:
+ *   1. Pass `runtimeId`, `version`, and `machineId` to `super()`.
+ *   2. Call `this.startSession(sessionId)` from `onSessionStart` (and
+ *      whenever they otherwise observe a session begin) so the
+ *      sequence counter exists.
+ *   3. Implement the abstract `on*` callbacks and the
+ *      RuntimeDecisionDelivery methods.
+ *   4. Use `this.buildEvent()` to construct events — that's what
+ *      keeps id/schema_version/sequence consistent.
+ */
+export declare abstract class BaseAdapter implements OnlookerRuntimeAdapter {
+    readonly runtimeId: RuntimeId;
+    readonly version: string;
+    /** Stable machine identifier (UUID). One per host install. */
+    protected readonly machineId: string;
+    /**
+     * Per-session sequence counters. Each `createEvent` call inside
+     * `buildEvent` reads-then-increments the counter for that session
+     * id so events within a session carry monotonic sequence numbers.
+     */
+    private readonly sequence;
+    private readonly writer;
+    constructor(args: {
+        runtimeId: RuntimeId;
+        version: string;
+        machineId: string;
+        options?: BaseAdapterOptions;
+    });
+    /**
+     * Initialise (or reset) the sequence counter for `sessionId`.
+     * Called from `onSessionStart`. Idempotent — calling twice resets
+     * the counter, which is the desired behavior for resumed sessions
+     * that issue a fresh session-start event.
+     */
+    protected startSession(sessionId: string): void;
+    /**
+     * Generate a new session id. Adapters can pull this if the runtime
+     * doesn't surface one of its own (e.g. a stateless tool invocation).
+     */
+    protected newSessionId(): string;
+    /**
+     * Read-and-increment the sequence counter for `sessionId`. Lazily
+     * initialises if the session wasn't seen before — adapters
+     * occasionally receive events out of order (session-end fires
+     * before session-start due to clock skew), and we'd rather emit
+     * those with sequence=0 than crash.
+     */
+    protected nextSequence(sessionId: string): number;
+    /**
+     * Shared envelope fields. Concrete `on*` callbacks call this to
+     * build the canonical event, then pass the result to `writeEvent`
+     * (or yield it from the callback for the caller to write).
+     */
+    protected buildEvent<T extends EventType>(params: BuildEventParams<T>): OnlookerEvent<T>;
+    /**
+     * Convenience: build + persist. Concrete adapters typically end
+     * their `on*` callbacks with this — `return this.writeEvent(...)`.
+     */
+    protected writeEvent<T extends EventType>(params: BuildEventParams<T>): OnlookerEvent<T>;
+    /** Test/inspection helper — exposes the resolved JSONL path. */
+    pathFor(event: OnlookerEvent): string;
+    abstract onSessionStart(rawEvent: unknown): OnlookerEvent;
+    abstract onSessionEnd(rawEvent: unknown): OnlookerEvent;
+    abstract onFileWrite(rawEvent: unknown): OnlookerEvent;
+    abstract onFileEdit(rawEvent: unknown): OnlookerEvent;
+    abstract onShellExec(rawEvent: unknown): OnlookerEvent;
+    abstract onWebFetch(rawEvent: unknown): OnlookerEvent;
+    abstract onAgentSpawn(rawEvent: unknown): OnlookerEvent;
+    abstract onAgentComplete(rawEvent: unknown): OnlookerEvent;
+    abstract blockOperation(reason: string): void;
+    abstract allowOperation(): void;
+    abstract injectContext(content: string): void;
+}
+//# sourceMappingURL=base-adapter.d.ts.map

package/dist/base-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-adapter.d.ts","sourceRoot":"","sources":["../src/base-adapter.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAEX,SAAS,EACT,aAAa,EACb,UAAU,EACV,SAAS,EACT,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,SAAS;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,CAAC,CAAC;IACd,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,8BAAsB,WAAY,YAAW,sBAAsB;IAClE,SAAgB,SAAS,EAAE,SAAS,CAAC;IACrC,SAAgB,OAAO,EAAE,MAAM,CAAC;IAEhC,8DAA8D;IAC9D,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAErC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAE3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,IAAI,EAAE;QACjB,SAAS,EAAE,SAAS,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,kBAAkB,CAAC;KAC7B;IAWD;;;;;OAKG;IACH,SAAS,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI/C;;;OAGG;IACH,SAAS,CAAC,YAAY,IAAI,MAAM;IAIhC;;;;;;OAMG;IACH,SAAS,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAQjD;;;;OAIG;IACH,SAAS,CAAC,UAAU,CAAC,CAAC,SAAS,SAAS,EACvC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GACzB,aAAa,CAAC,CAAC,CAAC;IAsBnB;;;OAGG;IACH,SAAS,CAAC,UAAU,CAAC,CAAC,SAAS,SAAS,EACvC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GACzB,aAAa,CAAC,CAAC,CAAC;IAMnB,gEAAgE;IACzD,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM;IAM5C,QAAQ,CAAC,cAAc,CAAC,QAAQ,EAAE,OAAO,GAAG,aAAa;IACzD,QAAQ,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,GAAG,aAAa;IACvD,QAAQ,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,aAAa;IACtD,QAAQ,CAAC,UAAU,CAAC,QAAQ,EAAE,OAAO,GAAG,aAAa;IACrD,QAAQ,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,aAAa;IACtD,QAAQ,CAAC,UAAU,CAAC,QAAQ,EAAE,OAAO,GAAG,aAAa;IACrD,QAAQ,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,GAAG,aAAa;IACvD,QAAQ,CAAC,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,aAAa;IAE1D,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAC7C,QAAQ,CAAC,cAAc,IAAI,IAAI;IAC/B,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAC7C"}

package/dist/base-adapter.js

@@ -0,0 +1,123 @@
+// BaseAdapter — abstract base class every runtime adapter extends.
+//
+// Owns the cross-runtime concerns so concrete adapters can focus on the
+// runtime-specific translation:
+//   * session id tracking with one monotonic sequence counter per
+//     session
+//   * createEventBase() — shared envelope fields (id, schema_version,
+//     timestamp, sequence, etc.)
+//   * writeEvent() — append to ~/.onlooker/<runtimeId>/<plugin>/<sid>.jsonl
+//
+// Subclasses implement the `on*` callbacks and the decision-delivery
+// methods. Subclasses MUST call `this.startSession(sessionId)` from
+// their session-start handler so the sequence counter is initialised
+// before any other event for that session is created.
+import { randomUUID } from "node:crypto";
+import { createEvent } from "@onlooker-community/schema";
+import { EventWriter } from "./event-writer.js";
+/**
+ * Abstract base every OnlookerRuntimeAdapter extends.
+ *
+ * Subclasses must:
+ *   1. Pass `runtimeId`, `version`, and `machineId` to `super()`.
+ *   2. Call `this.startSession(sessionId)` from `onSessionStart` (and
+ *      whenever they otherwise observe a session begin) so the
+ *      sequence counter exists.
+ *   3. Implement the abstract `on*` callbacks and the
+ *      RuntimeDecisionDelivery methods.
+ *   4. Use `this.buildEvent()` to construct events — that's what
+ *      keeps id/schema_version/sequence consistent.
+ */
+export class BaseAdapter {
+    runtimeId;
+    version;
+    /** Stable machine identifier (UUID). One per host install. */
+    machineId;
+    /**
+     * Per-session sequence counters. Each `createEvent` call inside
+     * `buildEvent` reads-then-increments the counter for that session
+     * id so events within a session carry monotonic sequence numbers.
+     */
+    sequence = new Map();
+    writer;
+    constructor(args) {
+        this.runtimeId = args.runtimeId;
+        this.version = args.version;
+        this.machineId = args.machineId;
+        this.writer =
+            args.options?.eventWriter ??
+                new EventWriter(args.options?.eventWriterOptions ?? {});
+    }
+    // ── Session tracking ────────────────────────────────────────────────────
+    /**
+     * Initialise (or reset) the sequence counter for `sessionId`.
+     * Called from `onSessionStart`. Idempotent — calling twice resets
+     * the counter, which is the desired behavior for resumed sessions
+     * that issue a fresh session-start event.
+     */
+    startSession(sessionId) {
+        this.sequence.set(sessionId, 0);
+    }
+    /**
+     * Generate a new session id. Adapters can pull this if the runtime
+     * doesn't surface one of its own (e.g. a stateless tool invocation).
+     */
+    newSessionId() {
+        return randomUUID();
+    }
+    /**
+     * Read-and-increment the sequence counter for `sessionId`. Lazily
+     * initialises if the session wasn't seen before — adapters
+     * occasionally receive events out of order (session-end fires
+     * before session-start due to clock skew), and we'd rather emit
+     * those with sequence=0 than crash.
+     */
+    nextSequence(sessionId) {
+        const current = this.sequence.get(sessionId) ?? 0;
+        this.sequence.set(sessionId, current + 1);
+        return current;
+    }
+    // ── Event construction ──────────────────────────────────────────────────
+    /**
+     * Shared envelope fields. Concrete `on*` callbacks call this to
+     * build the canonical event, then pass the result to `writeEvent`
+     * (or yield it from the callback for the caller to write).
+     */
+    buildEvent(params) {
+        const base = {
+            runtime: this.runtimeId,
+            plugin: params.plugin,
+            machine_id: this.machineId,
+            session_id: params.session_id,
+            event_type: params.event_type,
+            payload: params.payload,
+        };
+        if (params.adapter_id !== undefined)
+            base.adapter_id = params.adapter_id;
+        if (params.cost_usd !== undefined)
+            base.cost_usd = params.cost_usd;
+        if (params.token_count !== undefined)
+            base.token_count = params.token_count;
+        const event = createEvent(base);
+        // `createEvent` uses a module-scoped global counter; we override
+        // with our per-session counter so adapters running in long-lived
+        // processes (Claude Code daemon) keep per-session sequences
+        // instead of one monotonic counter for everything.
+        event.sequence = this.nextSequence(params.session_id);
+        return event;
+    }
+    /**
+     * Convenience: build + persist. Concrete adapters typically end
+     * their `on*` callbacks with this — `return this.writeEvent(...)`.
+     */
+    writeEvent(params) {
+        const event = this.buildEvent(params);
+        this.writer.write(event);
+        return event;
+    }
+    /** Test/inspection helper — exposes the resolved JSONL path. */
+    pathFor(event) {
+        return this.writer.pathFor(event);
+    }
+}
+//# sourceMappingURL=base-adapter.js.map

package/dist/base-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-adapter.js","sourceRoot":"","sources":["../src/base-adapter.ts"],"names":[],"mappings":"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"}

package/dist/event-writer.d.ts

@@ -0,0 +1,32 @@
+import type { OnlookerEvent } from "@onlooker-community/schema";
+export interface EventWriterOptions {
+    /**
+     * Root directory for canonical event JSONL. Defaults to
+     * `~/.onlooker`. Override for tests or alternate installs.
+     */
+    rootDir?: string;
+}
+/**
+ * Resolve the canonical JSONL path for a single event.
+ *
+ * `rootDir` defaults to `~/.onlooker` — callers passing a custom root
+ * (typically tests) get full control.
+ */
+export declare function eventLogPath(event: OnlookerEvent, rootDir?: string): string;
+/**
+ * Append a single canonical event to its per-session JSONL file. Side
+ * effect only — returns nothing. Errors are swallowed and reported via
+ * `onError` (default: stderr) so adapters can stay non-blocking.
+ */
+export declare class EventWriter {
+    private readonly rootDir;
+    private readonly onError;
+    constructor(options?: EventWriterOptions, onError?: (err: unknown, event: OnlookerEvent) => void);
+    write(event: OnlookerEvent): void;
+    /**
+     * Path the next write for this event would land at. Useful for tests
+     * and for adapters that want to surface the log location to users.
+     */
+    pathFor(event: OnlookerEvent): string;
+}
+//# sourceMappingURL=event-writer.d.ts.map

package/dist/event-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-writer.d.ts","sourceRoot":"","sources":["../src/event-writer.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE,MAAM,WAAW,kBAAkB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,aAAa,EACpB,OAAO,GAAE,MAAqC,GAC5C,MAAM,CAOR;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+C;gBAGtE,OAAO,GAAE,kBAAuB,EAChC,OAAO,GAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,KAAK,IAOhD;IAMF,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAUjC;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM;CAGrC"}

package/dist/event-writer.js

@@ -0,0 +1,56 @@
+// EventWriter — appends canonical events to per-session JSONL files.
+//
+// File layout, by contract:
+//   ~/.onlooker/<runtimeId>/<plugin>/<session_id>.jsonl
+//
+// Each event becomes a single JSON line. Writes are append-only and
+// best-effort: if the filesystem is unavailable, the writer logs to
+// stderr and continues so the runtime doesn't crash on disk pressure.
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * Resolve the canonical JSONL path for a single event.
+ *
+ * `rootDir` defaults to `~/.onlooker` — callers passing a custom root
+ * (typically tests) get full control.
+ */
+export function eventLogPath(event, rootDir = join(homedir(), ".onlooker")) {
+    return join(rootDir, event.runtime, event.plugin, `${event.session_id}.jsonl`);
+}
+/**
+ * Append a single canonical event to its per-session JSONL file. Side
+ * effect only — returns nothing. Errors are swallowed and reported via
+ * `onError` (default: stderr) so adapters can stay non-blocking.
+ */
+export class EventWriter {
+    rootDir;
+    onError;
+    constructor(options = {}, onError = (err, event) => {
+        // One-line stderr is enough to be greppable; full event would
+        // be noisy and may contain large payloads.
+        console.error(`[adapter-sdk] event write failed for ${event.event_type} ` +
+            `session=${event.session_id}: ${err.message}`);
+    }) {
+        this.rootDir = options.rootDir ?? join(homedir(), ".onlooker");
+        this.onError = onError;
+    }
+    write(event) {
+        const path = eventLogPath(event, this.rootDir);
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            appendFileSync(path, `${JSON.stringify(event)}\n`);
+        }
+        catch (err) {
+            this.onError(err, event);
+        }
+    }
+    /**
+     * Path the next write for this event would land at. Useful for tests
+     * and for adapters that want to surface the log location to users.
+     */
+    pathFor(event) {
+        return eventLogPath(event, this.rootDir);
+    }
+}
+//# sourceMappingURL=event-writer.js.map

package/dist/event-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-writer.js","sourceRoot":"","sources":["../src/event-writer.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,4BAA4B;AAC5B,wDAAwD;AACxD,EAAE;AACF,oEAAoE;AACpE,oEAAoE;AACpE,sEAAsE;AAEtE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAW1C;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC3B,KAAoB,EACpB,UAAkB,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC;IAE9C,OAAO,IAAI,CACV,OAAO,EACP,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,MAAM,EACZ,GAAG,KAAK,CAAC,UAAU,QAAQ,CAC3B,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,WAAW;IACN,OAAO,CAAS;IAChB,OAAO,CAA+C;IAEvE,YACC,UAA8B,EAAE,EAChC,UAAwD,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QACtE,8DAA8D;QAC9D,2CAA2C;QAC3C,OAAO,CAAC,KAAK,CACZ,wCAAwC,KAAK,CAAC,UAAU,GAAG;YAC1D,WAAW,KAAK,CAAC,UAAU,KAAM,GAAa,CAAC,OAAO,EAAE,CACzD,CAAC;IACH,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;QAC/D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,KAAoB;QACzB,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAI,CAAC;YACJ,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9C,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1B,CAAC;IACF,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,KAAoB;QAC3B,OAAO,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;CACD"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { BaseAdapter, type BaseAdapterOptions, type BuildEventParams, } from "./base-adapter.js";
+export { EventWriter, type EventWriterOptions, eventLogPath, } from "./event-writer.js";
+export type { AdapterEventCallbacks, OnlookerEvent, OnlookerRuntimeAdapter, RuntimeDecisionDelivery, RuntimeId, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,WAAW,EACX,KAAK,kBAAkB,EACvB,YAAY,GACZ,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACX,qBAAqB,EACrB,aAAa,EACb,sBAAsB,EACtB,uBAAuB,EACvB,SAAS,GACT,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// Public API barrel.
+export { BaseAdapter, } from "./base-adapter.js";
+export { EventWriter, eventLogPath, } from "./event-writer.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qBAAqB;AAErB,OAAO,EACN,WAAW,GAGX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,WAAW,EAEX,YAAY,GACZ,MAAM,mBAAmB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+import type { OnlookerEvent, RuntimeId } from "@onlooker-community/schema";
+/**
+ * Mapping from canonical lifecycle event types to the OnlookerEvent
+ * payload shape the schema expects for each. Adapter callbacks are
+ * typed against this map so a future schema change surfaces as a type
+ * error in adapters before it surfaces in production.
+ */
+export type AdapterEventCallbacks = {
+    onSessionStart: (rawEvent: unknown) => OnlookerEvent;
+    onSessionEnd: (rawEvent: unknown) => OnlookerEvent;
+    onFileWrite: (rawEvent: unknown) => OnlookerEvent;
+    onFileEdit: (rawEvent: unknown) => OnlookerEvent;
+    onShellExec: (rawEvent: unknown) => OnlookerEvent;
+    onWebFetch: (rawEvent: unknown) => OnlookerEvent;
+    onAgentSpawn: (rawEvent: unknown) => OnlookerEvent;
+    onAgentComplete: (rawEvent: unknown) => OnlookerEvent;
+};
+/**
+ * Plugin → runtime decision delivery. The plugin layer calls these to
+ * tell the runtime adapter how to act on a tool invocation. Adapters
+ * are free to translate the call to whatever native primitive the
+ * runtime exposes (Claude Code hook stdout, MCP response, IDE notify,
+ * etc.). All three are best-effort by contract — adapters must never
+ * throw out of these methods.
+ */
+export interface RuntimeDecisionDelivery {
+    /** Block the in-flight operation. `reason` is shown to the user. */
+    blockOperation(reason: string): void;
+    /** Allow the in-flight operation to proceed unchanged. */
+    allowOperation(): void;
+    /**
+     * Inject context into the runtime's prompt / conversation surface.
+     * The exact mechanism depends on the runtime: Claude Code uses
+     * SessionStart `additionalContext`, Cursor a system message, etc.
+     */
+    injectContext(content: string): void;
+}
+/**
+ * The OnlookerRuntimeAdapter contract.
+ *
+ * Implementations sit between a runtime (Claude Code, Cursor, ...) and
+ * the canonical event bus. They:
+ *   - normalise runtime-native events into OnlookerEvent envelopes via
+ *     the `on*` callbacks
+ *   - deliver plugin decisions back to the runtime via the
+ *     RuntimeDecisionDelivery methods
+ *
+ * Every adapter declares its `runtimeId` (one of the canonical strings
+ * in the schema enum) and a semantic `version` so consumers can pin or
+ * gate by adapter capability.
+ */
+export interface OnlookerRuntimeAdapter extends AdapterEventCallbacks, RuntimeDecisionDelivery {
+    readonly runtimeId: RuntimeId;
+    readonly version: string;
+}
+/** Re-export RuntimeId so adapters don't have to import from schema. */
+export type { OnlookerEvent, RuntimeId };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG;IACnC,cAAc,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,aAAa,CAAC;IACrD,YAAY,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,aAAa,CAAC;IACnD,WAAW,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,aAAa,CAAC;IAClD,UAAU,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,aAAa,CAAC;IACjD,WAAW,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,aAAa,CAAC;IAClD,UAAU,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,aAAa,CAAC;IACjD,YAAY,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,aAAa,CAAC;IACnD,eAAe,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,aAAa,CAAC;CACtD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACvC,oEAAoE;IACpE,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,0DAA0D;IAC1D,cAAc,IAAI,IAAI,CAAC;IACvB;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,sBAChB,SAAQ,qBAAqB,EAC5B,uBAAuB;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,9 @@
+// Public types for the Onlooker adapter SDK.
+//
+// `OnlookerRuntimeAdapter` is the contract every runtime adapter implements.
+// Adapters translate runtime-native events (Claude Code hook payloads,
+// Cursor tool calls, GitHub Copilot completions, etc.) into canonical
+// OnlookerEvent envelopes from @onlooker-community/schema, and deliver
+// plugin decisions back to the runtime in its native format.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,6EAA6E;AAC7E,uEAAuE;AACvE,sEAAsE;AACtE,uEAAuE;AACvE,6DAA6D"}

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "@onlooker-community/adapter-sdk",
+	"version": "1.0.0",
+	"description": "Foundational SDK for Onlooker runtime adapters — defines the OnlookerRuntimeAdapter interface, base class, and canonical event writer.",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"ci": "npx @biomejs/biome ci",
+		"lint": "npx @biomejs/biome lint",
+		"lint:fix": "npx @biomejs/biome lint --fix",
+		"format": "npx @biomejs/biome format",
+		"format:fix": "npx @biomejs/biome format --write",
+		"fix": "npx @biomejs/biome check --write",
+		"test": "vitest run",
+		"typecheck": "tsc --noEmit",
+		"verify": "npm run ci && npm run typecheck && npm run test && npm run build",
+		"prepare": "simple-git-hooks",
+		"prepublishOnly": "npm run build && npm test"
+	},
+	"simple-git-hooks": {
+		"pre-push": "npm run verify"
+	},
+	"peerDependencies": {
+		"@onlooker-community/schema": "^0.1.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.14",
+		"@onlooker-community/schema": "^0.1.0",
+		"@types/node": "^20.0.0",
+		"simple-git-hooks": "^2.13.1",
+		"typescript": "^5.0.0",
+		"vitest": "^1.0.0"
+	},
+	"keywords": [
+		"onlooker",
+		"adapter",
+		"runtime",
+		"sdk",
+		"canonical-events"
+	],
+	"license": "Apache-2.0",
+	"author": "Onlooker Community",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/onlooker-community/adapter-sdk.git"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}