kernl 0.2.0 → 0.6.0

package/src/api/pagination/cursor.ts

@@ -0,0 +1,86 @@
+import { AbstractPage, type PageParamsBase } from "./base";
+
+export interface CursorPageParams extends PageParamsBase {
+  /**
+   * Pagination cursor returned from a previous page.
+   * If omitted, starts from the beginning of the collection.
+   */
+  cursor?: string;
+}
+
+export interface CursorPageResponse<T> {
+  data: T[];
+  /**
+   * Cursor for the next page, or null if there is no next page.
+   */
+  next: string | null;
+  /**
+   * True if this is the last page (no further pages).
+   */
+  last: boolean;
+}
+
+export class CursorPage<
+  T,
+  TParams extends CursorPageParams = CursorPageParams,
+> extends AbstractPage<T, TParams, CursorPageResponse<T>> {
+  data: T[];
+  private readonly _next: string | null;
+  private readonly _last: boolean;
+
+  constructor(args: {
+    params: TParams;
+    response: CursorPageResponse<T>;
+    loader: (params: TParams) => Promise<CursorPageResponse<T>>;
+  }) {
+    super(args);
+    this.data = args.response.data ?? [];
+    this._next = args.response.next;
+    this._last = args.response.last;
+  }
+
+  /**
+   * All items contained in this page.
+   */
+  get items(): T[] {
+    return this.data;
+  }
+
+  /**
+   * True if this is the last page in the sequence.
+   *
+   * When `last` is true, `next()` will return null.
+   */
+  get last(): boolean {
+    if (this._last) return true;
+    if (!this._next) return true;
+    return this.data.length === 0;
+  }
+
+  /**
+   * Fetch the next page, or null if there is no next page.
+   */
+  async next(): Promise<this | null> {
+    if (this.last) {
+      return null;
+    }
+
+    if (!this._next) {
+      return null;
+    }
+
+    const nextParams: TParams = {
+      ...(this.params as TParams),
+      cursor: this._next,
+    };
+
+    const res = await this.loader(nextParams);
+    const page = new CursorPage<T, TParams>({
+      params: nextParams,
+      response: res,
+      loader: this.loader,
+    }) as this;
+
+    return page;
+  }
+}

package/src/api/pagination/offset.ts

