Skip to content

Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.

10.1 KB
Raw Blame
import { isRecord } from "@linger/service-kit";

export type RuntimeHistoryJsonValue =
  | null
  | boolean
  | number
  | string
  | readonly RuntimeHistoryJsonValue[]
  | { readonly [key: string]: RuntimeHistoryJsonValue };

export type RuntimeHistoryRecordCategory =
  | "message"
  | "tool_call"
  | "tool_result"
  | "lifecycle"
  | "reasoning"
  | "usage"
  | "provider_event"
  | "compaction";

export type RuntimeHistoryRedactionReason =
  | "secret"
  | "encrypted_content"
  | "reasoning_content"
  | "physical_path"
  | "omitted_too_large";

export interface RuntimeHistoryRedactedField {
  readonly path: string;
  readonly reason: RuntimeHistoryRedactionReason;
  readonly byteCount?: number;
}

export interface RuntimeHistoryRecord {
  readonly ordinal: number;
  readonly timestamp?: string;
  readonly turnId?: string;
  readonly category: RuntimeHistoryRecordCategory;
  readonly nativeType: string;
  readonly toolCallId?: string;
  readonly toolName?: string;
  readonly role?: string;
  readonly phase?: string;
  readonly nativeRecord: { readonly [key: string]: RuntimeHistoryJsonValue };
  readonly redactedFields: readonly RuntimeHistoryRedactedField[];
}

export interface RuntimeHistoryInstructionBlock {
  readonly recordOrdinal: number;
  readonly recordType: string;
  readonly field: string;
  readonly contentOrdinal?: number;
  readonly timestamp?: string;
  readonly text: string;
}

export type RuntimeHistorySource =
  | "codex_rollout"
  | "claude_transcript"
  | "pi_session";

export type RuntimeHistoryInstructions =
  | {
      readonly status: "available";
      readonly source: RuntimeHistorySource;
      readonly blocks: readonly RuntimeHistoryInstructionBlock[];
    }
  | {
      readonly status: "unavailable";
      readonly source: RuntimeHistorySource;
      readonly reason: string;
      readonly blocks: readonly [];
    };

export interface RuntimeHistorySnapshot {
  readonly id: string;
  readonly threadId: string;
  readonly capturedAt: string;
  readonly recordCount: number;
  readonly tailState: "clean" | "incomplete" | "corrupt";
}

export type RuntimeHistoryPage =
  | {
      readonly status: "available";
      readonly providerKind: string;
      readonly source: RuntimeHistorySource;
      readonly snapshot: RuntimeHistorySnapshot;
      readonly instructions: RuntimeHistoryInstructions;
      readonly records: readonly RuntimeHistoryRecord[];
      readonly previousCursor?: string;
    }
  | {
      readonly status: "unsupported" | "unavailable";
      readonly providerKind: string;
      readonly reason: string;
      readonly instructions: RuntimeHistoryInstructions;
      readonly records: readonly [];
    };

export interface RuntimeHistoryOptions {
  readonly cursor?: string;
  readonly limit?: number;
  readonly signal?: AbortSignal;
}

/**
 * A History page with no records. `unsupported` means the Runtime cannot
 * inspect History at all; `unavailable` means it can but nothing is readable
 * now. The instruction source follows the Runtime's native History format.
 */
export function unavailableRuntimeHistory(
  providerKind: string,
  reason: string,
  status: "unsupported" | "unavailable" = "unavailable",
): RuntimeHistoryPage {
  return {
    status,
    providerKind,
    reason,
    instructions: {
      status: "unavailable",
      source:
        providerKind === "pi"
          ? "pi_session"
          : providerKind === "claude"
            ? "claude_transcript"
            : "codex_rollout",
      reason,
      blocks: [],
    },
    records: [],
  };
}

export type RuntimeHistoryInspection = RuntimeHistoryPage;

const MAX_NATIVE_RECORD_BYTES = 4 * 1024 * 1024;
const MAX_REDACTED_FIELDS = 1_024;
const MAX_JSON_DEPTH = 100;

/** Defense-in-depth redaction at the Agent Service process boundary. */
export const redactRuntimeHistoryPage = (
  history: RuntimeHistoryPage,
): RuntimeHistoryPage => {
  const instructions = redactInstructions(history.instructions);
  if (history.status !== "available") {
    return Object.freeze({ ...history, instructions });
  }
  return Object.freeze({
    ...history,
    instructions,
    records: Object.freeze(history.records.map(redactHistoryRecord)),
  });
};

const redactInstructions = (
  instructions: RuntimeHistoryInstructions,
): RuntimeHistoryInstructions => {
  if (instructions.status === "unavailable") return instructions;
  return Object.freeze({
    ...instructions,
    blocks: Object.freeze(
      instructions.blocks.map((block) =>
        Object.freeze({ ...block, text: redactString(block.text) }),
      ),
    ),
  });
};

