saeeol 1.1.0 → 1.1.1

package/src/util/schema.ts

@@ -0,0 +1,108 @@
+import { Option, Schema, SchemaGetter } from "effect"
+import { zod, ZodOverride } from "./effect-zod"
+
+/**
+ * Integer greater than zero.
+ */
+export const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0))
+
+/**
+ * Integer greater than or equal to zero.
+ */
+export const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+
+/**
+ * Optional public JSON field that can hold explicit `undefined` on the type
+ * side but encodes it as an omitted key, matching legacy `JSON.stringify`.
+ */
+export const optionalOmitUndefined = <S extends Schema.Top>(schema: S) =>
+  Schema.optionalKey(schema).pipe(
+    Schema.decodeTo(Schema.optional(schema), {
+      decode: SchemaGetter.passthrough({ strict: false }),
+      encode: SchemaGetter.transformOptional(Option.filter((value) => value !== undefined)),
+    }),
+    Schema.annotate({ [ZodOverride]: zod(schema).optional() }),
+  )
+
+/**
+ * Strip `readonly` from a nested type. Stand-in for `effect`'s `Types.DeepMutable`
+ * until `effect:core/x228my` ("Types.DeepMutable widens unknown to `{}`") lands.
+ *
+ * The upstream version falls through `unknown` into `{ -readonly [K in keyof T]: ... }`
+ * where `keyof unknown = never`, so `unknown` collapses to `{}`. This local
+ * version gates the object branch on `extends object` (which `unknown` does
+ * not) so `unknown` passes through untouched.
+ *
+ * Primitive bailout matches upstream — without it, branded strings like
+ * `string & Brand<"SessionID">` fall into the object branch and get their
+ * prototype methods walked.
+ *
+ * Tuple branch preserves readonly tuples (e.g. `ConfigPlugin.Spec`'s
+ * `readonly [string, Options]`); the general array branch would otherwise
+ * widen them to unbounded arrays.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type DeepMutable<T> = T extends string | number | boolean | bigint | symbol | Function
+  ? T
+  : T extends readonly [unknown, ...unknown[]]
+    ? { -readonly [K in keyof T]: DeepMutable<T[K]> }
+    : T extends readonly (infer U)[]
+      ? DeepMutable<U>[]
+      : T extends object
+        ? { -readonly [K in keyof T]: DeepMutable<T[K]> }
+        : T
+
+/**
+ * Attach static methods to a schema object. Designed to be used with `.pipe()`:
+ *
+ * @example
+ *   export const Foo = fooSchema.pipe(
+ *     withStatics((schema) => ({
+ *       zero: schema.make(0),
+ *       from: Schema.decodeUnknownOption(schema),
+ *     }))
+ *   )
+ */
+export const withStatics =
+  <S extends object, M extends Record<string, unknown>>(methods: (schema: S) => M) =>
+  (schema: S): S & M =>
+    Object.assign(schema, methods(schema))
+
+/**
+ * Nominal wrapper for scalar types. The class itself is a valid schema —
+ * pass it directly to `Schema.decode`, `Schema.decodeEffect`, etc.
+ *
+ * Overrides `~type.make` on the derived `Schema.Opaque` so `Schema.Schema.Type`
+ * of a field using this newtype resolves to `Self` rather than the underlying
+ * branded phantom. Without that override, passing a class instance to code
+ * typed against `Schema.Schema.Type<FieldSchema>` would require a cast even
+ * though the values are structurally equivalent at runtime.
+ *
+ * @example
+ *   class QuestionID extends Newtype<QuestionID>()("QuestionID", Schema.String) {
+ *     static make(id: string): QuestionID {
+ *       return this.make(id)
+ *     }
+ *   }
+ *
+ *   Schema.decodeEffect(QuestionID)(input)
+ */
+export function Newtype<Self>() {
+  return <const Tag extends string, S extends Schema.Top>(tag: Tag, schema: S) => {
+    abstract class Base {
+      declare readonly _newtype: Tag
+
+      static make(value: Schema.Schema.Type<S>): Self {
+        return value as unknown as Self
+      }
+    }
+
+    Object.setPrototypeOf(Base, schema)
+
+    return Base as unknown as (abstract new (_: never) => { readonly _newtype: Tag }) & {
+      readonly make: (value: Schema.Schema.Type<S>) => Self
+    } & Omit<Schema.Opaque<Self, S, {}>, "make" | "~type.make"> & {
+        readonly "~type.make": Self
+      }
+  }
+}

