@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/components/telemetry/dist/provider-cache.js

@@ -0,0 +1,117 @@
+/**
+ * Local-only provider cache capability for Codex JSONL receipts.
+ *
+ * Codex exposes cache counters on `turn.completed.usage`. This adapter accepts
+ * only that receipt shape, keeps only bounded numeric counters, and never
+ * stores or returns prompt, transcript, model, provider, or response text.
+ * The SessionStart hook remains a deliberately inert no-op; callers opt into
+ * this measurement path explicitly with an already-parsed receipt event.
+ */
+const RECEIPT_SOURCE = "turn.completed.usage";
+export const PROVIDER_CACHE_RECEIPT_FIELDS = Object.freeze(["input_tokens", "cached_input_tokens"]);
+export const providerCacheCapability = Object.freeze({
+    state: "capable",
+    surface: RECEIPT_SOURCE,
+    receiptFields: PROVIDER_CACHE_RECEIPT_FIELDS,
+    storage: "local-only numeric measurement",
+    liveMeasurement: "unproven until a receipt arrives",
+    rawPayloads: "ignored",
+});
+/**
+ * Extract the cache counters from one Codex `turn.completed` JSONL event.
+ * Unknown event shapes and invalid counters are rejected without exposing
+ * their contents to callers.
+ */
+export function parseProviderCacheReceipt(event) {
+    if (!isRecord(event) || event["type"] !== "turn.completed")
+        return null;
+    const usage = event["usage"];
+    if (!isRecord(usage))
+        return null;
+    const inputTokens = nonNegativeSafeInteger(usage["input_tokens"]);
+    const cachedInputTokens = nonNegativeSafeInteger(usage["cached_input_tokens"]);
+    if (inputTokens === null || cachedInputTokens === null || cachedInputTokens > inputTokens)
+        return null;
+    return { inputTokens, cachedInputTokens };
+}
+/**
+ * Convert an explicit B0 plus ordered cumulative snapshots into per-turn
+ * deltas. Missing receipts are unavailable; malformed sequences are invalid.
+ * Neither outcome permits a cache claim from latency or event timing.
+ */
+export function measureProviderCacheReceipts(sequence) {
+    if (sequence.baseline === null)
+        return invalidMeasurement("missing-baseline");
+    if (sequence.snapshots.length === 0) {
+        return {
+            status: "unavailable",
+            source: RECEIPT_SOURCE,
+            receipts: 0,
+            reason: "no-authoritative-cache-fields",
+        };
+    }
+    if (!hasSafeCounters(sequence.baseline))
+        return invalidMeasurement("numeric-overflow");
+    if (sequence.baseline.cachedInputTokens > sequence.baseline.inputTokens) {
+        return invalidMeasurement("cached-counter-exceeds-input");
+    }
+    let inputTokens = 0;
+    let cachedInputTokens = 0;
+    let previous = sequence.baseline;
+    const deltas = [];
+    for (const snapshot of sequence.snapshots) {
+        if (!hasSafeCounters(snapshot))
+            return invalidMeasurement("numeric-overflow");
+        if (snapshot.cachedInputTokens > snapshot.inputTokens) {
+            return invalidMeasurement("cached-counter-exceeds-input");
+        }
+        if (snapshot.inputTokens < previous.inputTokens || snapshot.cachedInputTokens < previous.cachedInputTokens) {
+            return invalidMeasurement("counter-reset");
+        }
+        const inputDelta = snapshot.inputTokens - previous.inputTokens;
+        const cachedDelta = snapshot.cachedInputTokens - previous.cachedInputTokens;
+        if (inputDelta === 0)
+            return invalidMeasurement("zero-input-delta");
+        if (cachedDelta > inputDelta)
+            return invalidMeasurement("cached-delta-exceeds-input");
+        const nextInputTokens = safeAdd(inputTokens, inputDelta);
+        const nextCachedInputTokens = safeAdd(cachedInputTokens, cachedDelta);
+        if (nextInputTokens === null || nextCachedInputTokens === null) {
+            return invalidMeasurement("numeric-overflow");
+        }
+        deltas.push({
+            inputTokens: inputDelta,
+            cachedInputTokens: cachedDelta,
+            uncachedInputTokens: inputDelta - cachedDelta,
+        });
+        inputTokens = nextInputTokens;
+        cachedInputTokens = nextCachedInputTokens;
+        previous = snapshot;
+    }
+    return {
+        status: "measured",
+        source: RECEIPT_SOURCE,
+        receipts: sequence.snapshots.length,
+        inputTokens,
+        cachedInputTokens,
+        uncachedInputTokens: inputTokens - cachedInputTokens,
+        cacheHitRatio: cachedInputTokens / inputTokens,
+        deltas,
+    };
+}
+function invalidMeasurement(reason) {
+    return { status: "invalid", source: RECEIPT_SOURCE, receipts: 0, reason };
+}
+function hasSafeCounters(receipt) {
+    return (nonNegativeSafeInteger(receipt.inputTokens) !== null && nonNegativeSafeInteger(receipt.cachedInputTokens) !== null);
+}
+function nonNegativeSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+function safeAdd(left, right) {
+    const sum = left + right;
+    return Number.isSafeInteger(sum) ? sum : null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/marketplace/plugins/litcodex/components/telemetry/package.json

@@ -0,0 +1,22 @@
+{
+	"name": "@litcodex/telemetry",
+	"version": "1.0.0",
+	"description": "LitCodex telemetry: a deliberately inert, local-only SessionStart hook (NO network, NO data collection).",
+	"type": "module",
+	"private": true,
+	"bin": {
+		"litcodex-telemetry": "./dist/cli.js"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"postbuild": "node ../../../../scripts/mark-cli-executable.mjs --workspace .",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest --run --passWithNoTests=false"
+	},
+	"engines": {
+		"node": ">=22.0.0"
+	}
+}

package/marketplace/plugins/litcodex/components/wikify-knowledge/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: readonly string[], stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream, env?: NodeJS.ProcessEnv): Promise<number>;

