Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
9.0 KB
Raw Blame
/**
 * `systemone` adapter: `POST <base_url>/v1/systemone`.
 *
 * The wire format TypeSafe serves for Jev, and that OpenRouter, the
 * Vercel AI Gateway compatible route, OpenCode Zen and self-hosted
 * compatible servers also speak:
 *
 *   request   { model, state, questions: { id: { type, instructions, criteria } } }
 *   response  { model, answers: { id: { type, noul | choice + probabilities +
 *               confidence | score + legend + probabilities + confidence } },
 *               usage: { input_tokens, output_tokens, cost? } }
 *
 * Raw `fetch`, no vendor SDK. Network rules:
 *   - the base URL passed `assertHttpEgressEndpoint` at config resolution
 *     and is checked again here;
 *   - `redirect: "error"`, so no redirect carries the key or the state
 *     anywhere the operator did not configure;
 *   - the whole body passes `redactForEgress` before it is sent, and a
 *     refusal degrades with `egress_refused` rather than sending part;
 *   - the bearer header is sent only when a key is set (a self-hosted
 *     loopback server may need none);
 *   - the route's own `choice` limit (52 options for OpenJev, for
 *     example) is checked before sending, and a larger question degrades
 *     with `budget`;
 *   - retries, the reply size cap and error handling follow
 *     `transport.ts`.
 *
 * The Vercel AI Gateway `/v1/evaluate` variant (`vercel-evaluate.ts`)
 * extends this class and only renames fields, so both routes send through
 * this module's single `fetch` and its egress guard call.
 *
 * Errors name the env var that holds the key, never its value, and no
 * response body is ever logged or put into an error message.
 */

import { sha256Hex } from "../integrity/digest.ts";
import { redactForEgress } from "../egress/guard.ts";
import { assertHttpEgressEndpoint } from "../search/embeddings/http-util.ts";
import { CHOICE_MAX_OPTIONS, questionLimitViolation, validateAnswer } from "./answers.ts";
import {
  DecisionProviderError,
  type DecideOptions,
  type DecisionAnswer,
  type DecisionPingResult,
  type DecisionProvider,
  type DecisionQuestion,
  type DecisionRequest,
  type DecisionResponse,
  type DecisionUsage,
} from "./contract.ts";
import {
  answeringModel,
  decisionHttpError,
  fetchFailure,
  finiteNonNegative,
  isRecord,
  readAttempt,
  withOneRetry,
  type DecisionAttempt,
} from "./transport.ts";

export { MAX_REPLY_BYTES } from "./transport.ts";

/** The registry id this module is declared under in `EGRESS_SITES`. */
export const SYSTEMONE_EGRESS_SITE = "decision-model-systemone";

export interface SystemOneEndpoint {
  readonly name: string;
  readonly baseUrl: string;
  readonly model: string;
  /** NAME of the env var holding the key, for messages. */
  readonly envKey: string | null;
  /** Resolved at call time by the factory; never stored in config. */
  readonly apiKey: string | null;
  readonly allowInsecureHttp?: boolean;
  readonly calibrated: boolean;
  readonly timeoutMs: number;
  /** The route's own `choice` limit; defaults to the wire maximum (255). */
  readonly maxChoiceOptions?: number;
}

function readSnakeUsage(raw: unknown): DecisionUsage {
  if (!isRecord(raw)) return {};
  const inputTokens = finiteNonNegative(raw["input_tokens"]);
  const outputTokens = finiteNonNegative(raw["output_tokens"]);
  const costUsd = finiteNonNegative(raw["cost"]);
  return {
    ...(inputTokens !== undefined ? { inputTokens } : {}),
    ...(outputTokens !== undefined ? { outputTokens } : {}),
    ...(costUsd !== undefined ? { costUsd } : {}),
  };
}

export class SystemOneDecisionProvider implements DecisionProvider {
  readonly name: string;
  readonly model: string;
  readonly calibrated: boolean;
  private readonly url: string;
  private readonly endpoint: SystemOneEndpoint;

  constructor(endpoint: SystemOneEndpoint) {
    this.endpoint = endpoint;
    this.name = endpoint.name;
    this.model = endpoint.model;
    this.calibrated = endpoint.calibrated;
    const base = assertHttpEgressEndpoint(endpoint.baseUrl, "decision_model_base_url", {
      allowInsecureHttp: endpoint.allowInsecureHttp === true,
      key: "decision_model_allow_insecure_http",
    });
    this.url = `${base.replace(/\/+$/, "")}${this.path()}`;
  }

  /** The route's path below the base URL. */
  protected path(): string {
    return "/v1/systemone";
  }

