@remnic/core 1.1.12 → 1.1.13

package/src/replay/types.ts

@@ -0,0 +1,143 @@
+import { parseIsoUtcTimestamp } from "../utils/iso-timestamp.js";
+
+export type ReplaySource = "openclaw" | "claude" | "chatgpt";
+export type ReplayRole = "user" | "assistant";
+
+export interface ReplayTurn {
+  source: ReplaySource;
+  sessionKey: string;
+  role: ReplayRole;
+  content: string;
+  timestamp: string;
+  sourceValidAt?: string;
+  externalId?: string;
+  metadata?: Record<string, unknown>;
+  parts?: import("../message-parts/index.js").LcmMessagePartInput[];
+  rawContent?: unknown;
+  sourceFormat?: import("../message-parts/index.js").MessagePartSourceFormat;
+}
+
+export interface ReplayWarning {
+  code: string;
+  message: string;
+  index?: number;
+}
+
+export interface ReplayValidationIssue {
+  code: string;
+  message: string;
+  index?: number;
+}
+
+export interface ReplayParseOptions {
+  from?: string;
+  to?: string;
+  defaultSessionKey?: string;
+  strict?: boolean;
+}
+
+export interface ReplayParseResult {
+  turns: ReplayTurn[];
+  warnings: ReplayWarning[];
+}
+
+export interface ReplayNormalizer {
+  source: ReplaySource;
+  parse(input: unknown, options?: ReplayParseOptions): Promise<ReplayParseResult> | ReplayParseResult;
+}
+
+const VALID_SOURCES: ReadonlySet<string> = new Set(["openclaw", "claude", "chatgpt"]);
+const VALID_ROLES: ReadonlySet<string> = new Set(["user", "assistant"]);
+export const REPLAY_UNKNOWN_SESSION_KEY = "replay:unknown";
+
+export function isReplaySource(value: unknown): value is ReplaySource {
+  return typeof value === "string" && VALID_SOURCES.has(value);
+}
+
+export function isReplayRole(value: unknown): value is ReplayRole {
+  return typeof value === "string" && VALID_ROLES.has(value);
+}
+
+export function normalizeReplaySessionKey(value: unknown): string {
+  if (typeof value !== "string") return REPLAY_UNKNOWN_SESSION_KEY;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : REPLAY_UNKNOWN_SESSION_KEY;
+}
+
+/**
+ * Strict UTC-only ISO-8601 parser used by the replay pipeline.
+ *
+ * Delegates to the shared parser in `utils/iso-timestamp.ts` — do not
+ * reimplement locally; extend that helper instead. Replay intentionally
+ * rejects timezone-offset timestamps to keep canonical form consistent
+ * across recorded transcripts.
+ */
+export function parseIsoTimestamp(value: string): number | null {
+  return parseIsoUtcTimestamp(value);
+}
+
+export function validateReplayTurn(turn: ReplayTurn, index?: number): ReplayValidationIssue[] {
+  const issues: ReplayValidationIssue[] = [];
+  if (!turn || typeof turn !== "object") {
+    issues.push({
+      code: "turn.invalid",
+      message: "Replay turn must be an object.",
+      index,
+    });
+    return issues;
+  }
+
+  if (!isReplayRole(turn.role)) {
+    issues.push({
+      code: "turn.role.invalid",
+      message: `Replay role must be 'user' or 'assistant', received '${String(turn.role)}'.`,
+      index,
+    });
+  }
+
+  if (!isReplaySource(turn.source)) {
+    issues.push({
+      code: "turn.source.invalid",
+      message: `Replay source must be 'openclaw', 'claude', or 'chatgpt', received '${String(turn.source)}'.`,
+      index,
+    });
+  }
+
+  if (!turn.sessionKey || typeof turn.sessionKey !== "string" || turn.sessionKey.trim().length === 0) {
+    issues.push({
+      code: "turn.sessionKey.invalid",
+      message: "Replay sessionKey is required.",
+      index,
+    });
+  }
+
+  if (!turn.content || typeof turn.content !== "string" || turn.content.trim().length === 0) {
+    issues.push({
+      code: "turn.content.invalid",
+      message: "Replay content must be a non-empty string.",
+      index,
+    });
+  }
+
+  if (!turn.timestamp || typeof turn.timestamp !== "string" || parseIsoTimestamp(turn.timestamp) === null) {
+    issues.push({
+      code: "turn.timestamp.invalid",
+      message: `Replay timestamp must be a valid ISO timestamp, received '${String(turn.timestamp)}'.`,
+      index,
+    });
+  }
+
+  if (
+    turn.sourceValidAt !== undefined &&
+    (typeof turn.sourceValidAt !== "string" ||
+      parseIsoTimestamp(turn.sourceValidAt) === null)
+  ) {
+    issues.push({
+      code: "turn.sourceValidAt.invalid",
+      message: `Replay sourceValidAt must be a valid ISO timestamp when provided, received '${String(turn.sourceValidAt)}'.`,
+      index,
+    });
+  }
+
+  return issues;
+}

