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
16.3 KB
Raw Blame
/**
 * Skill drafts from mature vault pages
 * (salience-lifecycle-enrichment, unit 4, t_abaec26b).
 *
 * `skill-proposals.ts` mines continuity TELEMETRY: what the agent did,
 * repeatedly, in a shape a detector recognises. It has never read a vault
 * page. So the material an operator has already written down, verified and
 * reused - the pages that are the most obvious skill candidates in the
 * vault - was the one input the proposal queue could not see.
 *
 * This module is that input, gated three ways before a model is ever
 * asked for anything:
 *
 *   1. The CHEAP filter is the page-meta trio, the only three fields that
 *      apply to arbitrary user pages: `tier` must be `core` (operator
 *      intent), the lifecycle must not be stale (freshness), and
 *      `_confidence` must be `high`. Each is a separate dimension and each
 *      rejection is reported by name - a gate that answered "no candidates"
 *      would be indistinguishable from a vault nobody has tagged.
 *   2. The EVIDENCE floor is observed reuse. A page can be tagged core,
 *      fresh and high-confidence and still be something nobody has ever
 *      pulled back out; `observedReuseRates` is the only signal that says
 *      the material was actually USED, so it is the one that decides.
 *   3. The NEGATIVE signal is skill coverage. A page an installed skill
 *      already covers must not be drafted again: the second copy would
 *      shadow or be shadowed by the first, and `discoverSkills` would
 *      report a collision an operator never asked for.
 *
 * Drafting itself is envelope-mediated, and each ADMITTED page gets its
 * own: one page, one skill, one prompt carrying that page's content. The
 * returned draft is validated structurally ({@link SKILL_PAGE_DRAFT_SHAPE})
 * and semantically (the name has to be a legal directory name, which no
 * descriptor can say) and then STAGED as a pending proposal inside the
 * vault. Nothing reaches the skills root until a human accepts.
 */

import { existsSync, readFileSync } from "node:fs";
import { posix, relative } from "node:path";

import { resolveSkillsDir } from "../config.ts";
import { ensureInsideVault } from "../path-safety.ts";
import { discoverSkills, skillRoots } from "../surface/skills.ts";
import { EXCLUDED_DIRS, listVaultPages, slugify } from "../vault.ts";
import { buildNeedsLlmStep, type NeedsLlmStep } from "./llm-step.ts";
import { observedReuseRates } from "./observed-use.ts";
import {
  ageDaysFromIso,
  isStale,
  readLifecycle,
  type PageLifecycle,
} from "./page-meta/lifecycle.ts";
import { readConfidence, type PageConfidence } from "./page-meta/confidence.ts";
import { PAGE_TIER, readTier, type PageTier } from "./page-meta/tier.ts";
import { BRAIN_ROOT_REL } from "./paths.ts";
import {
  assertResponseCheck,
  registerResponseCheck,
  SEMANTIC_VIOLATION_CODES,
  semanticViolation,
  type SemanticViolation,
} from "./response-checks.ts";
import {
  assertResponseShape,
  SHAPE_ROOT_PATH,
  SKILL_PAGE_DRAFT_SHAPE,
  SKILL_PAGE_DRAFT_SURFACE,
} from "./response-shape.ts";
import {
  draftMaturePageSkillProposal,
  SKILL_NAME_RE,
  type DeclaredSkillProposalResult,
} from "./skill-proposals.ts";
import { BRAIN_CONFIDENCE } from "./types.ts";
import { MAINTENANCE_LANE_REACH } from "../graph/transport-reach.ts";

/** Lowest tier a page may carry and still be a skill candidate. */
export const MATURE_PAGE_TIER: PageTier = PAGE_TIER.core;

/** Lowest confidence a page may carry and still be a skill candidate. */
export const MATURE_PAGE_CONFIDENCE: PageConfidence = BRAIN_CONFIDENCE.high;

/**
 * Age past which a `stable` or `draft` page counts as stale. The page-meta
 * default is reused rather than re-picked: a page this module calls stale
 * and `o2b brain stale` calls fresh would be two answers to one question.
 */
export const MATURE_PAGE_STALE_DAYS = 180;

/**
 * Lowest observed-reuse score a page may carry. `observedReuseRates`
 * scores `(used - contradicted) / total` in [0, 1], so this floor demands
 * that a clear majority of the times the page was surfaced, it was used.
 */
