my-durable 0.0.0-stage → 0.0.2

package/apps/dpi-sdk/src/app-state.ts

@@ -0,0 +1,111 @@
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+export type AppState = { [key: string]: JsonValue };
+export type StateChange = {
+  operation: "create" | "update" | "delete" | "increment";
+  path: string;
+  value?: JsonValue;
+};
+
+export function statePath(parent: string, key: string) {
+  return `${parent}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+}
+
+function parts(path: string) {
+  if (path === "") return [];
+  if (!path.startsWith("/")) throw Error("Use a JSON Pointer path, such as /counter");
+  return path
+    .slice(1)
+    .split("/")
+    .map((part) => {
+      if (/~(?![01])/u.test(part)) throw Error("Invalid JSON Pointer escape");
+      const key = part.replaceAll("~1", "/").replaceAll("~0", "~");
+      if (["__proto__", "constructor", "prototype"].includes(key))
+        throw Error("Reserved field name");
+      return key;
+    });
+}
+
+function child(value: JsonValue, key: string): JsonValue {
+  if (value === null || typeof value !== "object" || !Object.hasOwn(value, key))
+    throw Error(`Field does not exist: ${key}`);
+  if (Array.isArray(value) && !/^(0|[1-9]\d*)$/u.test(key)) throw Error("Invalid array index");
+  return (value as AppState)[key]!;
+}
+
+export function readState(state: AppState, path = ""): JsonValue {
+  return parts(path).reduce<JsonValue>(child, state);
+}
+
+function validate(value: unknown, depth = 0): asserts value is JsonValue {
+  if (depth > 24) throw Error("State is too deeply nested");
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number" && Number.isFinite(value)) return;
+  if (typeof value !== "object" || value === null) throw Error("Value must be valid JSON");
+  for (const [key, item] of Object.entries(value)) {
+    if (["__proto__", "constructor", "prototype"].includes(key)) throw Error("Reserved field name");
+    validate(item, depth + 1);
+  }
+}
+
+export function changeState(state: AppState, input: StateChange): AppState {
+  if (!["create", "update", "delete", "increment"].includes(input.operation))
+    throw Error("Invalid state operation");
+  if (typeof input.path !== "string") throw Error("State path is required");
+  const path = parts(input.path);
+  const next: AppState = JSON.parse(JSON.stringify(state));
+  if (!path.length) {
+    if (input.operation === "delete") return {};
+    if (
+      input.operation !== "update" ||
+      input.value === null ||
+      Array.isArray(input.value) ||
+      typeof input.value !== "object"
+    )
+      throw Error("The state root must be a JSON object. Use update to replace it.");
+    validate(input.value);
+    if (JSON.stringify(input.value).length > 100000)
+      throw Error("App State must be under 100,000 characters");
+    return JSON.parse(JSON.stringify(input.value));
+  }
+  const key = path.pop()!;
+  const parent = path.reduce<JsonValue>(child, next);
+  if (parent === null || typeof parent !== "object")
+    throw Error("Parent must be an object or array");
+  const exists = Object.hasOwn(parent, key);
+  const array = Array.isArray(parent);
+  const append = array && (key === "-" || key === String(parent.length));
+  if (array && !append && (!/^(0|[1-9]\d*)$/u.test(key) || Number(key) >= parent.length))
+    throw Error("Invalid array index");
+  if (input.operation === "create" && exists) throw Error("Field already exists. Use update.");
+  if (input.operation !== "create" && !exists) throw Error("Field does not exist. Use create.");
+  if (input.operation === "delete") {
+    if (array) parent.splice(Number(key), 1);
+    else delete parent[key];
+  } else {
+    let value = input.value;
+    if (input.operation === "increment") {
+      const current = (parent as AppState)[key];
+      if (typeof current !== "number" || typeof value !== "number")
+        throw Error("Increment requires numbers");
+      value = current + value;
+    }
+    validate(value);
+    if (array) parent[append ? parent.length : Number(key)] = value;
+    else parent[key] = value;
+  }
+  validate(next);
+  if (JSON.stringify(next).length > 100000)
+    throw Error("App State must be under 100,000 characters");
+  return next;
+}
+
+export function replaceState(target: AppState, next: AppState) {
+  for (const key of Object.keys(target)) delete target[key];
+  Object.assign(target, next);
+}

package/apps/dpi-sdk/src/client.ts

@@ -0,0 +1,330 @@
+import type {
+  AgentConfig,
+  AgentDetail,
+  AgentExtensions,
+  AgentSummary,
+  CompactionSettings,
+  CreateAgentBody,
+  CreateSessionBody,
+  DeviceInfo,
+  DeviceTree,
+  DirListing,
+  ErrorCode,
+  ForkBody,
+  Frame,
+  Page,
+  SendResult,
+  SessionSummary,
+  TaskOutcome,
+  WhenBusy,
+  WireEntry,
+} from "./api.js";
+import { DpiError } from "./errors.js";
+import { Backoff } from "./protocol/backoff.js";
+import { RECONNECT_BACKOFF_S } from "./protocol/limits.js";
+import { readSse } from "./sse.js";
+
+export interface RequestOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  idempotencyKey?: string;
+}
+
+const enc = encodeURIComponent;
+const newId = (): string =>
+  globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+/**
+ * Typed client for one dpi-backend. Works in browsers and Node (fetch + streams).
+ * `token` is optional: the playground hub injects it, so browsers never hold one.
+ */
+export class DpiClient {
+  readonly baseUrl: string;
+  constructor(
+    baseUrl: string,
+    private readonly token?: string,
+  ) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+  }
+
+  private headers(json: boolean, extra: Record<string, string> = {}) {
+    return {
+      ...(this.token ? { authorization: `Bearer ${this.token}`, "x-dpi-token": this.token } : {}),
+      ...(json ? { "content-type": "application/json" } : {}),
+      ...extra,
+    };
+  }
+
+  async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    options: RequestOptions = {},
+  ): Promise<T> {
+    const timeout = AbortSignal.timeout(options.timeoutMs ?? 20_000);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    let response: Response;
+    try {
+      response = await fetch(this.baseUrl + path, {
+        method,
+        signal,
+        headers: this.headers(
+          body !== undefined,
+          options.idempotencyKey ? { "idempotency-key": options.idempotencyKey } : {},
+        ),
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+    } catch (cause) {
+      if (options.signal?.aborted) throw cause;
+      throw new DpiError("offline", `Cannot reach ${this.baseUrl}`, 0, { cause });
+    }
+    const text = await response.text();
+    let data: unknown;
+    try {
+      data = text ? JSON.parse(text) : undefined;
+    } catch {
+      data = undefined;
+    }
+    if (!response.ok) {
+      const error = (data as { error?: { code?: ErrorCode; message?: string } } | undefined)?.error;
+      const code: ErrorCode =
+        error?.code ??
+        (response.status === 401 ? "unauthorized" : response.status === 404 ? "not_found" : "internal");
+      throw new DpiError(code, error?.message ?? `${response.status} ${response.statusText}`, response.status);
+    }
+    return data as T;
+  }
+
+  /** Open one SSE stream and yield its frames until it ends. Throws `DpiError` on failure. */
+  async *stream(path: string, signal: AbortSignal, idleMs?: number): AsyncGenerator<Frame> {
+    let response: Response;
+    try {
+      response = await fetch(this.baseUrl + path, {
+        headers: { ...this.headers(false), accept: "text/event-stream" },
+        signal,
+      });
+    } catch (cause) {
+      if (signal.aborted) return;
+      throw new DpiError("offline", `Cannot reach ${this.baseUrl}`, 0, { cause });
+    }
+    if (!response.ok || !response.body) {
+      const body = (await response.json().catch(() => undefined)) as
+        | { error?: { code?: ErrorCode; message?: string } }
+        | undefined;
+      const code: ErrorCode =
+        body?.error?.code ?? (response.status === 401 ? "unauthorized" : "unavailable");
+      throw new DpiError(code, body?.error?.message ?? `Stream failed (${response.status})`, response.status);
+    }
+    try {
+      for await (const message of readSse(response.body, idleMs)) yield JSON.parse(message.data) as Frame;
+    } catch (error) {
+      if (signal.aborted) return;
+      throw error;
+    }
+  }
+
+  // ------------------------------------------------------------ device
+  device(options?: RequestOptions) {
+    return this.request<DeviceInfo>("GET", "/v1/device", undefined, options);
+  }
+  tree() {
+    return this.request<DeviceTree>("GET", "/v1/tree");
+  }
+  dirs(path = "") {
+    return this.request<DirListing>("GET", `/v1/fs/dirs?path=${enc(path)}`);
+  }
+  deviceDoc<T = unknown>(kind: string) {
+    return this.request<{ kind: string; value: T; revision?: number }>("GET", `/v1/docs/${enc(kind)}`);
+  }
+  deviceEvents(signal: AbortSignal, docs: string[] = []) {
+    return this.stream(`/v1/events${docs.length ? `?docs=${docs.map(enc).join(",")}` : ""}`, signal);
+  }
+
+  // ------------------------------------------------------------ sessions
+  sessions() {
+    return this.request<SessionSummary[]>("GET", "/v1/sessions");
+  }
+  createSession(body: CreateSessionBody, idempotencyKey = newId()) {
+    return this.request<SessionSummary>("POST", "/v1/sessions", body, { idempotencyKey });
+  }
+  session(ref: string) {
+    return new SessionHandle(this, ref);
+  }
+  agent(session: string, agent: string | number) {
+    return new AgentHandle(this, session, String(agent));
+  }
+}
+
+export class SessionHandle {
+  constructor(
+    readonly client: DpiClient,
+    readonly ref: string,
+  ) {}
+  get base() {
+    return `/v1/sessions/${enc(this.ref)}`;
+  }
+  get() {
+    return this.client.request<SessionSummary>("GET", this.base);
+  }
+  rename(name: string) {
+    return this.client.request<SessionSummary>("PATCH", this.base, { name });
+  }
+  archive() {
+    return this.client.request<{ archived: string }>("DELETE", this.base);
+  }
+  agents() {
+    return this.client.request<AgentSummary[]>("GET", `${this.base}/agents`);
+  }
+  createAgent(body: CreateAgentBody = {}, idempotencyKey = newId()) {
+    return this.client.request<AgentSummary>("POST", `${this.base}/agents`, body, { idempotencyKey });
+  }
+  tasks(status: "live" | "terminal" = "terminal", limit = 20) {
+    return this.client.request<TaskOutcome[]>("GET", `${this.base}/tasks?status=${status}&limit=${limit}`);
+  }
+  abortTask(taskId: number) {
+    return this.client.request<{ status: string }>("POST", `${this.base}/tasks/${taskId}/abort`, {});
+  }
+  inspect() {
+    return this.client.request<unknown>("GET", `${this.base}/inspect`);
+  }
+  compaction() {
+    return this.client.request<CompactionSettings>("GET", `${this.base}/compaction`);
+  }
+  /** Change the session's automatic compaction thresholds; they apply from the next request. */
+  setCompaction(patch: Partial<CompactionSettings>) {
+    return this.client.request<CompactionSettings>("PATCH", `${this.base}/compaction`, patch);
+  }
+  submission(id: number, waitMs = 0) {
+    return this.client.request<SendResult>("GET", `${this.base}/submissions/${id}?waitMs=${waitMs}`, undefined, {
+      timeoutMs: waitMs + 20_000,
+    });
+  }
+  events(signal: AbortSignal) {
+    return this.client.stream(`${this.base}/events`, signal);
+  }
+}
+
+export class AgentHandle {
+  constructor(
+    readonly client: DpiClient,
+    readonly session: string,
+    readonly agent: string,
+  ) {}
+  get base() {
+    return `/v1/sessions/${enc(this.session)}/agents/${enc(this.agent)}`;
+  }
+  get() {
+    return this.client.request<AgentDetail>("GET", this.base);
+  }
+  rename(name: string) {
+    return this.client.request<AgentSummary>("PATCH", this.base, { name });
+  }
+  send(content: string, whenBusy: WhenBusy = "followUp", requestId = newId(), waitMs?: number) {
+    return this.client.request<SendResult>(
+      "POST",
+      `${this.base}/messages`,
+      { content, whenBusy, requestId, waitMs },
+      { timeoutMs: (waitMs ?? 0) + 20_000 },
+    );
+  }
+  withdraw(submissionId: number) {
+    return this.client.request<{ status: string }>("DELETE", `${this.base}/inbox/${submissionId}`);
+  }
+  abort(background = false) {
+    return this.client.request<{ ok: true }>("POST", `${this.base}/abort`, { background });
+  }
+  fork(body: ForkBody, idempotencyKey = newId()) {
+    return this.client.request<AgentSummary>("POST", `${this.base}/fork`, body, { idempotencyKey });
+  }
+  config() {
+    return this.client.request<AgentConfig>("GET", `${this.base}/config`);
+  }
+  configure(patch: Partial<AgentConfig>) {
+    return this.client.request<AgentConfig>("PATCH", `${this.base}/config`, patch);
+  }
+  compact(instructions?: string) {
+    return this.client.request<{ taskId: number }>("POST", `${this.base}/compact`, { instructions });
+  }
+  reset(note?: string) {
+    return this.client.request<{ ok: true }>("POST", `${this.base}/reset`, { note });
+  }
+  entries(options: { scope?: "active" | "all"; cursor?: string; limit?: number } = {}) {
+    const q = new URLSearchParams({
+      scope: options.scope ?? "all",
+      limit: String(options.limit ?? 500),
+      ...(options.cursor ? { cursor: options.cursor } : {}),
+    });
+    return this.client.request<Page<WireEntry>>("GET", `${this.base}/entries?${q}`);
+  }
+  transcript(format: "json" | "markdown" = "json") {
+    return this.client.request<{ format: string; text?: string; items?: unknown[] }>(
+      "GET",
+      `${this.base}/transcript?format=${format}`,
+    );
+  }
+  doc<T = unknown>(kind: string) {
+    return this.client.request<{ kind: string; value: T }>("GET", `${this.base}/docs/${enc(kind)}`);
+  }
+  extensions() {
+    return this.client.request<AgentExtensions>("GET", `${this.base}/extensions`);
+  }
+  /** Turn a custom extension on or off, or check or uncheck one of system-prompts' prompts. */
+  setExtension(patch: { name: string; enabled: boolean } | { prompt: string; enabled: boolean }) {
+    return this.client.request<AgentExtensions>("PATCH", `${this.base}/extensions`, patch);
+  }
+  demo<T = unknown>(path: string, body: unknown, method = "POST") {
+    return this.client.request<T>(method, `${this.base}/demo/${path}`, body);
+  }
+  events(signal: AbortSignal, docs: string[] = []) {
+    return this.client.stream(
+      `${this.base}/events${docs.length ? `?docs=${docs.map(enc).join(",")}` : ""}`,
+      signal,
+    );
+  }
+}
+
+export type ConnectionState = "connecting" | "live" | "offline" | "unauthorized" | "gone";
+
+const sleep = (ms: number, signal: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    if (signal.aborted) return resolve();
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener("abort", () => (clearTimeout(timer), resolve()), { once: true });
+  });
+
+/**
+ * Keep one stream open: reconnect with backoff, and start every reconnect from the server's fresh
+ * snapshot (streams never replay). Stops for good on `unauthorized` or `not_found`.
+ */
+export async function follow(
+  open: (signal: AbortSignal) => AsyncIterable<Frame>,
+  onFrame: (frame: Frame) => void,
+  onState: (state: ConnectionState, error?: DpiError) => void,
+  signal: AbortSignal,
+) {
+  const backoff = new Backoff(RECONNECT_BACKOFF_S);
+  while (!signal.aborted) {
+    onState("connecting");
+    try {
+      for await (const frame of open(signal)) {
+        if (frame.type === "hello") {
+          backoff.reset();
+          onState("live");
+        }
+        onFrame(frame);
+      }
+      if (signal.aborted) return;
+      onFrame({ type: "disconnected", reason: "Stream ended" });
+    } catch (error) {
+      if (signal.aborted) return;
+      const e =
+        error instanceof DpiError ? error : new DpiError("offline", String((error as Error)?.message ?? error));
+      onFrame({ type: "disconnected", reason: e.message });
+      if (e.code === "unauthorized") return onState("unauthorized", e);
+      if (e.code === "not_found") return onState("gone", e);
+      onState("offline", e);
+    }
+    await sleep(backoff.ms, signal);
+    backoff.advance();
+  }
+}

package/apps/dpi-sdk/src/errors.ts

@@ -0,0 +1,16 @@
+import type { ErrorCode } from "./api.js";
+
+/** Every client-side failure: `offline` when the device can't be reached, otherwise the server's error code. */
+export class DpiError extends Error {
+  constructor(
+    readonly code: ErrorCode,
+    message: string,
+    readonly status = 0,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options);
+    this.name = "DpiError";
+  }
+}
+
+export const isDpiError = (e: unknown): e is DpiError => e instanceof DpiError;

package/apps/dpi-sdk/src/jobs.ts

@@ -0,0 +1,99 @@
+// Durable jobs: repeatable workflows. Each run is one pi-durable task whose checkpoint phases are the job's named
+// phases. The run's record lives in the conversation document `demo.job-runs`, so every client renders the same
+// phases, steps and approval, live and after a restart. Types are aliases (not interfaces) so they stay JSON documents.
+
+export const JOB_RUNS_DOC = "demo.job-runs";
+
+export type JobInputValue = string | number | boolean;
+
+export type JobInputSpec = {
+  name: string;
+  type: "string" | "integer";
+  description: string;
+  default: JobInputValue;
+  min?: number;
+  max?: number;
+};
+
+export type JobPhaseSpec = {
+  id: string;
+  label: string;
+  summary: string;
+  /** `approval` phases wait for a person's decision; `repeat` phases save one checkpoint per iteration. */
+  kind?: "approval" | "repeat";
+};
+
+export type JobDef = {
+  id: string;
+  title: string;
+  summary: string;
+  phases: JobPhaseSpec[];
+  inputs: JobInputSpec[];
+  /** The run pauses in an approval phase until a person approves or declines. */
+  approval: boolean;
+  /** App State path where every run saves its result. */
+  resultPath: string;
+  /** Typical run time in seconds, without the approval wait. */
+  seconds: number;
+};
+
+export type JobStepKind = "command" | "tool" | "agent" | "state" | "approval" | "checkpoint" | "note";
+export type JobStepStatus = "running" | "done" | "error" | "waiting";
+export type JobPhaseStatus = "pending" | "running" | "waiting" | "done" | "failed" | "aborted" | "skipped";
+export type JobRunStatus = "running" | "waiting" | "completed" | "failed" | "aborted" | "declined";
+
+export type JobStep = {
+  id: string;
+  kind: JobStepKind;
+  label: string;
+  detail?: string;
+  status: JobStepStatus;
+  /** The phase iteration that recorded the step; a resumed iteration replaces its own steps. */
+  iteration: number;
+  at: number;
+  ms?: number;
+  /** For subagent steps: the child conversation that made the call. */
+  conversationId?: number;
+};
+
+export type JobPhaseRun = {
+  id: string;
+  label: string;
+  status: JobPhaseStatus;
+  startedAt?: number;
+  endedAt?: number;
+  summary?: string;
+  steps: JobStep[];
+  progress?: { done: number; total: number };
+};
+
+export type JobRun = {
+  /** The job's durable task id. */
+  id: number;
+  job: string;
+  title: string;
+  /** The nth run of this job in this conversation. */
+  run: number;
+  input: Record<string, JobInputValue>;
+  startedBy: "agent" | "you";
+  /** Set when the agent started the run: the run_durable_job call that owns it. */
+  toolCallId?: string;
+  background: boolean;
+  status: JobRunStatus;
+  phase?: string;
+  phases: JobPhaseRun[];
+  approval?: "pending" | "approved" | "declined" | "cancelled";
+  childConversationId?: number;
+  /** How many times the run continued from a checkpoint after a restart. */
+  resumed: number;
+  result?: string;
+  error?: string;
+  startedAt: number;
+  updatedAt: number;
+  endedAt?: number;
+};
+
+export type JobRunsDoc = { counts: Record<string, number>; items: Record<string, JobRun> };
+
+export const jobRunDone = (run: Pick<JobRun, "status">) =>
+  run.status !== "running" && run.status !== "waiting";