@zaly/agent 0.0.3

package/dist/session-Ds5nJz5A.d.mts

@@ -0,0 +1,346 @@
+import { Emitter } from "@zaly/shared";
+import { Message, ReasoningEffort } from "@zaly/ai";
+//#region src/session/types.d.ts
+/** A single node in the session DAG. Same shape on disk (JSONL) as in
+ *  memory — what we persist *is* what we navigate. Session settings live ONLY on
+ *  `session-settings` nodes as a full snapshot of the cumulative session
+ *  settings at that point. Other node types are pure markers / payload —
+ *  consumers reading "the settings as of node X" use `SessionNodeView`,
+ *  which decorates raw nodes with cumulative settings computed by `Session`'s
+ *  chain-walk forward pass. */
+type SessionN = {
+  uuid: string;
+  /** Absent only on the very first node (`session-start`). */
+  parentUuid?: string;
+  /** Wall-clock millisecond timestamp when the node was created. */
+  ts: number;
+} & ({
+  type: "session-start";
+} | {
+  type: "session-resume";
+} | {
+  type: "session-settings";
+  settings: SessionSettings;
+} | {
+  type: "message";
+  message: Message;
+} | {
+  type: "mask-checkpoint";
+  threshold: number;
+  messageId: string;
+} | {
+  type: "compact";
+  /** Whether the loop kicked off compaction itself or the user did. */
+  trigger: "manual" | "auto";
+  /** Last known cumulative input+output tokens at compaction time. */
+  preTokens?: number;
+  /** How long the compactor took, ms. */
+  durationMs?: number;
+  /** Number of message from before compaction that will be preserved */
+  tail: number;
+  /** Frozen summary message that becomes the head of the active
+   *  chain reconstruction. The full Message (not just text) so the
+   *  walker stays generic and future format changes don't require
+   *  migrating old compact nodes. */
+  summary: Message<"system">;
+});
+type SessionNodeType = SessionN["type"];
+type MaskCheckpoint = {
+  messageId: string;
+  threshold: number;
+};
+type SessionMessage = Message & {
+  ts: number;
+  id: string;
+};
+type SessionNode<T extends SessionNodeType = SessionNodeType> = Extract<SessionN, {
+  type: T;
+}>;
+/** A `SessionNode` decorated with the cumulative settings as of that
+ *  node's position in the chain. Returned by `Session.node()` and
+ *  `Session#chain` — consumers always see a defined `settings`. */
+type SessionNodeView = SessionNode & {
+  settings: SessionSettings;
+};
+type SessionView = {
+  messages: Message[];
+  nodes: Map<string, SessionNodeView>;
+  compact?: SessionNode<"compact">;
+  maskCheckpoint?: MaskCheckpoint;
+};
+type SessionSettings = {
+  version?: number;
+  sessionId?: string;
+  cwd?: string;
+  workspace?: string;
+  modelId?: string;
+  reasoning?: ReasoningEffort;
+};
+type SessionUpdate = Omit<SessionSettings, "version" | "sessionId">;
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+type PartialNode = DistributiveOmit<SessionNode, "parentUuid" | "uuid" | "ts">;
+/** Events a `Session` emits when its state changes. Subscribers fire
+ *  synchronously; throws are routed to `onEmitError`. */
+type SessionEvents = {
+  node: {
+    node: SessionNode;
+  };
+  navigate: {
+    head: string | undefined;
+    messages: readonly Message[];
+  };
+  compact: {
+    node: SessionNode<"compact">;
+  };
+  cwd: {
+    cwd: string;
+    prev?: string;
+  };
+  model: {
+    model: string;
+    prev?: string;
+  };
+  reasoning: {
+    effort: ReasoningEffort;
+    prev?: ReasoningEffort;
+  };
+  "session-start": {};
+  "session-resume": {};
+};
+type SessionOptions<T extends SessionStore = SessionStore> = {
+  store?: T;
+  /** JSONL file to persist the session to. If the file exists, its
+   *  records are read into the DAG before any `add()` calls; either way
+   *  the session opens it in append mode so subsequent commits land on
+   *  disk in real time. Omit for in-memory sessions. */
+  path?: string;
+  /** Per-session directory for artifacts produced during this session —
+   *  bash command logs (when output exceeds the inline cap), subagent
+   *  traces, cached attachments, and any other side-channel data tools
+   *  need to write somewhere session-scoped. */
+  dir?: string;
+  /** Initial session settings. Only used to fill in missing fields in the
+   * session's first `session-settings` node; */
+  defaults?: Omit<SessionSettings, "version">;
+};
+type SessionInit<T extends SessionStore = SessionStore> = SessionOptions & {
+  /** Storage backend. Required — `Session.load()` picks the right
+   *  store based on options; direct construction passes one explicitly. */
+  store: T;
+};
+//#endregion
+//#region src/session/store.d.ts
+/**
+ * Storage backend for a `Session`'s DAG.
+ *
+ * The store is the source of truth for nodes. `Session` reads through
+ * the store for chain walks, and writes new nodes via `write()`.
+ *
+ * Implementations:
+ *   - `MemoryStore` — `Map<uuid, SessionNode>`, no persistence. Used
+ *     by tests and ephemeral / in-process sessions.
+ *   - `JsonlStore` — append-only JSONL file. Eager-loads all records on
+ *     `load()`; future versions may add lazy reads + LRU caching.
+ *
+ * Async by design — even `get()` may involve I/O for backends that don't
+ * cache the full DAG in memory. Callers that need synchronous reads
+ * should pre-warm via `Session`'s chain walk (which populates Session's
+ * own caches as it goes).
+ *
+ * `root` is the most recently appended node. Loading a store sets `root`
+ * from the last persisted record. Writes advance `root` synchronously
+ * (the in-memory state must reflect the append before `write()` resolves)
+ * so subsequent `root` reads see the new node — even if the underlying
+ * I/O completes asynchronously.
+ */
+interface SessionStore {
+  /** The most recently appended node — drives chain walks. Undefined
+   *  for an empty store. */
+  readonly root: SessionNode | undefined;
+  /** Lookup by uuid. Returns undefined for unknown ids. */
+  get: (id: string) => Promise<SessionNode | undefined>;
+  /** Append a node. Becomes the new `root`. The in-memory state must
+   *  reflect the append synchronously (so a follow-up `root` read sees
+   *  it) even when underlying I/O is still in flight. */
+  write: (node: SessionNode) => Promise<void>;
+  /** Optional flush + cleanup hook — called by `Session.close()`. */
+  close?: () => Promise<void>;
+  /** Optional bulk iterator for the full DAG — used by `/tree` UI and
+   *  the masker's full-history scans. Backends with lazy reads can
+   *  override with a more efficient bulk-scan implementation. */
+  all?: () => Iterable<SessionNode> | AsyncIterable<SessionNode>;
+}
+//#endregion
+//#region src/session/jsonl.d.ts
+/**
+ * JSONL-backed `SessionStore` — append-only file, one record per line.
+ *
+ * Current implementation reads the entire file on `load()` and keeps the
+ * full DAG in memory. Future optimizations (lazy reads with offset
+ * index, LRU cache for huge sessions) can land behind this same
+ * interface without changing `Session`.
+ *
+ * Crash tolerance: a truncated last line (interrupted mid-write) is
+ * silently dropped; any other JSON parse error mid-file throws so real
+ * corruption surfaces loudly.
+ */
+declare class JsonlStore implements SessionStore {
+  #private;
+  readonly path: string;
+  constructor(path: string);
+  /** Load + open: hydrate the DAG from `path` (when the file exists),
+   *  then open the writer in append mode. New nodes land on disk as
+   *  they're committed. */
+  static load(path: string): Promise<JsonlStore>;
+  get root(): SessionNode | undefined;
+  get(id: string): Promise<SessionNode | undefined>;
+  write(node: SessionNode): Promise<void>;
+  close(): Promise<void>;
+  all(): AsyncIterable<SessionNode>;
+}
+declare class JsonlReader<T> {
+  #private;
+  readonly path: string;
+  constructor(path: string);
+  private generator;
+  next(): Promise<T | undefined>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/session/memory.d.ts
+/**
+ * In-memory `SessionStore` — a `Map<uuid, SessionNode>` plus a `root`
+ * pointer. No persistence. Construction takes optional initial nodes
+ * for tests, replay tools, and the Claude session importer.
+ */
+declare class MemoryStore implements SessionStore {
+  #private;
+  constructor(nodes?: Iterable<SessionNode>);
+  get root(): SessionNode | undefined;
+  get(id: string): Promise<SessionNode | undefined>;
+  write(node: SessionNode): Promise<void>;
+  all(): Iterable<SessionNode>;
+}
+//#endregion
+//#region src/session/session.d.ts
+/**
+ * Conversation primitive. Owns a DAG of message + compaction + meta
+ * nodes via a `SessionStore` backend; the *active* message list is
+ * whatever you get by walking `parentUuid` backwards from the store's
+ * root until you hit a `compact` node (or the start).
+ *
+ * **Meta is snapshot-based.** `session-meta` nodes carry the full
+ * cumulative meta as of their commit time. Other node types (start,
+ * resume, message, compact) don't carry meta — `Session` reconstructs
+ * the cumulative meta at any point by finding the most recent
+ * `session-meta` ancestor in a forward pass over the chain. Public
+ * APIs return `SessionNodeView` (raw node + decorated `meta`).
+ *
+ * Designed so the loop, the persistor, the TUI, and any replay tool
+ * all read from one source of truth and never mutate the DAG behind
+ * each other's backs:
+ *
+ * - **Run loop** (`Agent`) calls `add()` on each new message and
+ *   `compact()` on overflow.
+ * - **TUI** subscribes to the `node` event for streaming render.
+ * - **Persistor** is the `SessionStore` — `MemoryStore` for ephemeral
+ *   sessions, `JsonlStore` for file-backed.
+ *
+ * Construction:
+ *   - Use `await Session.load(opts)` for the recommended path — picks
+ *     the right store (Memory if no path, JSONL if path).
+ *   - For tests / direct embedding, `new Session({ store })` works with
+ *     any pre-built store.
+ */
+declare class Session<T extends SessionStore = SessionStore> extends Emitter<SessionEvents> {
+  #private;
+  protected constructor(opts: SessionInit<T>);
+  /** Recommended one-step path: pick the right store backend, hydrate
+   *  if applicable, return a ready-to-use session.
+   *
+   *  - `path` provided → `JsonlStore` (file-backed, hydrates from disk
+   *    if the file exists, opens for append either way).
+   *  - No `path` → `MemoryStore` (ephemeral, no persistence). */
+  static load<T extends SessionStore = SessionStore>(opts: SessionOptions<T> & {
+    store: T;
+  }): Promise<Session<T>>;
+  static load(opts: SessionOptions & {
+    path: string;
+  }): Promise<Session<JsonlStore>>;
+  static load(opts?: SessionOptions & {}): Promise<Session<MemoryStore>>;
+  private static create;
+  /** Efficiently fetch the most recent user message by walking backward until we hit
+   * a user message, without reconstructing the full chain. Useful for a session picker. */
+  static lastMessage(opts?: SessionOptions): Promise<Message<"user"> | undefined>;
+  /** Active conversation — chain from current head back to the most
+   *  recent compact (exclusive), in chronological order. This is what
+   *  the agent sees on the next request. */
+  get messages(): readonly Message[];
+  get maskCheckpoint(): MaskCheckpoint | undefined;
+  get id(): string;
+  get dir(): string;
+  get path(): string | undefined;
+  get started(): boolean;
+  /** Current session settings, merged with defaults. */
+  get settings(): SessionSettings;
+  update(settings: SessionUpdate, opts?: {
+    force?: boolean;
+  }): Promise<string>;
+  /** Explicitly mark the session as started — writes a `session-start`
+   *  marker on a fresh session, `session-resume` on a hydrated one.
+   *  Idempotent; subsequent calls are no-ops. Optional `meta` is
+   *  applied via `update()` after the marker lands. */
+  start(settings?: SessionUpdate): Promise<string | undefined>;
+  /** Look up the decorated view for a node id — raw node plus the
+   *  cumulative meta as of that node's position. Returns the
+   *  message-typed view, or `undefined` if the id doesn't refer to a
+   *  message in this session. */
+  node(id?: string | Message): Promise<(SessionNodeView & {
+    type: "message";
+  }) | undefined>;
+  /** Current head uuid — the root of the store, which is the most
+   *  recently appended node. */
+  get head(): string | undefined;
+  /** Full DAG iterator — backed by `store.all()`. Yields raw nodes
+   *  (no meta decoration). */
+  nodes(): Iterable<SessionNode> | AsyncIterable<SessionNode>;
+  get root(): SessionNode | undefined;
+  /** Append a message. The new node is parented to the current head,
+   *  head advances, and a `node` event fires. Optional `meta` carries
+   *  usage / model / finish info — populate it for assistant turns
+   *  the agent commits after a step. Returns the assigned uuid.
+   *
+   *  If `message.id` / `message.ts` are set (e.g. round-tripped from a
+   *  prior load), they're used as the node's uuid / timestamp; otherwise
+   *  fresh values are generated. The committed message always carries
+   *  both — `m.id === node.uuid` and `m.ts === node.ts`. */
+  add(message: Message): Promise<string>;
+  /** Mark a compaction boundary. Subsequent `add()` calls land after
+   *  this node; their messages form the new active conversation. The
+   *  pre-compact chain stays in the store but is no longer part of
+   *  `messages`. Also commits a fresh `session-meta` snapshot right
+   *  after the compact so post-compact lazy walks always have a nearby
+   *  meta anchor. */
+  compact(opts: {
+    trigger?: "manual" | "auto";
+    preTokens?: number;
+    durationMs?: number;
+    tail: number;
+    summary: Message<"system">;
+  }): Promise<string>;
+  addMaskCheckpoint(opts: MaskCheckpoint): Promise<string>;
+  checkout(uuid: string): Promise<void>;
+  /** Pre-active history of the current chain — messages from before
+   *  the most recent compact (and earlier compacts), in chronological
+   *  order. Useful for TUI scrollback that wants to render context the
+   *  agent itself no longer sees.
+   *
+   *  `limit` truncates from the front (oldest), so the most recent
+   *  history messages always make it through. */
+  history(limit?: number): Promise<readonly Message[]>;
+  /** Flush + close the underlying store. Subsequent writes throw. */
+  close(): Promise<void>;
+}
+//#endregion
+export { SessionStore as a, SessionEvents as c, SessionNode as d, SessionNodeView as f, SessionView as g, SessionUpdate as h, JsonlStore as i, SessionInit as l, SessionSettings as m, MemoryStore as n, MaskCheckpoint as o, SessionOptions as p, JsonlReader as r, PartialNode as s, Session as t, SessionMessage as u };
+//# sourceMappingURL=session-Ds5nJz5A.d.mts.map

package/dist/session-Ds5nJz5A.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-Ds5nJz5A.d.mts","names":[],"sources":["../src/session/types.ts","../src/session/store.ts","../src/session/jsonl.ts","../src/session/memory.ts","../src/session/session.ts"],"mappings":";;;;;;;;;;KAYK;EACH;;EAEA;;EAEA;;EAEI;;EACA;;EACA;EAA0B,UAAU;;EACpC;EAAiB,SAAS;;EAC1B;EAAyB;EAAmB;;EAE5C;;EAEA;;EAEA;;EAEA;;EAEA;;;;;EAKA,SAAS;;KAGV,kBAAkB;KAEX;EAAmB;EAAmB;;KAEtC,iBAAiB;EAAY;EAAY;;KAEzC,YAAY,UAAU,kBAAkB,mBAAmB,QACrE;EACE,MAAM;;;;;KAME,kBAAkB;EAAgB,UAAU;;KAE5C;EACV,UAAU;EACV,OAAO,YAAY;EACnB,UAAU;EACV,iBAAiB;;KAGP;EACV;EACA;EACA;EACA;EACA;EACA,YAAY;;KAGF,gBAAgB,KAAK;KAE5B,iBAAiB,GAAG,UAAU,eAAe,oBAAoB,KAAK,GAAG;KAElE,cAAc,iBAAiB;;;KAM/B;EACV;IAAQ,MAAM;;EACd;IAAY;IAA0B,mBAAmB;;EACzD;IAAW,MAAM;;EAEjB;IAAO;IAAa;;EACpB;IAAS;IAAe;;EACxB;IAAa,QAAQ;IAAiB,OAAO;;EAE7C;EACA;;KAKU,eAAe,UAAU,eAAe;EAClD,QAAQ;;;;;EAKR;;;;;EAKA;;;EAGA,WAAW,KAAK;;KAGN,YAAY,UAAU,eAAe,gBAAgB;;;EAG/D,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;UC7FQ;;;WAGN,MAAM;;EAGf,MAAM,eAAe,QAAQ;;;;EAK7B,QAAQ,MAAM,gBAAgB;;EAG9B,cAAc;;;;EAKd,YAAY,SAAS,eAAe,cAAc;;;;;;;;;;;;;;;;cCvBvC,sBAAsB;;WACxB;EAKT,YAAY;;;;SAQC,KAAK,eAAe,QAAQ;MAmBrC,QAAQ;EAIN,IAAI,aAAa,QAAQ;EAIzB,MAAM,MAAM,cAAc;EAS1B,SAAS;EAIR,OAAO,cAAc;;cAMjB,YAAY;;WAMF;EAArB,YAAqB;UAsBN;EAgCT,QAAQ,QAAQ;EAMhB,SAAK;;;;;;;;;cC3IA,uBAAuB;;EAIlC,YAAY,QAAQ,SAAS;MAUzB,QAAQ;EAIN,IAAI,aAAa,QAAQ;EAIzB,MAAM,MAAM,cAAc;EAK/B,OAAO,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cCoBN,QAAQ,UAAU,eAAe,sBAAsB,QAAQ;;YAYjE,YAAa,MAAM,YAAY;;;;;;;SAe3B,KAAK,UAAU,eAAe,cACzC,MAAM,eAAe;IAAO,OAAO;MAClC,QAAQ,QAAQ;SACN,KAAK,MAAM;IAAmB;MAAiB,QAAQ,QAAQ;SAC/D,KAAK,OAAO,sBAAsB,QAAQ,QAAQ;iBAO1C;;;SAUR,YAAY,OAAM,iBAAsB,QAAQ;;;;MA4BzD,qBAAqB;MAIrB,kBAAkB;MAIlB;MAIA;MAIA;MAIA;;MAKA,YAAY;EAIV,OAAO,UAAU,eAAe;IAAS;MAAoB;;;;;EAe7D,MAAM,WAAW,gBAAgB;;;;;EAcjC,KAAK,cAAc,UAAU,SAAS;IAAoB;;;;MAS5D;;;EAMJ,SAAS,SAAS,eAAe,cAAc;MAI3C,QAAQ;;;;;;;;;;EAeN,IAAI,SAAS,UAAU;;;;;;;EAavB,QAAQ;IACZ;IACA;IACA;IACA;IACA,SAAS;MACP;EAmBE,kBAAkB,MAAM,iBAAiB;EAKzC,SAAS,eAAe;;;;;;;;EAaxB,QAAQ,iBAAiB,iBAAiB;;EAM1C,SAAS"}

package/dist/session.d.mts

@@ -0,0 +1,37 @@
+import { a as SessionStore, c as SessionEvents, d as SessionNode, f as SessionNodeView, g as SessionView, h as SessionUpdate, i as JsonlStore, l as SessionInit, m as SessionSettings, n as MemoryStore, o as MaskCheckpoint, p as SessionOptions, r as JsonlReader, s as PartialNode, t as Session, u as SessionMessage } from "./session-Ds5nJz5A.mjs";
+import { Stats } from "node:fs";
+//#region src/session/manager.d.ts
+type SessionInfo = {
+  /** uuidv7 session id. Absent for non-managed external paths until the
+   *  session is loaded — the file's session-start node carries the
+   *  authoritative id. */
+  id: string;
+  /** Absolute path to the session file. Typically within `zalyPaths.sessions`. */
+  path: string;
+  /** Data directory used for session artifacts */
+  dir: string;
+  /** The session's workspace containing its .zaly/ resources */
+  workspace: string;
+  /** Populated when listing with `sort: true` */
+  mtime?: number;
+  stat?: Stats;
+};
+type SessionFilter = {
+  /** (partial) uuid for a session */
+  id?: string;
+  /** sessions with this workspace */
+  workspace?: string;
+  /** glob pattern matching any workspace sessions */
+  pattern?: string;
+};
+type SessionListOpts = {
+  filter?: string | SessionFilter;
+  sort?: boolean;
+};
+declare function listSessions(opts?: SessionListOpts): Promise<SessionInfo[]>;
+declare function resumeSession(filter: string | SessionFilter): Promise<Session | undefined>;
+declare function loadSession(opts?: Partial<SessionInfo>): Promise<Session>;
+declare function sessionInfo(opts?: Partial<SessionInfo>): SessionInfo;
+//#endregion
+export { JsonlReader, JsonlStore, type MaskCheckpoint, MemoryStore, type PartialNode, Session, type SessionEvents, SessionFilter, SessionInfo, type SessionInit, SessionListOpts, type SessionMessage, type SessionNode, type SessionNodeView, type SessionOptions, type SessionSettings, type SessionStore, type SessionUpdate, type SessionView, listSessions, loadSession, resumeSession, sessionInfo };
+//# sourceMappingURL=session.d.mts.map

package/dist/session.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.mts","names":[],"sources":["../src/session/manager.ts"],"mappings":";;;KAUY;;;;EAIV;;EAEA;;EAEA;;EAEA;;EAEA;EACA,OAAO;;KAGG;;EAEV;;EAEA;;EAEA;;KAGU;EACV,kBAAkB;EAClB;;iBAcoB,aAAa,OAAM,kBAAoB,QAAA;iBAyCvC,cAAc,iBAAiB,gBAAgB,QAAQ;iBAKvD,YAAY,OAAM,QAAQ,eAAoB,QAAQ;iBAc5D,YAAY,OAAM,QAAQ,eAAoB"}

package/dist/session.mjs

@@ -0,0 +1,106 @@
+import { n as isUuidv7Like, r as uuidv7 } from "./uuid-ByXP5SO5.mjs";
+import { n as JsonlStore, t as JsonlReader } from "./jsonl-Dw_VBp46.mjs";
+import { r as MemoryStore, t as Session } from "./session-CUUdWFC5.mjs";
+import { decodePath, encodePath, normPath, safeStatAsync } from "@zaly/shared";
+import { basename, dirname, join, relative } from "pathe";
+import { glob } from "@zaly/shared/glob";
+import { mkdir, stat } from "node:fs/promises";
+import { zalyPaths } from "@zaly/shared/paths";
+//#region src/session/manager.ts
+async function toFilter(filter) {
+	if (isUuidv7Like(filter)) return { id: filter };
+	if ((await safeStatAsync(filter))?.isDirectory()) return { workspace: filter };
+	return { pattern: filter };
+}
+function workspaceSlug(workspace) {
+	return encodePath(normPath(workspace));
+}
+async function listSessions(opts = {}) {
+	const filter = typeof opts.filter === "string" ? await toFilter(opts.filter) : opts.filter ?? {};
+	let slug = filter.workspace ? workspaceSlug(filter.workspace) : void 0;
+	slug ??= filter.pattern ? `*${filter.pattern}*` : void 0;
+	slug ??= "*";
+	const isGlob = slug.includes("*");
+	const root = isGlob ? zalyPaths.sessions : join(zalyPaths.sessions, slug);
+	const pattern = [];
+	if (isGlob) pattern.push(slug);
+	if (filter.id) pattern.push(filter.id.length >= 36 ? filter.id.slice(0, 36) : `${filter.id}*`);
+	else pattern.push("*");
+	pattern.push("session.jsonl");
+	const paths = glob(pattern.join("/"), {
+		cwd: root,
+		depth: pattern.length,
+		ignore: false,
+		type: "file"
+	});
+	const ret = [];
+	for await (const rel of paths) {
+		const path = normPath(root, rel);
+		ret.push(sessionInfo({ path }));
+	}
+	if (!opts.sort) return ret;
+	return (await Promise.all(ret.map(async (session) => {
+		const s = await stat(session.path).catch(() => void 0);
+		session.mtime = s?.mtimeMs;
+		session.stat = s;
+		return session;
+	}))).filter((e) => e.mtime !== void 0).toSorted((a, b) => b.mtime - a.mtime);
+}
+async function resumeSession(filter) {
+	const list = await listSessions({
+		filter,
+		sort: true
+	});
+	return list.length === 0 ? void 0 : loadSession(list[0]);
+}
+async function loadSession(opts = {}) {
+	const info = sessionInfo(opts);
+	await mkdir(info.dir, { recursive: true });
+	return Session.load({
+		defaults: {
+			cwd: normPath(),
+			sessionId: info.id,
+			workspace: info.workspace
+		},
+		dir: info.dir,
+		path: info.path
+	});
+}
+function sessionInfo(opts = {}) {
+	if (opts.path && !relative(zalyPaths.sessions, opts.path).startsWith("..")) {
+		const path = normPath(opts.path);
+		const dir = normPath(opts.dir ?? dirname(path));
+		const id = opts.id ?? basename(dir);
+		const slug = basename(dirname(dir));
+		return {
+			dir,
+			id,
+			path,
+			workspace: normPath(opts.workspace ?? decodePath(slug))
+		};
+	} else if (opts.path) {
+		const path = normPath(opts.path);
+		const dir = normPath(opts.dir ?? dirname(path));
+		const workspace = normPath(opts.workspace);
+		return {
+			dir,
+			id: uuidv7(),
+			path,
+			workspace
+		};
+	}
+	const workspace = normPath(opts.workspace);
+	const slug = workspaceSlug(workspace);
+	const id = opts.id ?? uuidv7();
+	const dir = opts.dir ? normPath(opts.dir) : normPath(zalyPaths.sessions, slug, id);
+	return {
+		dir,
+		id,
+		path: normPath(dir, "session.jsonl"),
+		workspace
+	};
+}
+//#endregion
+export { JsonlReader, JsonlStore, MemoryStore, Session, listSessions, loadSession, resumeSession, sessionInfo };
+
+//# sourceMappingURL=session.mjs.map

package/dist/session.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.mjs","names":[],"sources":["../src/session/manager.ts"],"sourcesContent":["import type { Stats } from \"node:fs\"\n\nimport { decodePath, encodePath, normPath, safeStatAsync } from \"@zaly/shared\"\nimport { glob } from \"@zaly/shared/glob\"\nimport { zalyPaths } from \"@zaly/shared/paths\"\nimport { mkdir, stat } from \"node:fs/promises\"\nimport { basename, dirname, join, relative } from \"pathe\"\nimport { isUuidv7Like, uuidv7 } from \"../utils/uuid.ts\"\nimport { Session } from \"./session.ts\"\n\nexport type SessionInfo = {\n  /** uuidv7 session id. Absent for non-managed external paths until the\n   *  session is loaded — the file's session-start node carries the\n   *  authoritative id. */\n  id: string\n  /** Absolute path to the session file. Typically within `zalyPaths.sessions`. */\n  path: string\n  /** Data directory used for session artifacts */\n  dir: string\n  /** The session's workspace containing its .zaly/ resources */\n  workspace: string\n  /** Populated when listing with `sort: true` */\n  mtime?: number\n  stat?: Stats\n}\n\nexport type SessionFilter = {\n  /** (partial) uuid for a session */\n  id?: string\n  /** sessions with this workspace */\n  workspace?: string\n  /** glob pattern matching any workspace sessions */\n  pattern?: string\n}\n\nexport type SessionListOpts = {\n  filter?: string | SessionFilter\n  sort?: boolean\n}\n\nasync function toFilter(filter: string): Promise<SessionFilter> {\n  if (isUuidv7Like(filter)) return { id: filter }\n  const s = await safeStatAsync(filter)\n  if (s?.isDirectory()) return { workspace: filter }\n  return { pattern: filter }\n}\n\nfunction workspaceSlug(workspace?: string) {\n  return encodePath(normPath(workspace))\n}\n\nexport async function listSessions(opts: SessionListOpts = {}) {\n  const filter = typeof opts.filter === \"string\" ? await toFilter(opts.filter) : (opts.filter ?? {})\n  let slug = filter.workspace ? workspaceSlug(filter.workspace) : undefined\n  slug ??= filter.pattern ? `*${filter.pattern}*` : undefined\n  slug ??= \"*\"\n  const isGlob = slug.includes(\"*\")\n  const root = isGlob ? zalyPaths.sessions : join(zalyPaths.sessions, slug)\n\n  const pattern: string[] = []\n  if (isGlob) pattern.push(slug)\n\n  if (filter.id) pattern.push(filter.id.length >= 36 ? filter.id.slice(0, 36) : `${filter.id}*`)\n  else pattern.push(\"*\")\n\n  pattern.push(\"session.jsonl\")\n\n  const paths = glob(pattern.join(\"/\"), {\n    cwd: root,\n    depth: pattern.length,\n    ignore: false,\n    type: \"file\",\n  })\n  const ret: SessionInfo[] = []\n  for await (const rel of paths) {\n    const path = normPath(root, rel)\n    ret.push(sessionInfo({ path }))\n  }\n  if (!opts.sort) return ret\n  const stats = await Promise.all(\n    ret.map(async (session) => {\n      const s = await stat(session.path).catch(() => undefined)\n      session.mtime = s?.mtimeMs\n      session.stat = s\n      return session\n    })\n  )\n  return stats\n    .filter((e): e is SessionInfo & { mtime: number } => e.mtime !== undefined)\n    .toSorted((a, b) => b.mtime - a.mtime) // newest first\n}\n\nexport async function resumeSession(filter: string | SessionFilter): Promise<Session | undefined> {\n  const list = await listSessions({ filter, sort: true })\n  return list.length === 0 ? undefined : loadSession(list[0])\n}\n\nexport async function loadSession(opts: Partial<SessionInfo> = {}): Promise<Session> {\n  const info = sessionInfo(opts)\n  await mkdir(info.dir, { recursive: true })\n  return Session.load({\n    defaults: {\n      cwd: normPath(),\n      sessionId: info.id,\n      workspace: info.workspace,\n    },\n    dir: info.dir,\n    path: info.path,\n  })\n}\n\nexport function sessionInfo(opts: Partial<SessionInfo> = {}): SessionInfo {\n  if (opts.path && !relative(zalyPaths.sessions, opts.path).startsWith(\"..\")) {\n    // Managed session\n    const path = normPath(opts.path)\n    const dir = normPath(opts.dir ?? dirname(path))\n    const id = opts.id ?? basename(dir)\n    const slug = basename(dirname(dir))\n    const workspace = normPath(opts.workspace ?? decodePath(slug))\n    return { dir, id, path, workspace }\n  } else if (opts.path) {\n    // Existing session, but not in a managed location\n    const path = normPath(opts.path)\n    const dir = normPath(opts.dir ?? dirname(path))\n    const workspace = normPath(opts.workspace)\n    return { dir, id: uuidv7(), path, workspace }\n  }\n  // New session\n  const workspace = normPath(opts.workspace) // defaults to cwd\n  const slug = workspaceSlug(workspace)\n  const id = opts.id ?? uuidv7()\n  const dir = opts.dir ? normPath(opts.dir) : normPath(zalyPaths.sessions, slug, id)\n  const path = normPath(dir, \"session.jsonl\")\n  return { dir, id, path, workspace }\n}\n"],"mappings":"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"}

