Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
13.8 KB
Raw Blame
/**
 * Result decoders. Each checks the fields its type promises, raises
 * {@link ProtocolError} when one is missing or mistyped, and keeps the full
 * server JSON in `raw`. Unknown fields pass through in `raw` untouched.
 *
 * @internal
 * @module
 */

import { ProtocolError } from "./errors.js";
import type {
  ActivityWindow,
  AnsweredScope,
  ApiHandoff,
  ApiPage,
  ApiSearchHit,
  Briefing,
  SessionActivity,
  Handoff,
  Message,
  Observation,
  ObservationHit,
  ObservationsResult,
  PageSummary,
  ProjectSummary,
  QueryHit,
  Raw,
  RelatedPage,
  SessionSummary,
  StatusCounts,
  UntrustedText,
  WorkspaceSummary,
} from "./types.js";

/** Mark stored-memory text with the {@link UntrustedText} brand. */
export function untrusted(text: string): UntrustedText {
  return text as UntrustedText;
}

/** A JSON object, or a {@link ProtocolError} naming where it was expected. */
export function record(value: unknown, where: string): Raw {
  if (value === null || typeof value !== "object" || Array.isArray(value)) {
    throw new ProtocolError(`${where}: expected a JSON object`);
  }
  return value as Raw;
}

/** A JSON array, or a {@link ProtocolError}. */
export function array(value: unknown, where: string): readonly unknown[] {
  if (!Array.isArray(value)) throw new ProtocolError(`${where}: expected a JSON array`);
  return value;
}

/** A required string field. */
export function str(o: Raw, key: string, where: string): string {
  const value = o[key];
  if (typeof value !== "string") {
    throw new ProtocolError(`${where}: field ${key} is missing or not a string`);
  }
  return value;
}

/** An optional string field (`undefined` when absent or null). */
export function optStr(o: Raw, key: string, where: string): string | undefined {
  const value = o[key];
  if (value === undefined || value === null) return undefined;
  if (typeof value !== "string") throw new ProtocolError(`${where}: field ${key} is not a string`);
  return value;
}

/** A string-or-null field; absent counts as null. */
export function nullableStr(o: Raw, key: string, where: string): string | null {
  return optStr(o, key, where) ?? null;
}

/** A required number field. */
export function num(o: Raw, key: string, where: string): number {
  const value = o[key];
  if (typeof value !== "number") {
    throw new ProtocolError(`${where}: field ${key} is missing or not a number`);
  }
  return value;
}

/** An optional number field with a default. */
export function numOr(o: Raw, key: string, fallback: number, where: string): number {
  const value = o[key];
  if (value === undefined || value === null) return fallback;
  if (typeof value !== "number") throw new ProtocolError(`${where}: field ${key} is not a number`);
  return value;
}

/** A required boolean field. */
export function bool(o: Raw, key: string, where: string): boolean {
  const value = o[key];
  if (typeof value !== "boolean") {
    throw new ProtocolError(`${where}: field ${key} is missing or not a boolean`);
  }
  return value;
}

/** An optional boolean, false when absent. */
export function flag(o: Raw, key: string): boolean {
  return o[key] === true;
}

/** An array of strings; absent counts as empty. */
export function strings(o: Raw, key: string, where: string): string[] {
  const value = o[key];
  if (value === undefined || value === null) return [];
  return array(value, `${where}.${key}`).map((item, index) => {
    if (typeof item !== "string") {
      throw new ProtocolError(`${where}: ${key}[${index}] is not a string`);
    }
    return item;
  });
}

/** Decode each element of an array field with `decode`; absent counts as empty. */
export function list<T>(
  o: Raw,
  key: string,
  where: string,
  decode: (value: unknown, where: string) => T,
): T[] {
  const value = o[key];
  if (value === undefined || value === null) return [];
  return array(value, `${where}.${key}`).map((item, index) =>
    decode(item, `${where}.${key}[${index}]`),
  );
}

/** A required array field decoded with `decode`. */
export function requiredList<T>(
  o: Raw,
  key: string,
  where: string,
  decode: (value: unknown, where: string) => T,
): T[] {
  if (!Array.isArray(o[key])) {
    throw new ProtocolError(`${where}: field ${key} is missing or not an array`);
  }
  return list(o, key, where, decode);
}

/** A `PageHit` (single-project, scopes, recent) or a `PageHitWithMeta` (global). */
export function queryHit(value: unknown, where: string): QueryHit {
  const o = record(value, where);
  return {
    id: optStr(o, "id", where),
    path: str(o, "path", where),
    title: untrusted(str(o, "title", where)),
    snippet: untrusted(optStr(o, "snippet", where) ?? ""),
    rank: numOr(o, "rank", 0, where),
    superseded: flag(o, "superseded"),
    pinned: flag(o, "pinned"),
    workspace: optStr(o, "workspace_name", where) ?? optStr(o, "workspace", where),
    project: optStr(o, "project_name", where) ?? optStr(o, "project", where),
    raw: o,
  };
}