package/src/rerank.test.ts

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { rerankLocalOrNoop } from "./rerank.js";
+
+test("rerankLocalOrNoop tags rerank requests as recall-critical", async () => {
+  const calls: Array<{
+    messages: Array<{ role: string; content: string }>;
+    options?: {
+      maxTokens?: number;
+      temperature?: number;
+      timeoutMs?: number;
+      operation?: string;
+      priority?: "recall-critical" | "background";
+    };
+  }> = [];
+
+  const rankedIds = await rerankLocalOrNoop({
+    query: "API rate limit issue",
+    candidates: [
+      { id: "a", snippet: "API rate limit is 1000 requests per minute." },
+      { id: "b", snippet: "Deployment note." },
+    ],
+    local: {
+      async chatCompletion(messages, options) {
+        calls.push({ messages, options });
+        return {
+          content: JSON.stringify({
+            scores: [
+              { id: "a", score: 90 },
+              { id: "b", score: 10 },
+            ],
+          }),
+        };
+      },
+    },
+    enabled: true,
+    timeoutMs: 1_500,
+    maxCandidates: 5,
+    cacheEnabled: false,
+    cacheTtlMs: 60_000,
+  });
+
+  assert.deepEqual(rankedIds, ["a", "b"]);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0]?.options?.operation, "rerank");
+  assert.equal(calls[0]?.options?.priority, "recall-critical");
+});

package/src/rerank.ts