package/src/util/scrap.ts

@@ -0,0 +1,10 @@
+export const foo: string = "42"
+export const bar: number = 123
+
+export function dummyFunction(): void {
+  console.log("This is a dummy function")
+}
+
+export function randomHelper(): boolean {
+  return Math.random() > 0.5
+}

package/src/util/signal.ts

@@ -0,0 +1,10 @@
+import { latch } from "@saeeol/boxes/latch"
+
+/** One-shot signal (latch wrapper matching original trigger/wait API) */
+export function signal() {
+  const l = latch()
+  return {
+    trigger: l.trip,
+    wait: l.wait,
+  }
+}

package/src/util/timeout.ts

@@ -0,0 +1,13 @@
+export function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  let timeout: NodeJS.Timeout
+  return Promise.race([
+    promise.finally(() => {
+      clearTimeout(timeout)
+    }),
+    new Promise<never>((_, reject) => {
+      timeout = setTimeout(() => {
+        reject(new Error(`Operation timed out after ${ms}ms`))
+      }, ms)
+    }),
+  ])
+}

package/src/util/token.ts

@@ -0,0 +1,3 @@
+export { count as estimate } from "@saeeol/boxes/tokens"
+
+export * as Token from "./token"

package/src/util/update-schema.ts

@@ -0,0 +1,13 @@
+import z from "zod"
+
+export function updateSchema<T extends z.ZodRawShape>(schema: z.ZodObject<T>) {
+  const next = {} as {
+    [K in keyof T]: z.ZodOptional<z.ZodNullable<T[K]>>
+  }
+
+  for (const [k, v] of Object.entries(schema.required().shape) as [keyof T & string, z.ZodTypeAny][]) {
+    next[k] = v.nullable() as unknown as (typeof next)[typeof k]
+  }
+
+  return z.object(next)
+}

package/src/util/which.ts

@@ -0,0 +1,14 @@
+import whichPkg from "which"
+import path from "path"
+import { Global } from "@saeeol/core/global"
+
+export function which(cmd: string, env?: NodeJS.ProcessEnv) {
+  const base = env?.PATH ?? env?.Path ?? process.env.PATH ?? process.env.Path ?? ""
+  const full = base ? base + path.delimiter + Global.Path.bin : Global.Path.bin
+  const result = whichPkg.sync(cmd, {
+    nothrow: true,
+    path: full,
+    pathExt: env?.PATHEXT ?? env?.PathExt ?? process.env.PATHEXT ?? process.env.PathExt,
+  })
+  return typeof result === "string" ? result : null
+}

package/src/util/wildcard.ts

@@ -0,0 +1,20 @@
+import { globMatch, globBest, globStructured } from "@saeeol/boxes/wildcard"
+
+const ci = process.platform === "win32"
+
+/** Glob match — case-insensitive on Windows, matching original behaviour */
+export function match(str: string, pattern: string) {
+  return globMatch(str, pattern, ci)
+}
+
+/** Best match from pattern map */
+export function all(input: string, patterns: Record<string, any>) {
+  return globBest(input, patterns, ci)
+}
+
+/** Structured head/tail match */
+export function allStructured(input: { head: string; tail: string[] }, patterns: Record<string, any>) {
+  return globStructured(input, patterns, ci)
+}
+
+export * as Wildcard from "./wildcard"