export const MATURE_PAGE_REUSE_FLOOR = 0.5;

/** The needs-llm-step step name for a deferred skill draft. */
export const SKILL_PAGE_DRAFT_STEP = "skill-page-draft";

/** Per-page content budget in the prompt, so one long page cannot dominate. */
const PROMPT_PAGE_TEXT_MAX = 8000;

/**
 * Why a page is not a candidate. Closed, and one reason per page: the
 * FIRST gate that rejected it, in the order the gates run, so a reader
 * fixes the cheapest problem first.
 */
export const SKILL_PAGE_SKIP_REASON = Object.freeze({
  /** `tier` is below `core`. */
  tier: "tier_below_core",
  /** The lifecycle is stale for the page's age. */
  lifecycle: "lifecycle_stale",
  /** `_confidence` is below `high`. */
  confidence: "confidence_below_high",
  /** Nothing has reused the page often enough to evidence it. */
  reuse: "reuse_below_floor",
  /** An installed skill already covers the page. */
  covered: "covered_by_installed_skill",
} as const);

export type SkillPageSkipReason =
  (typeof SKILL_PAGE_SKIP_REASON)[keyof typeof SKILL_PAGE_SKIP_REASON];

/** A skill-page draft could not proceed, and the reason is in the message. */
export class SkillPageDraftError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "SkillPageDraftError";
  }
}

/** One page admitted for drafting, with the evidence that admitted it. */
export interface SkillPageCandidate {
  /** Vault-relative POSIX path - the identity every surface here uses. */
  readonly path: string;
  readonly title: string;
  readonly tier: PageTier;
  readonly lifecycle: PageLifecycle;
  readonly confidence: PageConfidence;
  /** Observed-reuse score in [0, 1]; at or above {@link MATURE_PAGE_REUSE_FLOOR}. */
  readonly reuseScore: number;
  /** How many observed-use verdicts the score was folded from. */
  readonly reuseObservations: number;
  readonly llmStep: NeedsLlmStep;
}

/** One page the gate turned down, named. */
export interface SkillPageSkip {
  readonly path: string;
  readonly title: string;
  readonly reason: SkillPageSkipReason;
  /** The measured value behind the reason, so the report is actionable. */
  readonly detail: string;
}

export interface SkillPageDraftPlan {
  readonly generatedAt: string;
  /** User pages walked, before any gate. */
  readonly pagesScanned: number;
  readonly admitted: ReadonlyArray<SkillPageCandidate>;
  readonly skipped: ReadonlyArray<SkillPageSkip>;
}

export interface PlanSkillPageDraftsOptions {
  readonly now: Date;
  /** Repo skills root, when the caller has one; used for coverage only. */
  readonly repoRoot?: string | null;
  /** Skills directory override; defaults to the configured `skills_dir`. */
  readonly skillsDir?: string | null;
}

export interface CommitSkillPageDraftOptions {
  readonly now: Date;
}

// ----- The semantic rule the descriptor language cannot express -------------
//
// The descriptor language has no pattern key and deliberately stays that
// way, so the `name` charset rule is a semantic check. The pattern itself
// is `SKILL_NAME_RE`, declared in `skill-proposals.ts` and imported here:
// the accept path re-applies it at materialize time, and one pattern in
// two spellings would let the two ends disagree about what a skill
// directory may be called.

/** Longest legal skill name; a directory name, not a sentence. */
const SKILL_NAME_MAX_LEN = 64;

registerResponseCheck(SKILL_PAGE_DRAFT_SURFACE, (payload) => {
  const violations: SemanticViolation[] = [];
  if (typeof payload !== "object" || payload === null) return violations;
  const name = (payload as { name?: unknown }).name;
  if (typeof name !== "string") return violations;
  const path = `${SHAPE_ROOT_PATH}.name`;
  if (!SKILL_NAME_RE.test(name)) {
    violations.push(
      semanticViolation(
        SEMANTIC_VIOLATION_CODES.crossItem,
        path,
        `must be a skill directory name - lowercase letters, digits and single hyphens; got ${JSON.stringify(name)}`,
      ),
    );
  }
  if (name.length > SKILL_NAME_MAX_LEN) {
    violations.push(
      semanticViolation(
        SEMANTIC_VIOLATION_CODES.threshold,
        path,
        `must be at most ${SKILL_NAME_MAX_LEN} characters; got ${name.length}`,
      ),
    );
  }
  return violations;
});