@@ -0,0 +1,89 @@
+import { AbstractPage, type PageParamsBase } from "./base";
+
+export interface OffsetPageParams extends PageParamsBase {
+  /**
+   * Number of items to skip from the beginning of the collection.
+   */
+  offset?: number;
+}
+
+export interface OffsetPageResponse<T> {
+  data: T[];
+  offset: number;
+  limit: number;
+  /**
+   * Optional total count when the underlying store can provide it.
+   */
+  total?: number;
+}
+
+export class OffsetPage<
+  T,
+  TParams extends OffsetPageParams = OffsetPageParams,
+> extends AbstractPage<T, TParams, OffsetPageResponse<T>> {
+  data: T[];
+  offset: number;
+  limit: number;
+  total?: number;
+
+  constructor(args: {
+    params: TParams;
+    response: OffsetPageResponse<T>;
+    loader: (params: TParams) => Promise<OffsetPageResponse<T>>;
+  }) {
+    super(args);
+    this.data = args.response.data ?? [];
+    this.offset = args.response.offset;
+    this.limit = args.response.limit;
+    this.total = args.response.total;
+  }
+
+  /**
+   * All items contained in this page.
+   */
+  get items(): T[] {
+    return this.data;
+  }
+
+  /**
+   * True if this is the last page in the sequence.
+   *
+   * When `last` is true, `next()` will return null.
+   */
+  get last(): boolean {
+    if (this.data.length === 0) {
+      return true;
+    }
+
+    const next = (this.offset ?? 0) + (this.limit ?? 0);
+    if (this.total != null && next >= this.total) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Fetch the next page, or null if there is no next page.
+   */
+  async next(): Promise<this | null> {
+    if (this.last) {
+      return null;
+    }
+
+    const next = (this.offset ?? 0) + (this.limit ?? 0);
+    const nextParams: TParams = {
+      ...(this.params as TParams),
+      offset: next,
+    };
+
+    const res = await this.loader(nextParams);
+    const page = new OffsetPage<T, TParams>({
+      params: nextParams,
+      response: res,
+      loader: this.loader,
+    }) as this;
+
+    return page;
+  }
+}

package/src/api/resources/threads/events.ts

@@ -0,0 +1,26 @@
+import type { ThreadStore } from "@/storage";
+import { isPublicEvent } from "@/thread/utils";
+import type { MThreadEvent } from "@/api/models";
+import type { ThreadEvent } from "@/types/thread";
+
+/**
+ * Events subresource for threads.
+ *
+ * Provides access to the event log for an individual thread, filtered down to
+ * events that make sense to surface to callers (messages, tool calls/results, etc.).
+ */
+export class RThreadEvents {
+  constructor(private readonly store: ThreadStore) {}
+
+  /**
+   * List events for a thread.
+   *
+   * Returns only public events – internal system events are filtered out.
+   *
+   * @param tid - Thread ID
+   */
+  async list(tid: string): Promise<MThreadEvent[]> {
+    const events: ThreadEvent[] = await this.store.history(tid);
+    return events.filter(isPublicEvent).map((e) => e as MThreadEvent);
+  }
+}

package/src/api/resources/threads/index.ts

@@ -0,0 +1,9 @@
+export { RThreads } from "./threads";
+export { RThreadEvents } from "./events";
+export type {
+  RThreadsListParams,
+  RThreadGetOptions,
+  RThreadHistoryParams,
+  RThreadCreateParams,
+  RThreadUpdateParams,
+} from "./types";

package/src/api/resources/threads/threads.ts

@@ -0,0 +1,256 @@
+import type {
+  ThreadStore,
+  ThreadListOptions,
+  ThreadHistoryOptions,
+} from "@/storage";
+import type { ThreadEvent } from "@/types/thread";
+import { isPublicEvent } from "@/thread/utils";
+import { Context } from "@/context";
+import { randomID } from "@kernl-sdk/shared/lib";
+import { RUNNING } from "@kernl-sdk/protocol";
+
+import type { MThread, MThreadEvent } from "@/api/models";
+import { CursorPage, type CursorPageResponse } from "@/api/pagination/cursor";
+
+import { RThreadEvents } from "./events";
+import type {
+  RThreadCreateParams,
+  RThreadGetOptions,
+  RThreadHistoryParams,
+  RThreadsListParams,
+  RThreadUpdateParams,
+} from "./types";
+import { MThreadCodec, ThreadsFilterCodec, ThreadsOrderCodec } from "./utils";
+
+/**
+ * Threads resource.
+ *
+ * Provides a structured API for listing, inspecting, and deleting threads.
+ */
+export class RThreads {
+  readonly events: RThreadEvents;
+
+  constructor(private readonly store: ThreadStore) {
+    this.events = new RThreadEvents(store);
+  }
+
+  /**
+   * Get a single thread by ID.
+   *
+   * When `options.history` is set, the returned thread will include a
+   * `history` field containing public events for that thread.
+   */
+  async get(tid: string, options?: RThreadGetOptions): Promise<MThread | null> {
+    const thread = await this.store.get(tid);
+    if (!thread) return null;
+
+    const model = MThreadCodec.encode(thread);
+
+    if (options?.history) {
+      const historyParams =
+        options.history === true ? undefined : options.history;
+      const history = await this.history(tid, historyParams);
+      model.history = history; // attach history lazily so callers can opt-in.
+    }
+
+    return model;
+  }
+
+  /**
+   * Create a new thread.
+   */
+  async create(params: RThreadCreateParams): Promise<MThread> {
+    const now = new Date();
+    const tid = params.tid ?? `tid_${randomID()}`;
+    const namespace = params.namespace ?? "kernl";
+
+    // merge caller-supplied metadata with optional title
+    const baseMetadata: Record<string, unknown> = {
+      ...(params.metadata ?? {}),
+    };
+
+    if (params.title !== undefined) {
+      const trimmed = params.title.trim();
+      if (trimmed) {
+        baseMetadata.title = trimmed;
+      } else {
+        delete baseMetadata.title;
+      }
+    }
+
+    const metadata: Record<string, unknown> | null =
+      Object.keys(baseMetadata).length > 0 ? baseMetadata : null;
+
+    const thread = await this.store.insert({
+      id: tid,
+      namespace,
+      agentId: params.agentId,
+      model: `${params.model.provider}/${params.model.modelId}`,
+      context: params.context,
+      parentTaskId: params.parentTaskId ?? null,
+      metadata,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    return MThreadCodec.encode(thread);
+  }
+
+  /**
+   * List threads with optional filtering and cursor-based pagination.
+   *
+   * @example
+   * ```ts
+   * const threads = await kernl.threads.list({ limit: 20 });
+   *
+   * for await (const thread of threads) {
+   *   console.log(thread.tid);
+   * }
+   * ```
+   */
+  async list(
+    params: RThreadsListParams = {},
+  ): Promise<CursorPage<MThread, RThreadsListParams>> {
+    const loader = async (
+      p: RThreadsListParams,
+    ): Promise<CursorPageResponse<MThread>> => {
+      const offset = p.cursor ? Number(p.cursor) : 0;
+      const limit = p.limit;
+      const effectiveLimit = limit !== undefined ? limit + 1 : undefined;
+
+      const filter = ThreadsFilterCodec.encode(p);
+      const order = ThreadsOrderCodec.encode(p.order);
+
+      const options: ThreadListOptions = {
+        filter,
+        order,
+        limit: effectiveLimit,
+        offset,
+      };
+
+      const threads = await this.store.list(options);
+
+      if (limit === undefined) {
+        // No limit requested → treat as a single, non-paginated page.
+        const data = threads.map((t) => MThreadCodec.encode(t));
+        return {
+          data,
+          next: null,
+          last: true,
+        };
+      }
+
+      const hasExtra = threads.length > limit;
+      const pageThreads = hasExtra ? threads.slice(0, limit) : threads;
+      const data = pageThreads.map((t) => MThreadCodec.encode(t));
+
+      const nextOffset = offset + data.length;
+      const last = !hasExtra || data.length === 0;
+      const next = last ? null : String(nextOffset);
+
+      return { data, next, last };
+    };
+
+    const response = await loader(params);
+
+    return new CursorPage<MThread, RThreadsListParams>({
+      params,
+      response,
+      loader,
+    });
+  }
+
+  /**
+   * Delete a thread and all associated events.
+   */
+  async delete(tid: string): Promise<void> {
+    await this.store.delete(tid);
+  }
+
+  /**
+   * Convenience wrapper around `events.list()` for fetching a thread's history.
+   *
+   * History is returned in descending sequence order by default (latest first).
+   */
+  async history(
+    tid: string,
+    params?: RThreadHistoryParams,
+  ): Promise<MThreadEvent[]> {
+    const opts: ThreadHistoryOptions = {
+      after: params?.after,
+      limit: params?.limit,
+      order: params?.order ?? "desc",
+      kinds: params?.kinds,
+    };
+
+    const events: ThreadEvent[] = await this.store.history(tid, opts);
+    return events.filter(isPublicEvent).map((e) => e as MThreadEvent);
+  }
+
+  /**
+   * Update mutable thread fields.
+   *
+   * Currently only supports updating the human-readable `title`, which is
+   * stored in thread metadata as `metadata.title`.
+   */
+  async update(
+    tid: string,
+    patch: RThreadUpdateParams,
+  ): Promise<MThread | null> {
+    const current = await this.store.get(tid);
+    if (!current) return null;
+
+    // Prevent context mutation while the thread is running.
+    if (patch.context !== undefined && current.state === RUNNING) {
+      throw new Error("Cannot update thread context while thread is running");
+    }
+
+    // build context patch
+    let contextPatch: Context<unknown> | undefined;
+    if ("context" in patch) {
+      const nextContextValue =
+        patch.context === null
+          ? {}
+          : (patch.context ?? current.context.context);
+      contextPatch = new Context(
+        current.namespace,
+        nextContextValue as unknown,
+      );
+    }
+
+    // build metadata base according to caller intent
+    let metadata: Record<string, unknown>;
+    if ("metadata" in patch) {
+      if (patch.metadata === null) {
+        metadata = {};
+      } else if (patch.metadata === undefined) {
+        metadata = current.metadata ? { ...current.metadata } : {};
+      } else {
+        metadata = { ...patch.metadata };
+      }
+    } else {
+      metadata = current.metadata ? { ...current.metadata } : {};
+    }
+
+    // apply title overlay on top of metadata
+    if ("title" in patch) {
+      const value = patch.title;
+      const trimmed =
+        typeof value === "string" ? value.trim() : (value ?? undefined);
+
+      if (!trimmed) {
+        delete metadata.title; // clear title
+      } else {
+        metadata.title = trimmed;
+      }
+    }
+
+    const nextMetadata = Object.keys(metadata).length > 0 ? metadata : null;
+
+    const updated = await this.store.update(tid, {
+      ...(contextPatch ? { context: contextPatch } : {}),
+      metadata: nextMetadata,
+    });
+    return MThreadCodec.encode(updated);
+  }
+}

package/src/api/resources/threads/types.ts

@@ -0,0 +1,143 @@
+import type { ThreadState } from "@/types/thread";
+import type { SortOrder } from "@/storage";
+import type { CursorPageParams } from "@/api/pagination/cursor";
+
+export interface RThreadHistoryParams {
+  /**
+   * Only return events with seq greater than this value.
+   */
+  after?: number;
+
+  /**
+   * Maximum number of events to return.
+   */
+  limit?: number;
+
+  /**
+   * Sort order by sequence number.
+   *
+   * Defaults to `"desc"` so callers see the latest events first.
+   */
+  order?: "asc" | "desc";
+
+  /**
+   * Restrict history to specific event kinds, e.g. `["message", "tool-result"]`.
+   */
+  kinds?: string[];
+}
+
+export interface RThreadsListParams extends CursorPageParams {
+  namespace?: string;
+  agentId?: string;
+  state?: ThreadState | ThreadState[];
+  parentTaskId?: string;
+
+  /**
+   * Only include threads created after this timestamp.
+   */
+  after?: Date;
+
+  /**
+   * Only include threads created before this timestamp.
+   */
+  before?: Date;
+
+  order?: {
+    createdAt?: SortOrder;
+    updatedAt?: SortOrder;
+  };
+}
+
+export interface RThreadGetOptions {
+  /**
+   * Include the thread's event history on the returned model.
+   *
+   * - `true` will fetch history with default options (latest-first).
+   * - An object lets you override history options (limit, kinds, order, etc.).
+   *
+   * This is equivalent to calling `kernl.threads.history(tid, opts)` and
+   * attaching the result to `thread.history`.
+   */
+  history?: true | RThreadHistoryParams;
+}
+
+/**
+ * Parameters for creating a new thread via the public Threads resource.
+ *
+ * Note: low-level API requires explicit agent + model. For most callers,
+ * prefer the agent-scoped helpers (agent.threads.create) which infer these.
+ */
+export interface RThreadCreateParams {
+  /**
+   * Owning agent id for the new thread.
+   */
+  agentId: string;
+
+  /**
+   * Optional explicit thread id.
+   *
+   * If omitted, a new id will be generated.
+   */
+  tid?: string;
+
+  /**
+   * Logical namespace to create the thread in.
+   *
+   * Defaults to `"kernl"` when not provided.
+   */
+  namespace?: string;
+
+  /**
+   * Optional human-readable title for the thread.
+   */
+  title?: string;
+
+  /**
+   * Initial context object for the thread.
+   */
+  context?: Record<string, unknown>;
+
+  /**
+   * Optional parent task id that spawned this thread, if any.
+   */
+  parentTaskId?: string | null;
+  /**
+   * Language model backing this thread.
+   */
+  model: {
+    provider: string;
+    modelId: string;
+  };
+
+  /**
+   * Arbitrary JSON-serializable metadata to attach to the thread.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Patch for updating caller-owned thread fields.
+ *
+ * Semantics for all fields:
+ * - `undefined` → leave the field unchanged
+ * - value (`object` / `string` / etc.) → replace the field
+ * - `null` → clear the field (for `title`, clears `metadata.title`)
+ */
+export interface RThreadUpdateParams {
+  /**
+   * Thread context object.
+   */
+  context?: Record<string, unknown> | null;
+
+  /**
+   * Arbitrary metadata bag attached to the thread.
+   */
+  metadata?: Record<string, unknown> | null;
+
+  /**
+   * Human-readable title (stored in `metadata.title`).
+   */
+  title?: string | null;
+}
+
+

package/src/api/resources/threads/utils.ts

@@ -0,0 +1,104 @@
+import { UnimplementedError, type Codec } from "@kernl-sdk/shared/lib";
+
+import type { Thread } from "@/thread";
+import type { ThreadFilter, ThreadListOptions } from "@/storage";
+import type { MThread } from "@/api/models";
+import type { RThreadsListParams } from "./types";
+
+/**
+ * Converts an internal `Thread` runtime instance into an `MThread` model.
+ */
+export const MThreadCodec: Codec<Thread, MThread> = {
+  encode(thread: Thread): MThread {
+    const rawTitle = thread.metadata?.title;
+    const title = typeof rawTitle === "string" ? rawTitle : null;
+
+    return {
+      tid: thread.tid,
+      namespace: thread.namespace,
+      agentId: thread.agent.id,
+      title,
+      model: {
+        provider: thread.model.provider,
+        modelId: thread.model.modelId,
+      },
+      context: thread.context.context as Record<string, unknown>,
+      parentTaskId: thread.parent?.id ?? null,
+      state: thread.state,
+      createdAt: thread.createdAt,
+      updatedAt: thread.updatedAt,
+    };
+  },
+
+  decode(_model: MThread): Thread {
+    throw new UnimplementedError();
+  },
+};
+
+/**
+ * Converts `RThreadsListParams` into a `ThreadFilter` for the store.
+ */
+export const ThreadsFilterCodec: Codec<
+  RThreadsListParams,
+  ThreadFilter | undefined
+> = {
+  encode(params: RThreadsListParams): ThreadFilter | undefined {
+    const filter: ThreadFilter = {};
+
+    if (params.namespace !== undefined) {
+      filter.namespace = params.namespace;
+    }
+    if (params.state !== undefined) {
+      filter.state = params.state;
+    }
+    if (params.agentId !== undefined) {
+      filter.agentId = params.agentId;
+    }
+    if (params.parentTaskId !== undefined) {
+      filter.parentTaskId = params.parentTaskId;
+    }
+    if (params.after !== undefined) {
+      filter.createdAfter = params.after;
+    }
+    if (params.before !== undefined) {
+      filter.createdBefore = params.before;
+    }
+
+    return Object.keys(filter).length > 0 ? filter : undefined;
+  },
+
+  decode(_filter: ThreadFilter | undefined): RThreadsListParams {
+    throw new UnimplementedError();
+  },
+};
+
+/**
+ * Converts list `order` params into `ThreadListOptions["order"]` for the store.
+ */
+export const ThreadsOrderCodec: Codec<
+  RThreadsListParams["order"],
+  ThreadListOptions["order"] | undefined
+> = {
+  encode(
+    order: RThreadsListParams["order"],
+  ): ThreadListOptions["order"] | undefined {
+    if (!order) return undefined;
+
+    const result: NonNullable<ThreadListOptions["order"]> = {};
+
+    if (order.createdAt !== undefined) {
+      result.createdAt = order.createdAt;
+    }
+    if (order.updatedAt !== undefined) {
+      result.updatedAt = order.updatedAt;
+    }
+
+    return Object.keys(result).length > 0 ? result : undefined;
+  },
+
+  decode(
+    _order: ThreadListOptions["order"] | undefined,
+  ): RThreadsListParams["order"] {
+    throw new UnimplementedError();
+  },
+};