package/src/v2/session-entry-stepper.ts

@@ -0,0 +1,262 @@
+import { produce, type WritableDraft } from "immer"
+import { Schema } from "effect"
+import { SessionEvent, Prompt as PromptEvent, Synthetic as SyntheticEvent, Retried as RetriedEvent, Step as StepEvent, Compacted as CompactedEvent, FileAttachment } from "./session-event"
+import { SessionEntry } from "./session-entry"
+
+export type MemoryState = {
+  entries: SessionEntry.Entry[]
+  pending: SessionEntry.Entry[]
+}
+
+export interface Adapter<Result> {
+  readonly getCurrentAssistant: () => SessionEntry.Assistant | undefined
+  readonly updateAssistant: (assistant: SessionEntry.Assistant) => void
+  readonly appendEntry: (entry: SessionEntry.Entry) => void
+  readonly appendPending: (entry: SessionEntry.Entry) => void
+  readonly finish: () => Result
+}
+
+export function memory(state: MemoryState): Adapter<MemoryState> {
+  const activeAssistantIndex = () =>
+    state.entries.findLastIndex((entry) => entry.type === "assistant" && !entry.time.completed)
+
+  return {
+    getCurrentAssistant() {
+      const index = activeAssistantIndex()
+      if (index < 0) return
+      const assistant = state.entries[index]
+      return assistant?.type === "assistant" ? assistant : undefined
+    },
+    updateAssistant(assistant) {
+      const index = activeAssistantIndex()
+      if (index < 0) return
+      const current = state.entries[index]
+      if (current?.type !== "assistant") return
+      state.entries[index] = assistant
+    },
+    appendEntry(entry) {
+      state.entries.push(entry)
+    },
+    appendPending(entry) {
+      state.pending.push(entry)
+    },
+    finish() {
+      return state
+    },
+  }
+}
+
+export function stepWith<Result>(adapter: Adapter<Result>, event: Schema.Schema.Type<typeof SessionEvent.Event>): Result {
+  const currentAssistant = adapter.getCurrentAssistant()
+  type DraftAssistant = WritableDraft<SessionEntry.Assistant>
+  type DraftTool = WritableDraft<SessionEntry.AssistantTool>
+  type DraftText = WritableDraft<SessionEntry.AssistantText>
+  type DraftReasoning = WritableDraft<SessionEntry.AssistantReasoning>
+
+  const latestTool = (assistant: DraftAssistant | undefined, callID?: string) =>
+    assistant?.content.findLast(
+      (item: DraftTool | DraftText | DraftReasoning): item is DraftTool => item.type === "tool" && (callID === undefined || item.callID === callID),
+    )
+
+  const latestText = (assistant: DraftAssistant | undefined) =>
+    assistant?.content.findLast((item: DraftTool | DraftText | DraftReasoning): item is DraftText => item.type === "text")
+
+  const latestReasoning = (assistant: DraftAssistant | undefined) =>
+    assistant?.content.findLast((item: DraftTool | DraftText | DraftReasoning): item is DraftReasoning => item.type === "reasoning")
+
+  SessionEvent.Event.match(event, {
+    prompt: (event) => {
+      const entry = SessionEntry.User.fromEvent(event)
+      if (currentAssistant) {
+        adapter.appendPending(entry)
+        return
+      }
+      adapter.appendEntry(entry)
+    },
+    synthetic: (event) => {
+      adapter.appendEntry(SessionEntry.Synthetic.fromEvent(event))
+    },
+    "step.started": (event) => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            draft.time.completed = event.timestamp
+          }),
+        )
+      }
+      adapter.appendEntry(SessionEntry.Assistant.fromEvent(event))
+    },
+    "step.ended": (event) => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            draft.time.completed = event.timestamp
+            draft.cost = event.cost
+            draft.tokens = event.tokens
+          }),
+        )
+      }
+    },
+    "text.started": () => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            draft.content.push({
+              type: "text",
+              text: "",
+            })
+          }),
+        )
+      }
+    },
+    "text.delta": (event) => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            const match = latestText(draft)
+            if (match) match.text += event.delta
+          }),
+        )
+      }
+    },
+    "text.ended": () => {},
+    "tool.input.started": (event) => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            draft.content.push({
+              type: "tool",
+              callID: event.callID,
+              name: event.name,
+              time: {
+                created: event.timestamp,
+              },
+              state: {
+                status: "pending",
+                input: "",
+              },
+            })
+          }),
+        )
+      }
+    },
+    "tool.input.delta": (event) => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            const match = latestTool(draft, event.callID)
+            // oxlint-disable-next-line no-base-to-string -- event.delta is a Schema.String (runtime string)
+            if (match && match.state.status === "pending") match.state.input += event.delta
+          }),
+        )
+      }
+    },
+    "tool.input.ended": () => {},
+    "tool.called": (event) => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            const match = latestTool(draft, event.callID)
+            if (match) {
+              match.time.ran = event.timestamp
+              match.state = {
+                status: "running",
+                input: event.input,
+              }
+            }
+          }),
+        )
+      }
+    },
+    "tool.success": (event) => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            const match = latestTool(draft, event.callID)
+            if (match && match.state.status === "running") {
+              match.state = {
+                status: "completed",
+                input: match.state.input,
+                output: event.output ?? "",
+                title: event.title,
+                metadata: event.metadata ?? {},
+                attachments: [...(event.attachments ?? [])],
+              }
+            }
+          }),
+        )
+      }
+    },
+    "tool.error": (event) => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            const match = latestTool(draft, event.callID)
+            if (match && match.state.status === "running") {
+              match.state = {
+                status: "error",
+                error: event.error,
+                input: match.state.input,
+                metadata: event.metadata ?? {},
+              }
+            }
+          }),
+        )
+      }
+    },
+    "reasoning.started": () => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            draft.content.push({
+              type: "reasoning",
+              text: "",
+            })
+          }),
+        )
+      }
+    },
+    "reasoning.delta": (event) => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            const match = latestReasoning(draft)
+            if (match) match.text += event.delta
+          }),
+        )
+      }
+    },
+    "reasoning.ended": (event) => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            const match = latestReasoning(draft)
+            if (match) match.text = event.text
+          }),
+        )
+      }
+    },
+    retried: (event) => {
+      if (currentAssistant) {
+        adapter.updateAssistant(
+          produce(currentAssistant, (draft) => {
+            draft.retries = [...(draft.retries ?? []), SessionEntry.AssistantRetry.fromEvent(event)]
+          }),
+        )
+      }
+    },
+    compacted: (event) => {
+      adapter.appendEntry(SessionEntry.Compaction.fromEvent(event))
+    },
+  })
+
+  return adapter.finish()
+}
+
+export function step(old: MemoryState, event: Schema.Schema.Type<typeof SessionEvent.Event>): MemoryState {
+  return produce(old, (draft) => {
+    stepWith(memory(draft as MemoryState), event)
+  })
+}
+
+export * as SessionEntryStepper from "./session-entry-stepper"