// ----- Phase one: which pages deserve a draft -------------------------------

/**
 * Walk the vault's user pages and decide which of them a skill should be
 * drafted from. Read-only; writes nothing and calls no model.
 *
 * The `Brain/` tree is excluded for the same reason `heal-run.ts` excludes
 * it: it is agent-owned bookkeeping, not the operator's knowledge, and the
 * page-meta trio is a statement about the latter.
 */
export function planSkillPageDrafts(
  vault: string,
  opts: PlanSkillPageDraftsOptions,
): SkillPageDraftPlan {
  const brainDir = BRAIN_ROOT_REL.split("/")[0] ?? "Brain";
  const pages = listVaultPages(vault, {
    skipDirs: [...EXCLUDED_DIRS, brainDir],
    reach: MAINTENANCE_LANE_REACH,
  });
  const reuse = observedReuseRates(vault);
  const covered = installedSkillNames(vault, opts);

  const admitted: SkillPageCandidate[] = [];
  const skipped: SkillPageSkip[] = [];

  for (const page of pages) {
    const rel = toPosixRel(vault, page.path);
    const title = page.title;
    const skip = (reason: SkillPageSkipReason, detail: string): void => {
      skipped.push(Object.freeze({ path: rel, title, reason, detail }));
    };

    const tier = readTier(page.metadata);
    if (tier !== MATURE_PAGE_TIER) {
      skip(SKILL_PAGE_SKIP_REASON.tier, `tier is '${tier}', not '${MATURE_PAGE_TIER}'`);
      continue;
    }
    const lifecycle = readLifecycle(page.metadata);
    const ageDays = ageDaysFromIso(pageInstant(page.metadata), opts.now);
    if (isStale(lifecycle, ageDays, MATURE_PAGE_STALE_DAYS)) {
      skip(
        SKILL_PAGE_SKIP_REASON.lifecycle,
        `lifecycle '${lifecycle}' is stale at ${Math.floor(ageDays)} day(s), past ${MATURE_PAGE_STALE_DAYS}`,
      );
      continue;
    }
    const confidence = readConfidence(page.metadata);
    if (confidence !== MATURE_PAGE_CONFIDENCE) {
      skip(
        SKILL_PAGE_SKIP_REASON.confidence,
        `confidence is '${confidence}', not '${MATURE_PAGE_CONFIDENCE}'`,
      );
      continue;
    }
    // The reuse ledger keys artifacts by whatever path the recorder had, so
    // both forms are consulted rather than assuming one.
    const observed = reuse.get(rel) ?? reuse.get(page.path);
    const score = observed?.score ?? 0;
    if (score < MATURE_PAGE_REUSE_FLOOR) {
      skip(
        SKILL_PAGE_SKIP_REASON.reuse,
        `observed reuse ${score.toFixed(2)} is below ${MATURE_PAGE_REUSE_FLOOR}` +
          ` over ${observed?.total ?? 0} observation(s)`,
      );
      continue;
    }
    const name = slugify(title);
    if (covered.has(name)) {
      skip(
        SKILL_PAGE_SKIP_REASON.covered,
        `an installed skill named '${name}' already covers this page`,
      );
      continue;
    }
    admitted.push(
      Object.freeze({
        path: rel,
        title,
        tier,
        lifecycle,
        confidence,
        reuseScore: score,
        reuseObservations: observed?.total ?? 0,
        llmStep: buildDraftStep(rel, title, name, readPageBody(page.path)),
      }),
    );
  }

  return Object.freeze({
    generatedAt: opts.now.toISOString(),
    pagesScanned: pages.length,
    admitted: Object.freeze(admitted),
    skipped: Object.freeze(skipped),
  });
}

/**
 * The envelope for one admitted page. The page's own content rides in the
 * prompt: the caller is writing a skill FROM this page, and a prompt that
 * merely named the file would invite it to write from memory instead.
 */
function buildDraftStep(
  rel: string,
  title: string,
  suggestedName: string,
  body: string,
): NeedsLlmStep {
  return buildNeedsLlmStep({
    step: SKILL_PAGE_DRAFT_STEP,
    prompt:
      `Write an Agent Skill from the vault page '${title}' (${rel}). The skill must teach an ` +
      "agent to do what the page describes, in imperative steps, without restating the page's " +
      `background. Suggested name: '${suggestedName}'.\n\n` +
      body.slice(0, PROMPT_PAGE_TEXT_MAX),
    schema_hints: [
      'payload: { "name", "description", "triggers": [...], "body" }',
      "name: skill directory name - lowercase letters, digits and single hyphens",
      "description: one line naming when an agent should reach for this skill",
      "triggers: keywords a matcher scores the skill on; at least one, each non-empty",
      "body: the SKILL.md body, imperative and self-contained",
    ],
    target_path: `${BRAIN_ROOT_REL}/skill-proposals/pending`,
  });
}

