@isparling/engram-coach 0.1.0 → 0.2.0

package/analysis-tools/tsb-predict.ts

@@ -0,0 +1,117 @@
+import { fileURLToPath } from 'url';
+import { resolve } from 'path';
+
+interface DayProjection {
+  day: number;
+  tss: number;
+  ctl: number;
+  atl: number;
+  tsb: number;
+}
+
+interface Projection {
+  initial: { ctl: number; atl: number; tsb: number };
+  projections: DayProjection[];
+}
+
+interface ProjectionOptions {
+  ctlTau?: number;
+  atlTau?: number;
+}
+
+function round1(n: number): number {
+  return Math.round(n * 10) / 10;
+}
+
+export function projectTSB(
+  ctl: number,
+  atl: number,
+  tssSequence: number[],
+  options?: ProjectionOptions,
+): Projection {
+  const ctlTau = options?.ctlTau ?? 42;
+  const atlTau = options?.atlTau ?? 7;
+
+  const projections: DayProjection[] = [];
+  let currentCtl = ctl;
+  let currentAtl = atl;
+
+  for (let i = 0; i < tssSequence.length; i++) {
+    const tss = tssSequence[i];
+    currentCtl = currentCtl * (1 - 1 / ctlTau) + tss / ctlTau;
+    currentAtl = currentAtl * (1 - 1 / atlTau) + tss / atlTau;
+    const roundedCtl = round1(currentCtl);
+    const roundedAtl = round1(currentAtl);
+    projections.push({
+      day: i + 1,
+      tss,
+      ctl: roundedCtl,
+      atl: roundedAtl,
+      tsb: round1(roundedCtl - roundedAtl),
+    });
+  }
+
+  return {
+    initial: { ctl, atl, tsb: round1(ctl - atl) },
+    projections,
+  };
+}
+
+// --- CLI entry point ---
+function parseArgs(args: string[]): {
+  ctl: number;
+  atl: number;
+  tss: number[];
+  ctlTau?: number;
+  atlTau?: number;
+} {
+  const flagValue = (name: string): string | undefined => {
+    const i = args.indexOf(name);
+    return i !== -1 && i + 1 < args.length ? args[i + 1] : undefined;
+  };
+
+  const ctl = flagValue('--ctl');
+  const atl = flagValue('--atl');
+  const tss = flagValue('--tss');
+
+  if (ctl === undefined || atl === undefined || tss === undefined) {
+    process.stderr.write(
+      'Usage: tsb-predict --ctl <number> --atl <number> --tss <n1,n2,...> [--ctl-tau <n>] [--atl-tau <n>]\n',
+    );
+    process.exit(1);
+  }
+
+  const ctlNum = Number(ctl);
+  const atlNum = Number(atl);
+  if (isNaN(ctlNum) || isNaN(atlNum)) {
+    process.stderr.write('Error: --ctl and --atl must be numbers\n');
+    process.exit(1);
+  }
+
+  const tssValues = tss.split(',').map(Number);
+  if (tssValues.some(isNaN)) {
+    process.stderr.write('Error: --tss values must be numbers (e.g., --tss 100,0,50)\n');
+    process.exit(1);
+  }
+
+  return {
+    ctl: ctlNum,
+    atl: atlNum,
+    tss: tssValues,
+    ctlTau: flagValue('--ctl-tau') ? Number(flagValue('--ctl-tau')) : undefined,
+    atlTau: flagValue('--atl-tau') ? Number(flagValue('--atl-tau')) : undefined,
+  };
+}
+
+// Only run CLI when executed directly (not imported)
+const isDirectExecution =
+  process.argv[1] !== undefined &&
+  fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+if (isDirectExecution) {
+  const parsed = parseArgs(process.argv.slice(2));
+  const result = projectTSB(parsed.ctl, parsed.atl, parsed.tss, {
+    ctlTau: parsed.ctlTau,
+    atlTau: parsed.atlTau,
+  });
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}

package/capture-handler.ts