  /** The questions as this route names them on the wire. */
  protected wireQuestions(
    questions: Readonly<Record<string, DecisionQuestion>>,
  ): Readonly<Record<string, unknown>> {
    return questions;
  }

  /** One reply item in the `systemone` answer shape `validateAnswer` reads. */
  protected canonicalAnswer(raw: unknown): unknown {
    return raw;
  }

  protected readUsage(json: Record<string, unknown>): DecisionUsage {
    return readSnakeUsage(json["usage"]);
  }

  async decide(req: DecisionRequest, opts: DecideOptions): Promise<DecisionResponse> {
    const limit = questionLimitViolation(
      req.questions,
      this.endpoint.maxChoiceOptions ?? CHOICE_MAX_OPTIONS,
    );
    if (limit !== null) throw new DecisionProviderError("budget", limit);

    // This adapter holds the resolved key it is about to send as a Bearer
    // credential, so it is a wired boundary: the body scan also carries
    // the key VALUE as a literal, scrubbing an occurrence that leaked
    // into the vault text the state and questions are built from - a
    // quiet string the shape passes cannot see. No key, no literal pass
    // (byte-identical to the bare guard).
    const verdict = redactForEgress(
      SYSTEMONE_EGRESS_SITE,
      {
        state: req.state,
        questions: req.questions,
      },
      this.endpoint.apiKey ? { resolvedLiterals: [this.endpoint.apiKey] } : {},
    );
    if (verdict.outcome !== "released") {
      throw new DecisionProviderError(
        "egress_refused",
        "decision request refused by the egress guard; nothing was sent",
      );
    }
    const body = JSON.stringify({
      model: this.model,
      state: verdict.payload.state,
      questions: this.wireQuestions(verdict.payload.questions),
    });
    const stateHash = sha256Hex(JSON.stringify(verdict.payload.state));

    const json = await withOneRetry(
      (signal) => this.send(body, signal, opts.timeoutMs),
      opts,
      (status) => decisionHttpError(status, this.endpoint.envKey),
    );
    return this.parse(json, req, stateHash);
  }

  /** One HTTP attempt. Throws on transport failure; returns the status otherwise. */
  private async send(
    body: string,
    signal: AbortSignal,
    timeoutMs: number,
  ): Promise<DecisionAttempt> {
    const headers: Record<string, string> = { "content-type": "application/json" };
    if (this.endpoint.apiKey !== null && this.endpoint.apiKey !== "") {
      headers["authorization"] = `Bearer ${this.endpoint.apiKey}`;
    }
    let response: Response;
    try {
      response = await fetch(this.url, {
        method: "POST",
        headers,
        body,
        // No redirect may carry the key or the state elsewhere.
        redirect: "error",
        signal,
      });
    } catch (e) {
      // A reset or refused connection, or a refused redirect. Never
      // retried: the provider may already have billed the call.
      throw fetchFailure(e, signal, timeoutMs);
    }
    return readAttempt(response, signal, timeoutMs);
  }

  private parse(json: unknown, req: DecisionRequest, stateHash: string): DecisionResponse {
    if (!isRecord(json) || !isRecord(json["answers"])) {
      throw new DecisionProviderError("invalid_reply", "decision reply has no answers map");
    }
    const rawAnswers = json["answers"];
    const answers: Record<string, DecisionAnswer> = {};
    for (const [id, question] of Object.entries(req.questions)) {
      answers[id] = validateAnswer(question, this.canonicalAnswer(rawAnswers[id]));
    }
    const model = answeringModel(json["model"], this.model);
    return Object.freeze({
      model,
      answers: Object.freeze(answers),
      usage: Object.freeze(this.readUsage(json)),
      calibrated: this.calibrated,
      stateHash,
    });
  }

  /**
   * One request over a synthetic state that carries no vault content, to
   * show the route answers and which model version answered.
   */
  async ping(): Promise<DecisionPingResult> {
    const started = Date.now();
    try {
      const res = await this.decide(
        {
          use: "rerank",
          state: { text: "Open Second Brain connectivity check." },
          questions: {
            ping: {
              type: "noul",
              instructions: "Is `text` a connectivity check message?",
            },
          },
        },
        { timeoutMs: this.endpoint.timeoutMs },
      );
      if (res.answers["ping"]?.valid !== true) {
        return {
          ok: false,
          reason: "invalid_reply",
          latencyMs: Date.now() - started,
          usage: res.usage,
        };
      }
      return { ok: true, model: res.model, latencyMs: Date.now() - started, usage: res.usage };
    } catch (e) {
      const reason = e instanceof DecisionProviderError ? e.reason : "network";
      return { ok: false, reason, latencyMs: Date.now() - started };
    }
  }
}