package/marketplace/plugins/litcodex/components/wikify-knowledge/dist/cli.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { stdin as processStdin } from "node:process";
+import { fileURLToPath } from "node:url";
+import { captureKnowledgeEvent, reviewKnowledgeRecord, runPostToolUseHook, runUserPromptSubmitHook, } from "./knowledge.js";
+import { decodeStrictUtf8, parseStrictJson } from "./strict-json.js";
+const MAX_RAW_INPUT_BYTES = 8192;
+export async function main(argv, stdin, stdout, stderr, env = process.env) {
+    const [command, subcommand, id, state] = argv.slice(2);
+    if (command === "event" && subcommand === "capture") {
+        const input = await readJson(stdin);
+        if (!input.ok)
+            return writeError(stderr, "KNOWLEDGE_EVENT_INVALID", "The structured knowledge event is invalid.", 2);
+        try {
+            const result = captureKnowledgeEvent(input.value, { root: process.cwd(), env });
+            if (result.outcome === "rejected") {
+                return writeError(stderr, "KNOWLEDGE_EVENT_REJECTED", `The structured knowledge event was rejected: ${result.reason}.`, 2);
+            }
+            stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
+            return 0;
+        }
+        catch {
+            return writeError(stderr, "KNOWLEDGE_WRITE_FAILED", "The knowledge record was not written.", 1);
+        }
+    }
+    if (command === "review" && subcommand === "save" && id) {
+        return runReview(id, "accepted", stdout, stderr);
+    }
+    if (command === "review" && subcommand === "set" && id && isReviewState(state)) {
+        return runReview(id, state, stdout, stderr);
+    }
+    if (command === "hook" && subcommand === "user-prompt-submit") {
+        const input = await readJson(stdin);
+        if (!input.ok)
+            return 0;
+        try {
+            const output = runUserPromptSubmitHook(input.value);
+            if (output.length > 0)
+                stdout.write(output);
+            return 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    if (command === "hook" && subcommand === "post-tool-use") {
+        const input = await readJson(stdin);
+        if (!input.ok)
+            return 0;
+        try {
+            runPostToolUseHook(input.value, { env });
+        }
+        catch {
+            // PostToolUse runs after a successful tool call. A capture failure must not alter that result.
+        }
+        return 0;
+    }
+    stderr.write("Usage: litcodex-wikify-knowledge event capture | review save <id> | review set <id> <accepted|rejected|stale> | hook user-prompt-submit | hook post-tool-use\n");
+    return 2;
+    function runReview(recordId, reviewState, output, errorOutput) {
+        try {
+            const result = reviewKnowledgeRecord(recordId, reviewState, { root: process.cwd() });
+            if (result.outcome === "not-found") {
+                return writeError(errorOutput, "KNOWLEDGE_RECORD_NOT_FOUND", "The knowledge record does not exist.", 2);
+            }
+            output.write(`${JSON.stringify({ ok: true, ...result })}\n`);
+            return 0;
+        }
+        catch {
+            return writeError(errorOutput, "KNOWLEDGE_WRITE_FAILED", "The knowledge record was not written.", 1);
+        }
+    }
+}
+async function readJson(stdin) {
+    const chunks = [];
+    let byteLength = 0;
+    for await (const chunk of stdin) {
+        let bytes;
+        if (typeof chunk === "string") {
+            const length = Buffer.byteLength(chunk, "utf8");
+            if (byteLength + length > MAX_RAW_INPUT_BYTES)
+                return { ok: false };
+            bytes = Buffer.from(chunk, "utf8");
+        }
+        else if (Buffer.isBuffer(chunk)) {
+            if (byteLength + chunk.byteLength > MAX_RAW_INPUT_BYTES)
+                return { ok: false };
+            bytes = chunk;
+        }
+        else {
+            return { ok: false };
+        }
+        chunks.push(bytes);
+        byteLength += bytes.byteLength;
+    }
+    let text;
+    try {
+        text = decodeStrictUtf8(Buffer.concat(chunks, byteLength));
+    }
+    catch {
+        return { ok: false };
+    }
+    try {
+        return { ok: true, value: parseStrictJson(text) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function writeError(stderr, code, message, exitCode) {
+    stderr.write(`${JSON.stringify({ ok: false, error: { code, message } })}\n`);
+    return exitCode;
+}
+function isReviewState(value) {
+    return value === "accepted" || value === "rejected" || value === "stale";
+}
+if (isDirectInvocation()) {
+    main(process.argv, processStdin, process.stdout, process.stderr).then((code) => {
+        process.exitCode = code;
+    });
+}
+function isDirectInvocation() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}

package/marketplace/plugins/litcodex/components/wikify-knowledge/dist/knowledge.d.ts

@@ -0,0 +1,72 @@
+export declare const NORMAL_QUERY_BUDGET_BYTES = 2048;
+export declare const HARD_QUERY_BUDGET_BYTES = 4096;
+export declare const AUTO_CAPTURE_EVIDENCE_REF = "lit-loop/create_goal";
+declare const KINDS: readonly ["fact", "decision", "failure", "risk", "rule", "checkpoint"];
+declare const STATES: readonly ["review-needed", "accepted", "rejected", "stale"];
+declare const SOURCES: readonly ["wikify", "lit-loop", "start-work", "review-work"];
+type KnowledgeKind = (typeof KINDS)[number];
+type KnowledgeState = (typeof STATES)[number];
+type KnowledgeSource = (typeof SOURCES)[number];
+export interface KnowledgeRecord {
+    schemaVersion: 1;
+    id: string;
+    kind: KnowledgeKind;
+    state: KnowledgeState;
+    text: string;
+    timestamp: string;
+    provenance: {
+        product: "litcodex";
+        source: KnowledgeSource;
+    };
+    evidenceRef: string;
+}
+interface KnowledgeOptions {
+    root: string;
+    now?: () => string;
+    env?: Record<string, string | undefined>;
+}
+export type CaptureResult = {
+    outcome: "captured";
+    id: string;
+    state: "review-needed";
+} | {
+    outcome: "duplicate";
+    id: string;
+    state: KnowledgeState;
+} | {
+    outcome: "disabled";
+} | {
+    outcome: "rejected";
+    reason: string;
+};
+export type ReviewResult = {
+    outcome: "updated";
+    id: string;
+    state: Exclude<KnowledgeState, "review-needed">;
+} | {
+    outcome: "unchanged";
+    id: string;
+    state: Exclude<KnowledgeState, "review-needed">;
+} | {
+    outcome: "not-found";
+    id: string;
+};
+export interface QueryResult {
+    context: string;
+    records: KnowledgeRecord[];
+}
+export declare function captureKnowledgeEvent(input: unknown, options: KnowledgeOptions): CaptureResult;
+export declare function reviewKnowledgeRecord(id: string, state: Exclude<KnowledgeState, "review-needed">, options: KnowledgeOptions): ReviewResult;
+export declare function queryKnowledge(prompt: string, options: {
+    root: string;
+    budgetBytes?: number;
+}): QueryResult;
+export declare function runUserPromptSubmitHook(input: unknown, options?: {
+    root?: string;
+    budgetBytes?: number;
+}): string;
+export declare function runPostToolUseHook(input: unknown, options?: {
+    root?: string;
+    env?: Record<string, string | undefined>;
+}): string;
+export {};