crewhaus 0.1.8 → 0.2.0

package/dist/knowledge-sync.d.ts

@@ -0,0 +1,179 @@
+/** Thrown for operational failures. The CLI routes the message through
+ *  `die()`; tests assert on `.message`. */
+export declare class KnowledgeSyncError extends Error {
+    readonly name = "KnowledgeSyncError";
+}
+export declare const SHARED_DIR_DEFAULT = ".crewhaus-shared";
+export declare const KNOWLEDGE_MARKER_RELPATH = ".crewhaus/knowledge.json";
+/** sha256 hex of a normalized memory (text + sorted, deduped tags) — the
+ *  dedupe key, independent of tag order or the memory's own id/timestamp. */
+export declare function memoryContentHash(text: string, tags: ReadonlyArray<string>): string;
+/** sha256 hex of a file fragment's bytes (grader/prompt), trimmed. */
+export declare function fragmentContentHash(bytes: string): string;
+export type Provenance = {
+    /** The harness that pushed the artifact. */
+    readonly harness: string;
+    readonly pushedAt: string;
+};
+export type SharedMemory = {
+    readonly contentHash: string;
+    readonly text: string;
+    readonly tags: ReadonlyArray<string>;
+    readonly provenance: Provenance;
+};
+export type SharedFragment = {
+    readonly contentHash: string;
+    readonly kind: "grader" | "prompt";
+    readonly filename: string;
+    readonly contents: string;
+    readonly provenance: Provenance;
+};
+export type RedactionOutcome = {
+    readonly text: string;
+    /** True when a credential-shaped token remained AFTER redaction (drop it). */
+    readonly secretRemains: boolean;
+};
+/** Redactor seam: redact a string for pushing to the shared store. Production
+ *  wraps `@crewhaus/pii-redactor` + a token detector; tests inject a stub. */
+export type Redactor = (text: string) => Promise<RedactionOutcome>;
+/** A pass-through redactor (tests / --no-redact). Never flags tokens. */
+export declare const IDENTITY_REDACTOR: Redactor;
+/** The credential token shapes, each a global RegExp so `replace` masks every
+ *  occurrence. Order matters only for the PEM block (masked whole, first). */
+export declare const KNOWLEDGE_SECRET_DETECTORS: ReadonlyArray<{
+    kind: string;
+    regex: RegExp;
+}>;
+/** True when `text` still contains something credential-shaped — used as the
+ *  `secretRemains` verdict AFTER redaction so anything suspicious is dropped. */
+export declare function looksLikeSecret(text: string): boolean;
+/**
+ * Mask every credential-shaped token in `text` with `***`. PEM blocks are
+ * masked whole. Pure + synchronous — the PII pass is layered on top by
+ * {@link buildKnowledgeRedactor}.
+ */
+export declare function maskKnowledgeSecrets(text: string): string;
+/** Primitive PII pass injected into {@link buildKnowledgeRedactor}: redact PII
+ *  and return the cleaned text. Production wraps `@crewhaus/pii-redactor`;
+ *  tests can inject an identity pass to exercise only the credential layer. */
+export type PiiPass = (text: string) => Promise<string>;
+/**
+ * Build the production knowledge redactor: run a PII pass, then mask every
+ * credential-shaped token, then re-scan the result with the STRICT
+ * {@link looksLikeSecret} heuristic — anything that still looks like a secret
+ * sets `secretRemains` so the caller DROPS the artifact rather than share a
+ * leaked credential.
+ *
+ * The `piiPass` is injected so this is unit-testable without the redactor
+ * package (the CLI wires the real `@crewhaus/pii-redactor` pass).
+ */
+export declare function buildKnowledgeRedactor(piiPass: PiiPass): Redactor;
+/** Whether a harness has opted into knowledge sharing (marker file with
+ *  `{ share: true }`). */
+export declare function harnessOptedIn(harnessDir: string): boolean;
+type RawMemory = {
+    text: string;
+    tags: ReadonlyArray<string>;
+};
+/** Read every memory-store entry across a harness's `.crewhaus/memories/*.jsonl`. */
+export declare function readHarnessMemories(harnessDir: string): RawMemory[];
+/** Read a harness's grader fragment (first of the candidate paths present). */
+export declare function readHarnessGraders(harnessDir: string): {
+    filename: string;
+    contents: string;
+} | undefined;
+/** Read a harness's prompt fragments (`.crewhaus/prompts/*.md`). */
+export declare function readHarnessPrompts(harnessDir: string): Array<{
+    filename: string;
+    contents: string;
+}>;
+/** Upper bound on a shared memory's text length. A shared store is untrusted
+ *  input on pull; an absurdly long "memory" is a poisoning / DoS vector, never
+ *  a real lesson. 64 KiB is far above any genuine memory. */
+export declare const MAX_SHARED_MEMORY_TEXT: number;
+/**
+ * Validate one parsed shared-memory record (F6). A pulled record is UNTRUSTED:
+ * the file could have been hand-edited to poison the harness's dedupe (a lying
+ * `contentHash` so a malicious `text` masquerades as an already-trusted entry)
+ * or to bloat it (oversized text / malformed tags). Returns the record when it
+ * is a well-formed {@link SharedMemory} whose stored `contentHash` MATCHES the
+ * recomputed hash of its own text+tags; otherwise a `reason` for the skip.
+ */
+export declare function validateSharedMemory(rec: unknown): {
+    ok: true;
+    memory: SharedMemory;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Read the shared memories.jsonl. Missing → []. Each record is validated as a
+ *  proper {@link SharedMemory} with a matching content hash (F6); invalid
+ *  records are SKIPPED with a warning to stderr, never loaded. */
+export declare function readSharedMemories(sharedDir: string): SharedMemory[];
+/** Read the shared fragments of a kind (`graders/` or `prompts/`). */
+export declare function readSharedFragments(sharedDir: string, kind: "grader" | "prompt"): SharedFragment[];
+/** A fragment file carries a first-line provenance comment
+ *  `#! crewhaus-knowledge {json}`; split it from the body. */
+export declare function splitProvenanceHeader(contents: string): {
+    provenance?: Provenance;
+    body: string;
+};
+/** Prepend a provenance header line to a fragment body. */
+export declare function withProvenanceHeader(body: string, provenance: Provenance): string;
+export type PushPlan = {
+    readonly memories: ReadonlyArray<SharedMemory>;
+    readonly fragments: ReadonlyArray<SharedFragment>;
+    /** Memories dropped because a token survived redaction. */
+    readonly droppedSecrets: ReadonlyArray<string>;
+    /** Artifacts already present in the shared store (deduped away). */
+    readonly skippedDuplicates: number;
+};
+/**
+ * Plan a push: redact each harness memory, drop any whose text still carries a
+ * credential-shaped token, hash the rest, and keep only artifacts whose
+ * content hash is NEW to the shared store. Pure over the injected redactor +
+ * the current shared hashes. Grader/prompt fragments are redacted too (a
+ * lesson can quote a key).
+ */
+export declare function planPush(opts: {
+    readonly harness: string;
+    readonly memories: ReadonlyArray<RawMemory>;
+    readonly graders?: {
+        filename: string;
+        contents: string;
+    } | undefined;
+    readonly prompts: ReadonlyArray<{
+        filename: string;
+        contents: string;
+    }>;
+    readonly existingMemoryHashes: ReadonlySet<string>;
+    readonly existingFragmentHashes: ReadonlySet<string>;
+    readonly redact: Redactor;
+    readonly now: () => Date;
+}): Promise<PushPlan>;
+/** Write a push plan into the shared store (append memories, write fragment
+ *  files, append the manifest log). Not called in --dry-run. */
+export declare function applyPush(sharedDir: string, plan: PushPlan, now: () => Date): void;
+export type PullPlan = {
+    /** Shared memories NOT already present in the harness. */
+    readonly memories: ReadonlyArray<SharedMemory>;
+    readonly fragments: ReadonlyArray<SharedFragment>;
+    readonly skippedDuplicates: number;
+};
+/**
+ * Plan a pull: shared artifacts whose content hash the harness does not
+ * already have. Pure over the harness's existing hashes.
+ */
+export declare function planPull(opts: {
+    readonly sharedMemories: ReadonlyArray<SharedMemory>;
+    readonly sharedFragments: ReadonlyArray<SharedFragment>;
+    readonly harnessMemoryHashes: ReadonlySet<string>;
+    readonly harnessFragmentHashes: ReadonlySet<string>;
+}): PullPlan;
+/** Write a pull plan into a harness: append memories to a shared-memories
+ *  JSONL the memory-store already reads, and drop fragment files into
+ *  `.crewhaus/prompts` / a `graders.shared.yaml`. Not called in --dry-run. */
+export declare function applyPull(harnessDir: string, plan: PullPlan, now: () => Date): void;
+export declare function formatPushReport(harness: string, plan: PushPlan, dryRun: boolean): ReadonlyArray<string>;
+export declare function formatPullReport(harness: string, plan: PullPlan, dryRun: boolean): ReadonlyArray<string>;
+export {};