// ----- Phase two: what the caller drafted -----------------------------------

/**
 * Validate a returned draft and STAGE it as a pending proposal.
 *
 * The page path is validated against the vault before anything else -
 * confined to it, then required to exist: a draft citing a page that is
 * not there has no provenance, one citing a path outside the vault has
 * provenance this surface cannot vouch for, and a proposal whose only
 * evidence is a broken wikilink is worse than no proposal.
 */
export function commitSkillPageDraft(
  vault: string,
  pagePath: string,
  payload: unknown,
  opts: CommitSkillPageDraftOptions,
): DeclaredSkillProposalResult {
  const rel = pagePath.trim();
  if (rel.length === 0) {
    throw new SkillPageDraftError("a skill page draft needs the page it was drafted from");
  }
  // Confinement before existence: `rel` is caller-supplied, and a path
  // climbing out of the vault with `..` (or through a symlinked directory
  // inside it) could otherwise be confirmed to exist and then cited as
  // this proposal's provenance. The refusal is by name, like every other
  // one on this surface.
  let abs: string;
  try {
    abs = ensureInsideVault(posix.join(vault, rel), vault);
  } catch (err) {
    throw new SkillPageDraftError(
      `page path is not inside the vault: ${rel} (${(err as Error).message})`,
    );
  }
  if (!existsSync(abs)) {
    throw new SkillPageDraftError(`no such vault page: ${rel}`);
  }
  // Structure first, then the rules a descriptor cannot state. Nothing is
  // staged until both pass.
  assertResponseShape(SKILL_PAGE_DRAFT_SURFACE, SKILL_PAGE_DRAFT_SHAPE, payload);
  assertResponseCheck(SKILL_PAGE_DRAFT_SURFACE, payload);

  const draft = payload as {
    name: string;
    description: string;
    triggers: ReadonlyArray<string>;
    body: string;
  };
  return draftMaturePageSkillProposal(vault, {
    name: draft.name,
    description: draft.description,
    triggers: draft.triggers,
    body: draft.body,
    sourceRefs: [`[[${rel}]]`],
    now: opts.now,
  });
}

// ----- Internals ------------------------------------------------------------

/** Names of every skill installed on any root this vault can see. */
function installedSkillNames(vault: string, opts: PlanSkillPageDraftsOptions): ReadonlySet<string> {
  const skillsDir = opts.skillsDir ?? resolveSkillsDir();
  const roots = skillRoots({
    vault,
    ...(opts.repoRoot ? { repoRoot: opts.repoRoot } : {}),
    ...(skillsDir ? { skillsDir } : {}),
  });
  return new Set(discoverSkills(roots).map((skill) => slugify(skill.name)));
}

/**
 * The instant a page's age is measured from. `last_evidence_at` wins when
 * present - a page re-evidenced last week is not stale because it was
 * created two years ago - and `created_at` is the fallback.
 */
function pageInstant(meta: Readonly<Record<string, unknown>>): string | null {
  for (const key of ["last_evidence_at", "created_at"]) {
    const value = meta[key];
    if (typeof value === "string" && value.trim().length > 0) return value.trim();
  }
  return null;
}

/** Page body without its frontmatter block, for the prompt. */
function readPageBody(abs: string): string {
  let text: string;
  try {
    text = readFileSync(abs, "utf8");
  } catch (err) {
    // A page the walk listed and the read cannot open is a real fault, not
    // an empty page: drafting from silence would produce a plausible skill
    // grounded in nothing.
    throw new SkillPageDraftError(
      `could not read candidate page ${abs}: ${(err as Error).message ?? String(err)}`,
    );
  }
  if (!text.startsWith("---\n")) return text.trim();
  const end = text.indexOf("\n---", 4);
  return end < 0 ? text.trim() : text.slice(end + "\n---".length).trim();
}

function toPosixRel(vault: string, abs: string): string {
  return relative(vault, abs).split(/[\\/]/).join(posix.sep);
}