@@ -0,0 +1,176 @@
+export interface RerankCandidate {
+  id: string;
+  originalIndex: number;
+}
+
+export interface RerankScore {
+  id: string;
+  score: number;
+}
+
+export interface RerankCacheEntry {
+  expiresAtMs: number;
+  rankedIds: string[];
+}
+
+export class RerankCache {
+  private entries = new Map<string, RerankCacheEntry>();
+
+  get(key: string): string[] | null {
+    const e = this.entries.get(key);
+    if (!e) return null;
+    if (Date.now() > e.expiresAtMs) {
+      this.entries.delete(key);
+      return null;
+    }
+    return e.rankedIds;
+  }
+
+  set(key: string, rankedIds: string[], ttlMs: number): void {
+    this.entries.set(key, { rankedIds, expiresAtMs: Date.now() + ttlMs });
+  }
+}
+
+/**
+ * Parse a rerank response (JSON) and return candidates sorted by score.
+ *
+ * Rules:
+ * - Unknown IDs in the response are ignored.
+ * - Candidates missing from the response keep relative order after scored ones.
+ * - Stable tie-breaker: originalIndex ascending.
+ */
+export function parseRerankResponse(
+  raw: string,
+  candidates: RerankCandidate[],
+): Array<RerankCandidate & { score?: number }> {
+  const byId = new Map<string, RerankCandidate>();
+  for (const c of candidates) byId.set(c.id, c);
+
+  const scores = new Map<string, number>();
+  try {
+    const parsed = JSON.parse(raw) as { scores?: Array<Partial<RerankScore>> };
+    if (Array.isArray(parsed.scores)) {
+      for (const s of parsed.scores) {
+        if (!s || typeof s.id !== "string") continue;
+        if (!byId.has(s.id)) continue;
+        if (typeof s.score !== "number" || !Number.isFinite(s.score)) continue;
+        scores.set(s.id, s.score);
+      }
+    }
+  } catch {
+    // Ignore parse errors and fall back to original order.
+  }
+
+  const withScore = candidates.map((c) => ({
+    ...c,
+    score: scores.get(c.id),
+  }));
+
+  return withScore.sort((a, b) => {
+    const as = a.score;
+    const bs = b.score;
+    if (typeof as === "number" && typeof bs === "number") {
+      if (bs !== as) return bs - as;
+      return a.originalIndex - b.originalIndex;
+    }
+    if (typeof as === "number") return -1;
+    if (typeof bs === "number") return 1;
+    return a.originalIndex - b.originalIndex;
+  });
+}
+
+function stableKey(query: string, ids: string[]): string {
+  // Keep it simple and deterministic; this is not a security boundary.
+  return `${query.trim().toLowerCase()}|${ids.join(",")}`;
+}
+
+function clampSnippet(snippet: string, maxChars: number): string {
+  const s = snippet.replace(/\s+/g, " ").trim();
+  return s.length > maxChars ? s.slice(0, maxChars) : s;
+}
+
+export async function rerankLocalOrNoop(opts: {
+  query: string;
+  candidates: Array<{ id: string; snippet: string }>;
+  local: {
+    chatCompletion: (
+      messages: Array<{ role: string; content: string }>,
+      options?: {
+        maxTokens?: number;
+        temperature?: number;
+        timeoutMs?: number;
+        operation?: string;
+        priority?: "recall-critical" | "background";
+      },
+    ) => Promise<{ content: string } | null>;
+  };
+  enabled: boolean;
+  timeoutMs: number;
+  maxCandidates: number;
+  cache?: RerankCache;
+  cacheEnabled: boolean;
+  cacheTtlMs: number;
+}): Promise<string[] | null> {
+  if (!opts.enabled) return null;
+
+  const ids = opts.candidates.slice(0, opts.maxCandidates).map((c) => c.id);
+  if (ids.length <= 1) return ids;
+
+  const key = stableKey(opts.query, ids);
+  if (opts.cache && opts.cacheEnabled) {
+    const cached = opts.cache.get(key);
+    if (cached) return cached;
+  }
+
+  const payload = opts.candidates.slice(0, opts.maxCandidates).map((c) => ({
+    id: c.id,
+    snippet: clampSnippet(c.snippet, 400),
+  }));
+
+  const system =
+    "You are a ranking system. Return JSON only. No markdown, no commentary.";
+  const user = JSON.stringify(
+    {
+      task: "rerank",
+      query: opts.query,
+      candidates: payload,
+      output: {
+        scores: [{ id: "string", score: "number 0-100" }],
+      },
+      rules: [
+        "Assign higher score to more relevant candidates.",
+        "Prefer durability and direct relevance to the query.",
+        "If unsure, keep scores close together.",
+      ],
+    },
+    null,
+    0,
+  );
+
+  const res = await opts.local.chatCompletion(
+    [
+      { role: "system", content: system },
+      { role: "user", content: user },
+    ],
+    {
+      maxTokens: 800,
+      temperature: 0.0,
+      timeoutMs: opts.timeoutMs,
+      operation: "rerank",
+      priority: "recall-critical",
+    },
+  );
+  if (!res?.content) return null;
+
+  const parsed = parseRerankResponse(
+    res.content,
+    ids.map((id, i) => ({ id, originalIndex: i })),
+  );
+  const rankedIds = parsed.map((p) => p.id);
+
+  if (opts.cache && opts.cacheEnabled) {
+    opts.cache.set(key, rankedIds, opts.cacheTtlMs);
+  }
+
+  return rankedIds;
+}