/** A raw-observation fallback hit. */
export function observationHit(value: unknown, where: string): ObservationHit {
  const o = record(value, where);
  return {
    id: str(o, "id", where),
    sessionId: str(o, "session_id", where),
    kind: str(o, "kind", where),
    title: untrusted(str(o, "title", where)),
    snippet: untrusted(optStr(o, "snippet", where) ?? ""),
    rank: numOr(o, "rank", 0, where),
    createdAt: str(o, "created_at", where),
    raw: o,
  };
}

/** The `scope` object a tool answers with. */
export function answeredScope(value: unknown, where: string): AnsweredScope {
  const o = record(value, where);
  return {
    workspace: str(o, "workspace", where),
    project: str(o, "project", where),
    resolvedBy: optStr(o, "resolved_by", where) ?? "",
  };
}

/** `StatusCounts`. */
export function statusCounts(value: unknown, where: string): StatusCounts {
  const o = record(value, where);
  return {
    pagesLatest: num(o, "pages_latest", where),
    pagesAll: num(o, "pages_all", where),
    sessions: num(o, "sessions", where),
    observations: num(o, "observations", where),
  };
}

/** A page reference (`PageSummary`). */
export function pageSummary(value: unknown, where: string): PageSummary {
  const o = record(value, where);
  return {
    path: str(o, "path", where),
    title: untrusted(str(o, "title", where)),
    kind: optStr(o, "kind", where),
    tier: optStr(o, "tier", where),
    updatedAt: optStr(o, "updated_at", where),
    raw: o,
  };
}

function activity(value: unknown, where: string): ActivityWindow {
  const o = record(value, where);
  return {
    days: num(o, "days", where),
    sessions: num(o, "sessions", where),
    observations: num(o, "observations", where),
    pagesUpdated: num(o, "pages_updated", where),
  };
}

/** `BriefingSnapshot`, shared by `memory_briefing` and `/api/v1/.../briefing`. */
export function briefing(value: unknown, where: string): Briefing {
  const o = record(value, where);
  return {
    counts: statusCounts(o["counts"], `${where}.counts`),
    activity7d: activity(o["activity_7d"], `${where}.activity_7d`),
    activity30d: activity(o["activity_30d"], `${where}.activity_30d`),
    lastObservationAt: nullableStr(o, "last_observation_at", where),
    pendingHandoffCount: numOr(o, "pending_handoff_count", 0, where),
    rules: list(o, "rules", where, pageSummary),
    slots: list(o, "slots", where, pageSummary),
    recentPages: requiredList(o, "recent_pages", where, pageSummary),
    recentSessions: list(o, "recent_sessions", where, sessionActivity),
    raw: o,
  };
}

/** A `SessionActivity` row: one session's newest captured work. */
export function sessionActivity(value: unknown, where: string): SessionActivity {
  const o = record(value, where);
  return {
    sessionId: str(o, "session_id", where),
    agentKind: str(o, "agent_kind", where),
    cwd: optStr(o, "cwd", where),
    lastActivityAt: str(o, "last_activity_at", where),
    ended: bool(o, "ended", where),
    handedOff: flag(o, "handed_off"),
    current: flag(o, "current"),
    raw: o,
  };
}

/** A related page from `memory_read_page(include_related)`. */
export function relatedPage(value: unknown, where: string): RelatedPage {
  const o = record(value, where);
  return {
    path: str(o, "path", where),
    title: untrusted(optStr(o, "title", where) ?? ""),
    kind: optStr(o, "kind", where),
    workspace: optStr(o, "workspace", where),
    project: optStr(o, "project", where),
    depth: typeof o["depth"] === "number" ? o["depth"] : undefined,
    direction: optStr(o, "direction", where),
    raw: o,
  };
}

/** A handoff row from `memory_handoff_list` / `memory_handoff_accept`. */
export function handoff(value: unknown, where: string): Handoff {
  const o = record(value, where);
  return {
    id: str(o, "id", where),
    summary: untrusted(str(o, "summary", where)),
    openQuestions: strings(o, "open_questions", where).map(untrusted),
    nextSteps: strings(o, "next_steps", where).map(untrusted),
    filesTouched: strings(o, "files_touched", where),
    state: str(o, "state", where),
    createdAt: optStr(o, "created_at", where),
    owner: nullableStr(o, "owner_user", where),
    raw: o,
  };
}