const redactHistoryRecord = (
  record: RuntimeHistoryRecord,
): RuntimeHistoryRecord => {
  const added: RuntimeHistoryRedactedField[] = [];
  const nativePayload =
    isRecord(record.nativeRecord) && isRecord(record.nativeRecord.payload)
      ? record.nativeRecord.payload
      : undefined;
  const reasoning =
    record.category === "reasoning" ||
    nativePayload?.type === "reasoning" ||
    nativePayload?.type === "agent_reasoning";
  const displayableAgentReasoningText =
    record.nativeType === "event_msg.agent_reasoning" &&
    isRecord(record.nativeRecord) &&
    record.nativeRecord.type === "event_msg" &&
    nativePayload?.type === "agent_reasoning";
  const value = redactHistoryValue(
    record.nativeRecord,
    "",
    reasoning,
    displayableAgentReasoningText,
    0,
    added,
  );
  const redactedFields = deduplicateRedactions([
    ...record.redactedFields,
    ...added,
  ]);
  const byteCount = Buffer.byteLength(JSON.stringify(value));
  if (
    byteCount > MAX_NATIVE_RECORD_BYTES ||
    redactedFields.length > MAX_REDACTED_FIELDS
  ) {
    return Object.freeze({
      ...record,
      nativeRecord: Object.freeze({
        omitted_too_large: true,
        byte_count: byteCount,
      }),
      redactedFields: Object.freeze([
        {
          path: "",
          reason: "omitted_too_large" as const,
          byteCount,
        },
      ]),
    });
  }
  return Object.freeze({
    ...record,
    nativeRecord: value as RuntimeHistoryRecord["nativeRecord"],
    redactedFields: Object.freeze(redactedFields),
  });
};

const redactHistoryValue = (
  value: RuntimeHistoryJsonValue,
  pointer: string,
  inReasoningPayload: boolean,
  displayableAgentReasoningText: boolean,
  depth: number,
  redactedFields: RuntimeHistoryRedactedField[],
): RuntimeHistoryJsonValue => {
  if (depth > MAX_JSON_DEPTH) {
    redactedFields.push({
      path: manifestPath(pointer),
      reason: "omitted_too_large",
    });
    return "[OMITTED_TOO_LARGE]";
  }
  if (typeof value === "string") {
    const redacted = redactString(value);
    if (redacted !== value) {
      redactedFields.push({
        path: manifestPath(pointer),
        reason: redacted.includes("[REDACTED_PATH]")
          ? "physical_path"
          : "secret",
      });
    }
    return redacted;
  }
  if (value === null || typeof value !== "object") return value;
  if (Array.isArray(value)) {
    return Object.freeze(
      value.map((item, index) =>
        redactHistoryValue(
          item,
          `${pointer}/${index}`,
          inReasoningPayload,
          displayableAgentReasoningText,
          depth + 1,
          redactedFields,
        ),
      ),
    );
  }

  const output: Record<string, RuntimeHistoryJsonValue> = {};
  let reasoningContentPresent = false;
  for (const [key, item] of Object.entries(value)) {
    const childPointer = `${pointer}/${escapeJsonPointer(key)}`;
    const normalizedKey = normalizeFieldName(key);
    if (normalizedKey === "encrypted_content") {
      redactedFields.push({
        path: manifestPath(childPointer),
        reason: "encrypted_content",
      });
      if (inReasoningPayload) reasoningContentPresent = true;
      continue;
    }
    if (isSecretField(key)) {
      redactedFields.push({
        path: manifestPath(childPointer),
        reason: "secret",
      });
      continue;
    }
    if (
      inReasoningPayload &&
      (normalizedKey === "content" ||
        normalizedKey === "text" ||
        normalizedKey === "raw_content") &&
      !(displayableAgentReasoningText && childPointer === "/payload/text")
    ) {
      reasoningContentPresent = item !== null && item !== "";
      redactedFields.push({
        path: manifestPath(childPointer),
        reason: "reasoning_content",
      });
      continue;
    }
    output[key] = redactHistoryValue(
      item,
      childPointer,
      inReasoningPayload && normalizedKey !== "summary",
      displayableAgentReasoningText,
      depth + 1,
      redactedFields,
    );
  }
  if (inReasoningPayload && reasoningContentPresent) {
    output.content_present = true;
  }
  return Object.freeze(output);
};

const redactString = (value: string): string =>
  value
    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/giu, "Bearer [REDACTED]")
    .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/gu, "[REDACTED]")
    .replace(
      /\b(authorization|cookie|api[_-]?key|access[_-]?token|refresh[_-]?token|secret|password)\s*[:=]\s*[^\s,;]+/giu,
      "$1=[REDACTED]",
    )
    .replace(
      /(?:\/Users\/[^/\s"'`]+|\/home\/[^/\s"'`]+|\/(?:private\/)?tmp|\/private\/var|\/var\/(?:lib|folders))(?:\/[^\s"'`<>]*)?/gu,
      "[REDACTED_PATH]",
    )
    .replace(/[A-Za-z]:\\Users\\[^\s"'`<>]*/gu, "[REDACTED_PATH]");

const deduplicateRedactions = (
  values: readonly RuntimeHistoryRedactedField[],
): RuntimeHistoryRedactedField[] => {
  const seen = new Set<string>();
  const result: RuntimeHistoryRedactedField[] = [];
  for (const value of values) {
    const key = `${value.path}\u0000${value.reason}`;
    if (seen.has(key)) continue;
    seen.add(key);
    result.push(value);
  }
  return result;
};

const isSecretField = (key: string): boolean =>
  /^(?:authorization|cookie|set_cookie|secret|client_secret|password|private_key|api_key|token|access_token|refresh_token|session_token|bearer_token|id_token|credential|credentials)$/iu.test(
    normalizeFieldName(key),
  );

const normalizeFieldName = (key: string): string =>
  key
    .replace(/([a-z0-9])([A-Z])/gu, "$1_$2")
    .replace(/[-\s]+/gu, "_")
    .toLowerCase();

const escapeJsonPointer = (value: string): string =>
  value.replaceAll("~", "~0").replaceAll("/", "~1");

const manifestPath = (value: string): string => value.slice(0, 4_096);