package/dist/subagent-baqzjRMc.mjs

@@ -0,0 +1,136 @@
+import { r as uuidv7 } from "./uuid-ByXP5SO5.mjs";
+import { join } from "pathe";
+import { AiError, defineTool, stringifyContent } from "@zaly/ai";
+import { Type } from "typebox";
+import { tmpdir } from "node:os";
+//#region src/tools/subagent.ts
+const subagentTool = defineTool({
+	name: "subagent",
+	desc: "Spawn a focused subagent with the same model and permissions. Use for tasks that benefit from a clean context window: deep code exploration, multi-step research, or anything where dragging the intermediate steps through your own context would be expensive. The subagent's final answer comes back as the result; full transcript is available at the returned `sessionPath` if you need more detail.",
+	parallel: true,
+	params: Type.Object({
+		description: Type.String({ description: "Short description of what the subagent should do. Shown to the user in the TUI. Keep under ~10 words." }),
+		prompt: Type.String({ description: "System prompt for the subagent — defines its role and constraints. The subagent does NOT inherit your system prompt; spell out what it needs to know." }),
+		task: Type.String({ description: "The actual task the subagent should perform, as if you were sending it as a user message. Be specific about the deliverable." })
+	}),
+	async call(args, ctx) {
+		const parent = ctx.agent;
+		if (!parent) throw new AiError({
+			code: "MISSING_TOOL_CONTEXT",
+			message: "subagent requires an Agent reference on the context (set up by the agent harness)."
+		});
+		const id = uuidv7();
+		const sessionPath = join(tmpdir(), `zaly-subagent-${id}.jsonl`);
+		const startedAt = Date.now();
+		const { Session } = await import("./session-CUUdWFC5.mjs").then((n) => n.n);
+		const child = await parent.child({
+			prompt: [args.prompt],
+			session: await Session.load({ path: sessionPath })
+		});
+		const depth = child.depth;
+		let textBuffer = "";
+		let cursor = 0;
+		let finalResult;
+		let stopReason;
+		child.on("stream-event", ({ event }) => {
+			if (event.type === "text-delta" && typeof event.delta === "string") textBuffer += event.delta;
+		});
+		child.on("stop", ({ kind }) => {
+			stopReason = kind;
+		});
+		child.send({
+			content: args.task,
+			role: "user"
+		});
+		const runDone = child.run().catch((error) => {
+			stopReason = "error";
+			throw error;
+		});
+		const buildMeta = (running) => ({
+			depth,
+			durationMs: Date.now() - startedAt,
+			id,
+			sessionPath,
+			status: running ? "running" : "done",
+			stop: stopReason,
+			usage: {
+				input: child.totalUsage.input,
+				output: child.totalUsage.output
+			}
+		});
+		/** Pull the last assistant text out of the child's session — the
+		*  user-visible "answer." Falls back to whatever's accumulated in the
+		*  text buffer if the assistant hasn't committed a message yet. */
+		const finalText = () => {
+			for (let i = child.messages.length - 1; i >= 0; i--) {
+				const m = child.messages[i];
+				if (m.role !== "assistant") continue;
+				const text = stringifyContent(m.content).trim();
+				if (text !== "") return text;
+			}
+			return textBuffer.trim();
+		};
+		const buildResult = (running) => {
+			if (!running && finalResult) return {
+				...finalResult,
+				running: false
+			};
+			const meta = buildMeta(running);
+			const slice = textBuffer.slice(cursor);
+			cursor = textBuffer.length;
+			const parts = [{
+				data: meta,
+				tag: "subagent",
+				type: "meta"
+			}];
+			if (running) {
+				if (slice !== "") parts.push({
+					text: slice,
+					type: "text"
+				});
+			} else {
+				const answer = finalText();
+				if (answer !== "") parts.push({
+					text: answer,
+					type: "text"
+				});
+			}
+			return {
+				content: parts,
+				isError: false,
+				running
+			};
+		};
+		return {
+			abort: () => {
+				child.stop();
+			},
+			done: runDone.then(async () => {
+				await child.session.close();
+				finalResult = buildResult(false);
+			}, async (error) => {
+				stopReason ??= "error";
+				await child.session.close().catch(() => void 0);
+				const meta = buildMeta(false);
+				const message = error instanceof Error ? error.message : String(error);
+				finalResult = {
+					content: [{
+						data: meta,
+						tag: "subagent",
+						type: "meta"
+					}, {
+						text: `subagent failed: ${message}`,
+						type: "text"
+					}],
+					isError: true
+				};
+			}),
+			hasNew: () => textBuffer.length > cursor,
+			poll: () => buildResult(child.status !== "idle" && child.status !== "paused")
+		};
+	}
+});
+//#endregion
+export { subagentTool };
+
+//# sourceMappingURL=subagent-baqzjRMc.mjs.map