package/src/resolve-auth-token.test.ts

@@ -0,0 +1,226 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  clearAuthTokenSecretCache,
+  isAgentAccessSecretRef,
+  resolveAgentAccessAuthToken,
+} from "./resolve-auth-token.js";
+
+test("resolveAgentAccessAuthToken passes through plain strings", async () => {
+  clearAuthTokenSecretCache();
+  const result = await resolveAgentAccessAuthToken("plain-bearer-token");
+  assert.equal(result, "plain-bearer-token");
+});
+
+test("resolveAgentAccessAuthToken trims surrounding whitespace", async () => {
+  clearAuthTokenSecretCache();
+  const result = await resolveAgentAccessAuthToken("  spaced-token  ");
+  assert.equal(result, "spaced-token");
+});
+
+test("resolveAgentAccessAuthToken returns undefined for empty / undefined input", async () => {
+  clearAuthTokenSecretCache();
+  assert.equal(await resolveAgentAccessAuthToken(undefined), undefined);
+  assert.equal(await resolveAgentAccessAuthToken(""), undefined);
+  assert.equal(await resolveAgentAccessAuthToken("   "), undefined);
+});
+
+test("resolveAgentAccessAuthToken delegates SecretRef objects to gateway resolver", async () => {
+  clearAuthTokenSecretCache();
+  const calls: unknown[] = [];
+  const resolveSecretRef = async (ref: any) => {
+    calls.push(ref);
+    return "resolved-secret-value";
+  };
+
+  try {
+    const result = await resolveAgentAccessAuthToken(
+      {
+        source: "exec",
+        provider: "kc_openclaw_remnic_token",
+        id: "value",
+      },
+      { resolveSecretRef },
+    );
+    assert.equal(result, "resolved-secret-value");
+    assert.equal(calls.length, 1);
+    assert.deepEqual(calls[0], {
+      source: "exec",
+      provider: "kc_openclaw_remnic_token",
+      id: "value",
+    });
+  } finally {
+    clearAuthTokenSecretCache();
+  }
+});
+
+test("resolveAgentAccessAuthToken trims SecretRef resolver output", async () => {
+  clearAuthTokenSecretCache();
+
+  try {
+    const result = await resolveAgentAccessAuthToken(
+      {
+        source: "exec",
+        provider: "kc_openclaw_remnic_token",
+        id: "value",
+      },
+      { resolveSecretRef: async () => "  resolved-secret-value\n" },
+    );
+    assert.equal(result, "resolved-secret-value");
+  } finally {
+    clearAuthTokenSecretCache();
+  }
+});
+
+test("resolveAgentAccessAuthToken caches resolved SecretRef values", async () => {
+  clearAuthTokenSecretCache();
+  let callCount = 0;
+  const resolveSecretRef = async () => {
+    callCount += 1;
+    return "cached-token";
+  };
+
+  try {
+    const ref = { source: "exec", provider: "kc_x", id: "value" };
+    const first = await resolveAgentAccessAuthToken(ref, { resolveSecretRef });
+    const second = await resolveAgentAccessAuthToken(ref, { resolveSecretRef });
+    // Same shape but different object reference — should still hit cache
+    const third = await resolveAgentAccessAuthToken({ ...ref }, { resolveSecretRef });
+    assert.equal(first, "cached-token");
+    assert.equal(second, "cached-token");
+    assert.equal(third, "cached-token");
+    assert.equal(callCount, 1);
+  } finally {
+    clearAuthTokenSecretCache();
+  }
+});
+
+test("resolveAgentAccessAuthToken cache key is order-independent", async () => {
+  clearAuthTokenSecretCache();
+  let callCount = 0;
+  const resolveSecretRef = async () => {
+    callCount += 1;
+    return "stable-token";
+  };
+
+  try {
+    await resolveAgentAccessAuthToken(
+      { source: "exec", provider: "p", id: "v" },
+      { resolveSecretRef },
+    );
+    await resolveAgentAccessAuthToken(
+      { id: "v", provider: "p", source: "exec" },
+      { resolveSecretRef },
+    );
+    assert.equal(callCount, 1, "key sort should make order-permuted refs share a cache slot");
+  } finally {
+    clearAuthTokenSecretCache();
+  }
+});
+
+test("resolveAgentAccessAuthToken throws when no SecretRef resolver is provided", async () => {
+  clearAuthTokenSecretCache();
+
+  await assert.rejects(
+    () =>
+      resolveAgentAccessAuthToken({
+        source: "exec",
+        provider: "kc_x",
+        id: "value",
+      }),
+    /SecretRef resolver was not provided|cannot resolve/i,
+  );
+});
+
+test("resolveAgentAccessAuthToken throws on missing source field", async () => {
+  clearAuthTokenSecretCache();
+  await assert.rejects(
+    () =>
+      resolveAgentAccessAuthToken({
+        provider: "no-source-field",
+      } as unknown as Parameters<typeof resolveAgentAccessAuthToken>[0]),
+    /missing required `source` field/,
+  );
+  await assert.rejects(
+    () =>
+      resolveAgentAccessAuthToken({
+        source: "   ",
+      } as unknown as Parameters<typeof resolveAgentAccessAuthToken>[0]),
+    /missing required `source` field/,
+  );
+});
+
+test("resolveAgentAccessAuthToken throws when SecretRef resolves to empty string", async () => {
+  clearAuthTokenSecretCache();
+  try {
+    await assert.rejects(
+      () =>
+        resolveAgentAccessAuthToken(
+          {
+            source: "exec",
+            provider: "kc_x",
+            id: "value",
+          },
+          { resolveSecretRef: async () => "" },
+        ),
+      /resolved to empty value/,
+    );
+  } finally {
+    clearAuthTokenSecretCache();
+  }
+});
+
+test("resolveAgentAccessAuthToken surfaces resolver errors with context", async () => {
+  clearAuthTokenSecretCache();
+  const resolveSecretRef = async () => {
+    throw new Error("keychain locked");
+  };
+  try {
+    await assert.rejects(
+      () =>
+        resolveAgentAccessAuthToken(
+          {
+            source: "exec",
+            provider: "kc_x",
+            id: "value",
+          },
+          { resolveSecretRef },
+        ),
+      /failed to resolve.*SecretRef.*keychain locked/,
+    );
+  } finally {
+    clearAuthTokenSecretCache();
+  }
+});
+
+test("resolveAgentAccessAuthToken does not cache failed resolutions", async () => {
+  clearAuthTokenSecretCache();
+  let callCount = 0;
+  const resolveSecretRef = async () => {
+    callCount += 1;
+    if (callCount === 1) throw new Error("transient");
+    return "second-try-success";
+  };
+  try {
+    const ref = { source: "exec", provider: "kc_x", id: "value" };
+    await assert.rejects(() => resolveAgentAccessAuthToken(ref, { resolveSecretRef }));
+    const second = await resolveAgentAccessAuthToken(ref, { resolveSecretRef });
+    assert.equal(second, "second-try-success");
+    assert.equal(callCount, 2);
+  } finally {
+    clearAuthTokenSecretCache();
+  }
+});
+
+test("isAgentAccessSecretRef recognizes SecretRef shapes", () => {
+  assert.equal(isAgentAccessSecretRef({ source: "exec", provider: "x" }), true);
+  assert.equal(isAgentAccessSecretRef({ source: "env" }), true);
+  assert.equal(isAgentAccessSecretRef("plain-string"), false);
+  assert.equal(isAgentAccessSecretRef(undefined), false);
+  assert.equal(isAgentAccessSecretRef(null), false);
+  assert.equal(isAgentAccessSecretRef({}), false);
+  assert.equal(isAgentAccessSecretRef({ source: "" }), false);
+  assert.equal(isAgentAccessSecretRef({ source: "   " }), false);
+  assert.equal(isAgentAccessSecretRef([1, 2, 3]), false);
+});