/** A message row. */
export function message(value: unknown, where: string): Message {
  const o = record(value, where);
  const subject = nullableStr(o, "subject", where);
  const evidence = nullableStr(o, "evidence", where);
  const nature = optStr(o, "nature", where) ?? "unknown";
  if (!["unknown", "measured", "reported", "inferred"].includes(nature)) {
    throw new ProtocolError(`${where}.nature must be a supported message nature`);
  }
  return {
    id: str(o, "id", where),
    subject: subject === null ? null : untrusted(subject),
    body: untrusted(str(o, "body", where)),
    nature: nature as Message["nature"],
    evidence: evidence === null ? null : untrusted(evidence),
    state: str(o, "state", where),
    createdAt: optStr(o, "created_at", where),
    claimedAt: nullableStr(o, "claimed_at", where),
    fromAgent: optStr(o, "from_agent", where),
    toAgent: nullableStr(o, "to_agent", where),
    fromOwner: nullableStr(o, "from_owner_user", where),
    raw: o,
  };
}

/** A `SessionSummary`. */
export function sessionSummary(value: unknown, where: string): SessionSummary {
  const o = record(value, where);
  return {
    sessionId: str(o, "session_id", where),
    agentKind: optStr(o, "agent_kind", where),
    cwd: nullableStr(o, "cwd", where),
    startedAt: optStr(o, "started_at", where),
    endedAt: nullableStr(o, "ended_at", where),
    observationCount: numOr(o, "observation_count", 0, where),
    raw: o,
  };
}

/** An `ObservationRecord`. */
export function observation(value: unknown, where: string): Observation {
  const o = record(value, where);
  return {
    id: str(o, "id", where),
    sessionId: str(o, "session_id", where),
    kind: str(o, "kind", where),
    title: untrusted(str(o, "title", where)),
    body: untrusted(str(o, "body", where)),
    importance: numOr(o, "importance", 0, where),
    createdAt: str(o, "created_at", where),
    raw: o,
  };
}

/** One page of session observations (MCP tool and `/api/v1` share the shape). */
export function observationsResult(value: unknown, where: string): ObservationsResult {
  const o = record(value, where);
  return {
    session: sessionSummary(o["session"], `${where}.session`),
    observations: requiredList(o, "observations", where, observation),
    total: num(o, "total", where),
    offset: numOr(o, "offset", 0, where),
    limit: num(o, "limit", where),
    elidedOtherScope: numOr(o, "elided_other_scope", 0, where),
    raw: o,
  };
}

/** A `WorkspaceSummary`. */
export function workspaceSummary(value: unknown, where: string): WorkspaceSummary {
  const o = record(value, where);
  return {
    name: str(o, "workspace_name", where),
    projectCount: numOr(o, "project_count", 0, where),
    pageCount: numOr(o, "page_count", 0, where),
    lastUpdated: nullableStr(o, "last_updated", where),
    raw: o,
  };
}

/** A `ProjectSummary`. */
export function projectSummary(value: unknown, where: string): ProjectSummary {
  const o = record(value, where);
  return {
    workspaceId: str(o, "workspace_id", where),
    workspace: str(o, "workspace_name", where),
    projectId: str(o, "project_id", where),
    project: str(o, "project_name", where),
    pageCount: numOr(o, "page_count", 0, where),
    lastUpdated: nullableStr(o, "last_updated", where),
    raw: o,
  };
}

/** A full `/api/v1` page. */
export function apiPage(value: unknown, where: string): ApiPage {
  const o = record(value, where);
  const frontmatter = o["frontmatter"];
  return {
    id: str(o, "id", where),
    path: str(o, "path", where),
    title: untrusted(str(o, "title", where)),
    kind: optStr(o, "kind", where),
    tier: optStr(o, "tier", where),
    pinned: flag(o, "pinned"),
    createdAt: optStr(o, "created_at", where),
    updatedAt: optStr(o, "updated_at", where),
    frontmatter:
      frontmatter !== null && typeof frontmatter === "object" && !Array.isArray(frontmatter)
        ? (frontmatter as Raw)
        : {},
    body: untrusted(str(o, "body_markdown", where)),
    raw: o,
  };
}

/** An `/api/v1/search` hit. */
export function apiSearchHit(value: unknown, where: string): ApiSearchHit {
  const o = record(value, where);
  return {
    workspace: str(o, "workspace", where),
    project: str(o, "project", where),
    path: str(o, "path", where),
    title: untrusted(str(o, "title", where)),
    kind: optStr(o, "kind", where),
    snippet: untrusted(optStr(o, "snippet", where) ?? ""),
    rank: numOr(o, "rank", 0, where),
    raw: o,
  };
}

/** A handoff row from the `/api/v1` listing. */
export function apiHandoff(value: unknown, where: string): ApiHandoff {
  const o = record(value, where);
  const summary = optStr(o, "summary", where);
  return {
    id: str(o, "id", where),
    state: str(o, "state", where),
    at: optStr(o, "at", where),
    agent: optStr(o, "agent", where),
    summary: summary === undefined ? undefined : untrusted(summary),
    redacted: flag(o, "redacted"),
    raw: o,
  };
}