package/src/v2/session-entry.ts

@@ -0,0 +1,219 @@
+import { Schema } from "effect"
+import { NonNegativeInt } from "@/util/schema"
+import { SessionEvent, Prompt as PromptEvent, Synthetic as SyntheticEvent, Retried as RetriedEvent, Step as StepEvent, Compacted as CompactedEvent, FileAttachment, RetryError } from "./session-event"
+
+export const ID = SessionEvent.ID
+export type ID = Schema.Schema.Type<typeof ID>
+
+const Base = {
+  id: SessionEvent.ID,
+  metadata: Schema.Record(Schema.String, Schema.Unknown).pipe(Schema.optional),
+  time: Schema.Struct({
+    created: Schema.DateTimeUtc,
+  }),
+}
+
+export class User extends Schema.Class<User>("Session.Entry.User")({
+  ...Base,
+  text: PromptEvent.fields.text,
+  files: PromptEvent.fields.files,
+  agents: PromptEvent.fields.agents,
+  type: Schema.Literal("user"),
+  time: Schema.Struct({
+    created: Schema.DateTimeUtc,
+  }),
+}) {
+  static fromEvent(event: Schema.Schema.Type<typeof PromptEvent>) {
+    return new User({
+      id: event.id,
+      type: "user",
+      metadata: event.metadata,
+      text: event.text,
+      files: event.files,
+      agents: event.agents,
+      time: { created: event.timestamp },
+    })
+  }
+}
+
+export class Synthetic extends Schema.Class<Synthetic>("Session.Entry.Synthetic")({
+  ...SyntheticEvent.fields,
+  ...Base,
+  type: Schema.Literal("synthetic"),
+}) {
+  static fromEvent(event: Schema.Schema.Type<typeof SyntheticEvent>) {
+    return new Synthetic({
+      ...event,
+      time: { created: event.timestamp },
+    })
+  }
+}
+
+export class ToolStatePending extends Schema.Class<ToolStatePending>("Session.Entry.ToolState.Pending")({
+  status: Schema.Literal("pending"),
+  input: Schema.String,
+}) {}
+
+export class ToolStateRunning extends Schema.Class<ToolStateRunning>("Session.Entry.ToolState.Running")({
+  status: Schema.Literal("running"),
+  input: Schema.Record(Schema.String, Schema.Unknown),
+  title: Schema.String.pipe(Schema.optional),
+  metadata: Schema.Record(Schema.String, Schema.Unknown).pipe(Schema.optional),
+}) {}
+
+export class ToolStateCompleted extends Schema.Class<ToolStateCompleted>("Session.Entry.ToolState.Completed")({
+  status: Schema.Literal("completed"),
+  input: Schema.Record(Schema.String, Schema.Unknown),
+  output: Schema.String,
+  title: Schema.String,
+  metadata: Schema.Record(Schema.String, Schema.Unknown),
+  attachments: FileAttachment.pipe(Schema.Array, Schema.optional),
+}) {}
+
+export class ToolStateError extends Schema.Class<ToolStateError>("Session.Entry.ToolState.Error")({
+  status: Schema.Literal("error"),
+  input: Schema.Record(Schema.String, Schema.Unknown),
+  error: Schema.String,
+  metadata: Schema.Record(Schema.String, Schema.Unknown).pipe(Schema.optional),
+}) {}
+
+export const ToolState: any = Schema.Union([ToolStatePending, ToolStateRunning, ToolStateCompleted, ToolStateError]).pipe(
+  Schema.toTaggedUnion("status") as any,
+)
+export type ToolState = ToolStatePending | ToolStateRunning | ToolStateCompleted | ToolStateError
+
+export class AssistantTool extends Schema.Class<AssistantTool>("Session.Entry.Assistant.Tool")({
+  type: Schema.Literal("tool"),
+  callID: Schema.String,
+  name: Schema.String,
+  state: ToolState,
+  time: Schema.Struct({
+    created: Schema.DateTimeUtc,
+    ran: Schema.DateTimeUtc.pipe(Schema.optional),
+    completed: Schema.DateTimeUtc.pipe(Schema.optional),
+    pruned: Schema.DateTimeUtc.pipe(Schema.optional),
+  }),
+}) {}
+
+export class AssistantText extends Schema.Class<AssistantText>("Session.Entry.Assistant.Text")({
+  type: Schema.Literal("text"),
+  text: Schema.String,
+}) {}
+
+export class AssistantReasoning extends Schema.Class<AssistantReasoning>("Session.Entry.Assistant.Reasoning")({
+  type: Schema.Literal("reasoning"),
+  text: Schema.String,
+}) {}
+
+export class AssistantRetry extends Schema.Class<AssistantRetry>("Session.Entry.Assistant.Retry")({
+  attempt: NonNegativeInt,
+  error: RetryError,
+  time: Schema.Struct({
+    created: Schema.DateTimeUtc,
+  }),
+}) {
+  static fromEvent(event: Schema.Schema.Type<typeof RetriedEvent>) {
+    return new AssistantRetry({
+      attempt: event.attempt,
+      error: event.error,
+      time: {
+        created: event.timestamp,
+      },
+    })
+  }
+}
+
+export const AssistantContent = Schema.Union([AssistantText, AssistantReasoning, AssistantTool]).pipe(
+  Schema.toTaggedUnion("type"),
+)
+export type AssistantContent = Schema.Schema.Type<typeof AssistantContent>
+
+export class Assistant extends Schema.Class<Assistant>("Session.Entry.Assistant")({
+  ...Base,
+  type: Schema.Literal("assistant"),
+  content: AssistantContent.pipe(Schema.Array),
+  retries: AssistantRetry.pipe(Schema.Array, Schema.optional),
+  cost: Schema.Finite.pipe(Schema.optional),
+  tokens: Schema.Struct({
+    input: NonNegativeInt,
+    output: NonNegativeInt,
+    reasoning: NonNegativeInt,
+    cache: Schema.Struct({
+      read: NonNegativeInt,
+      write: NonNegativeInt,
+    }),
+  }).pipe(Schema.optional),
+  error: Schema.String.pipe(Schema.optional),
+  time: Schema.Struct({
+    created: Schema.DateTimeUtc,
+    completed: Schema.DateTimeUtc.pipe(Schema.optional),
+  }),
+}) {
+  static fromEvent(event: Schema.Schema.Type<typeof StepEvent.Started>) {
+    return new Assistant({
+      id: event.id,
+      type: "assistant",
+      time: {
+        created: event.timestamp,
+      },
+      content: [],
+      retries: [],
+    })
+  }
+}
+
+export class Compaction extends Schema.Class<Compaction>("Session.Entry.Compaction")({
+  ...CompactedEvent.fields,
+  type: Schema.Literal("compaction"),
+  ...Base,
+}) {
+  static fromEvent(event: Schema.Schema.Type<typeof CompactedEvent>) {
+    return new Compaction({
+      ...event,
+      type: "compaction",
+      time: { created: event.timestamp },
+    })
+  }
+}
+
+export const Entry: any = Schema.Union([User, Synthetic, Assistant, Compaction]).pipe(Schema.toTaggedUnion("type") as any)
+export type Entry = User | Synthetic | Assistant | Compaction
+
+export type Type = Entry["type"]
+
+/*
+export interface Interface {
+  readonly decode: (row: typeof SessionEntryTable.$inferSelect) => Entry
+  readonly fromSession: (sessionID: SessionID) => Effect.Effect<Entry[], never>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@saeeol/SessionEntry") {}
+
+export const layer: Layer.Layer<Service, never, never> = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const decodeEntry = Schema.decodeUnknownSync(Entry)
+
+    const decode: (typeof Service.Service)["decode"] = (row) => decodeEntry({ ...row, id: row.id, type: row.type })
+
+    const fromSession = Effect.fn("SessionEntry.fromSession")(function* (sessionID: SessionID) {
+      return Database.use((db) =>
+        db
+          .select()
+          .from(SessionEntryTable)
+          .where(eq(SessionEntryTable.session_id, sessionID))
+          .orderBy(SessionEntryTable.id)
+          .all()
+          .map((row) => decode(row)),
+      )
+    })
+
+    return Service.of({
+      decode,
+      fromSession,
+    })
+  }),
+)
+*/
+
+export * as SessionEntry from "./session-entry"