@@ -0,0 +1,301 @@
+/**
+ * engram-coach ambient capture handler — candidate-only persistence.
+ *
+ * The extension calls this at awaited OMP `session_stop` with the latest user
+ * turn. Extraction itself lives in `engram-coach-ambient-capture.ts`; this
+ * module owns what happens to the result:
+ *
+ *   - canonical key derivation that never authorizes replacement;
+ *   - suppression of ambient candidates the explicit channel already applied
+ *     in this same turn;
+ *   - deterministic IDs plus create-only writes, so re-settling a turn cannot
+ *     duplicate a draft;
+ *   - a single scoped index refresh.
+ *
+ * Every record written here is `status: "candidate"` with empty relationship
+ * arrays. Ambient extraction proposes; it never retires or supersedes an
+ * active record before review. Every failure becomes a warning rather than an
+ * exception, so a slow or broken extraction model can never block the
+ * coaching response or the explicit Phase 5 path.
+ */
+
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import type {
+  JsonObject,
+  KnowledgeEnvelope,
+  KnowledgeRelationships,
+  TurnContext,
+  TurnToolCall,
+} from "@isparling/engram-harness/knowledge-types";
+import type { CompletionRequest } from "@isparling/engram-harness/capture-types";
+import type { CaptureSummary } from "./engram-coach-capture-types.ts";
+import {
+  extractAmbientCandidates,
+  type AmbientCandidate,
+} from "./engram-coach-ambient-capture.ts";
+import { loadEngramCoachConfig, type EngramCoachRuntimeConfig } from "./engram-coach-config.ts";
+import { deriveCanonicalEntityKey } from "./engram-coach-keys.ts";
+import { validateEnvelope } from "./engram-coach-reconciliation.ts";
+import { canonicalJson } from "./engram-coach-structured-capture.ts";
+
+/**
+ * Host mechanics supplied by the extension. It owns no coaching ontology: it
+ * only spawns the isolated completion, confines writes to the records root,
+ * and refreshes the scoped index.
+ */
+export type CaptureTools = {
+  recordsRoot: string;
+  spaceId: string;
+  projectRoot: string;
+  writeFile(path: string, content: string): Promise<void>;
+  refreshIndex(): Promise<void>;
+  complete(request: CompletionRequest): Promise<string>;
+};
+
+export type { CaptureSummary } from "./engram-coach-capture-types.ts";
+
+// ---------------------------------------------------------------------------
+// Duplicate suppression from explicit tool provenance
+// ---------------------------------------------------------------------------
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Entity keys a successful `engram_capture_apply` already committed in this
+ * same turn. Membership is decided at runtime over an unbounded key space, so
+ * a Set is the right structure here.
+ */
+export function appliedEntityKeys(toolCalls: readonly TurnToolCall[]): Set<string> {
+  const keys = new Set<string>();
+  for (const call of toolCalls) {
+    if (call.tool !== "engram_capture_apply") continue;
+    const result = call.result;
+    const parsed = typeof result === "string" ? safeJson(result) : result;
+    if (!isObject(parsed)) continue;
+    const status = parsed.status;
+    if (status !== "committed" && status !== "no-change" && status !== "records-committed") continue;
+    for (const key of stringArray(parsed.entity_keys)) keys.add(key);
+  }
+  return keys;
+}
+
+// ---------------------------------------------------------------------------
+// Record construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic ambient record ID. Session, the stable turn index, the
+ * candidate index, and canonical candidate content all participate, so
+ * re-settling the same turn with the same extraction reproduces the same ID —
+ * which is what makes create-only writes idempotent instead of duplicating.
+ */
+export function ambientRecordId(
+  sessionId: string,
+  turnIndex: number,
+  candidateIndex: number,
+  candidate: AmbientCandidate,
+): string {
+  const digest = createHash("sha256")
+    .update(canonicalJson({
+      sessionId,
+      turnIndex,
+      candidateIndex,
+      kind: candidate.kind,
+      statement: candidate.statement,
+      entityType: candidate.entityType,
+      keyedEntityType: candidate.keyedEntityType,
+      keyComponents: candidate.keyComponents,
+      effectiveAt: candidate.effectiveAt,
+    }))
+    .digest("hex")
+    .slice(0, 24);
+  return `coach-ambient-${digest}`;
+}
+
+const EMPTY_RELATIONSHIPS: KnowledgeRelationships = {
+  supports: [],
+  contradicts: [],
+  refines: [],
+  supersedes: [],
+};
+
+function serializeDraftRecord(envelope: KnowledgeEnvelope): string {
+  return [
+    "---",
+    "schema_version: 0",
+    `id: ${canonicalJson(envelope.id)}`,
+    `kind: ${canonicalJson(envelope.kind)}`,
+    `status: ${canonicalJson(envelope.status)}`,
+    `statement: ${canonicalJson(envelope.statement)}`,
+    `details: ${canonicalJson(envelope.details)}`,
+    `scope: ${canonicalJson(envelope.scope)}`,
+    `pack: ${canonicalJson(envelope.pack)}`,
+    `sources: ${canonicalJson(envelope.sources)}`,
+    `session: ${canonicalJson(envelope.session)}`,
+    `submitted_at: ${canonicalJson(envelope.submittedAt)}`,
+    `disposition: ${canonicalJson(envelope.disposition)}`,
+    `relationships: ${canonicalJson(EMPTY_RELATIONSHIPS)}`,
+    "history: []",
+    "---",
+    "## Statement",
+    "",
+    envelope.statement,
+    "",
+  ].join("\n");
+}
+
+function submittedDate(turnTimestamp: string): string {
+  return /^\d{4}-\d{2}-\d{2}/.exec(turnTimestamp)?.[0] ?? turnTimestamp;
+}
+
+function isAlreadyPresent(error: unknown): boolean {
+  return isObject(error) && error.code === "EEXIST";
+}
+
+/**
+ * Build the candidate envelope. A derivable key is recorded so review can find
+ * the entity it concerns; an underivable one records the diagnostic instead.
+ * Either way the record stays a candidate with empty relationships.
+ */
+function buildEnvelope(
+  candidate: AmbientCandidate,
+  id: string,
+  entityKey: string | null,
+  bindingError: string | null,
+  turn: TurnContext,
+  tools: CaptureTools,
+  config: EngramCoachRuntimeConfig,
+): KnowledgeEnvelope {
+  const details: JsonObject = {
+    captureChannel: "ambient",
+    entityKey,
+    activeProfile: config.activeProfile,
+  };
+  if (candidate.entityType !== null) details.entityType = candidate.entityType;
+  if (candidate.effectiveAt !== null) details.effectiveAt = candidate.effectiveAt;
+  if (Object.keys(candidate.keyComponents).length > 0) {
+    details.keyComponents = candidate.keyComponents;
+  }
+  if (bindingError !== null) details.bindingError = bindingError;
+
+  return {
+    id,
+    kind: candidate.kind,
+    status: "candidate",
+    statement: candidate.statement,
+    details,
+    scope: {
+      space: tools.spaceId,
+      subjects: candidate.subjects,
+      topics: candidate.topics,
+      contexts: [],
+      dimensions: {},
+    },
+    pack: { id: "engram-coach", version: "0.1.0" },
+    sources: [
+      { type: "session", ref: `session:${turn.session.id}/turn:${turn.turnIndex}` },
+      { type: "inference", ref: `llm-inference:${config.capture.model}` },
+    ],
+    session: turn.session,
+    submittedAt: submittedDate(turn.timestamp),
+    disposition: "new",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/** Ambient capture for one settled turn. Always resolves. */
+export async function captureFromTurn(
+  turn: TurnContext,
+  tools: CaptureTools,
+): Promise<CaptureSummary> {
+  const summary: CaptureSummary = { created: [], existing: [], invalid: [], warnings: [] };
+
+  const userText = turn.narrative.trim();
+  if (userText.length === 0) return summary;
+
+  let config: EngramCoachRuntimeConfig;
+  try {
+    config = await loadEngramCoachConfig({ projectRoot: tools.projectRoot });
+  } catch (error) {
+    summary.warnings.push(`ambient capture is not configured: ${String(error)}`);
+    return summary;
+  }
+
+  const extraction = await extractAmbientCandidates(userText, config, tools);
+  summary.warnings.push(...extraction.warnings);
+  if (extraction.candidates.length === 0) return summary;
+
+  const alreadyApplied = appliedEntityKeys(turn.toolCalls);
+
+  for (const [index, candidate] of extraction.candidates.entries()) {
+    let entityKey: string | null = null;
+    let bindingError: string | null = null;
+    if (candidate.keyedEntityType !== null) {
+      const derived = deriveCanonicalEntityKey({
+        entity_type: candidate.keyedEntityType,
+        key_components: candidate.keyComponents,
+      });
+      if (derived.kind === "bound") entityKey = derived.key;
+      else bindingError = derived.reason;
+    }
+
+    // The explicit channel already captured this key in this same turn, under
+    // athlete approval. Unrelated candidates from the turn are untouched.
+    if (entityKey !== null && alreadyApplied.has(entityKey)) continue;
+
+    const id = ambientRecordId(turn.session.id, turn.turnIndex, index, candidate);
+    const envelope = buildEnvelope(candidate, id, entityKey, bindingError, turn, tools, config);
+
+    const validation = validateEnvelope(envelope);
+    if (!validation.ok) {
+      summary.invalid.push({
+        id: envelope.id,
+        errors: validation.errors.map((error) => `${error.field ?? "envelope"}: ${error.message}`),
+      });
+      continue;
+    }
+
+    try {
+      await tools.writeFile(
+        join(tools.recordsRoot, `${envelope.id}.md`),
+        serializeDraftRecord(envelope),
+      );
+      summary.created.push(envelope.id);
+    } catch (error) {
+      if (isAlreadyPresent(error)) {
+        summary.existing.push(envelope.id);
+        continue;
+      }
+      summary.warnings.push(`ambient draft write failed for ${envelope.id}: ${String(error)}`);
+    }
+  }
+
+  if (summary.created.length > 0 || summary.existing.length > 0) {
+    try {
+      await tools.refreshIndex();
+    } catch (error) {
+      summary.warnings.push(`ambient index refresh failed: ${String(error)}`);
+    }
+  }
+  return summary;
+}

package/config.json.example

@@ -0,0 +1,21 @@
+{
+  "_comment": "Copy this file to config.json and edit values. config.json is gitignored. season is optional: if absent, adapt-plan will ask for it at runtime.",
+  "active_profile": "default",
+  "profiles": {
+    "default": {
+      "active_persona": "conservative",
+      "coaching_docs_dir": "~/REPLACE_WITH_YOUR_COACHING_DOCS_PATH",
+      "prescriptions_dir": "~/REPLACE_WITH_YOUR_PRESCRIPTIONS_PATH",
+      "season": "REPLACE_WITH_SEASON_LABEL"
+    }
+  },
+  "capture": {
+    "model": "REPLACE_WITH_PROVIDER/MODEL",
+    "timeout_seconds": 60,
+    "max_candidates_per_turn": 3
+  },
+  "intervals_icu": {
+    "api_key": "REPLACE_WITH_YOUR_API_KEY",
+    "athlete_id": "REPLACE_WITH_YOUR_ATHLETE_ID"
+  }
+}