@litfamily/litopencode 1.0.9 → 1.0.11

package/dist/activation.d.ts

@@ -1,6 +1,7 @@
 import type { Hooks, PluginInput } from "@opencode-ai/plugin";
 import type { SessionLookup } from "./session-lineage.ts";
 import type { BoundedAuthorityOptions } from "./bounded-authority.ts";
+import { type JevSkillHintPart } from "./jev-skill-hint.ts";
 export { litHandoffPromptInjection, scientificVisualizationPromptInjection } from "./activation-managed-prompts.ts";
 export { litActivationBanner } from "./activation-prompt-utils.ts";
 export { litLoopPromptInjection, litPlanPromptInjection } from "./activation-primary-prompts.ts";
@@ -9,6 +10,12 @@ export { comprehendPromptInjection, debuggingPromptInjection, deepInterviewPromp
 type ChatMessageHook = NonNullable<Hooks["chat.message"]>;
 type ActivationToastClient = Pick<PluginInput["client"], "tui">;
 export declare function showActivationToast(client: ActivationToastClient | undefined, skillId: string, env?: NodeJS.ProcessEnv): void;
+/**
+ * One quiet `info` toast per hinted turn; notes, `none` and silent turns never reach it. On the first
+ * eligible turn of a session (`announce`) the standout ON notice goes out instead, with that turn's hint
+ * as its body: the TUI keeps a single toast, so a second one would replace the notice at once.
+ */
+export declare function showJevSkillHintToast(client: ActivationToastClient | undefined, hint: JevSkillHintPart | undefined, announce?: boolean): void;
 export type ChatMessageActivationOptions = {
     readonly getSession?: SessionLookup;
     readonly hostArgv?: readonly string[];
@@ -17,11 +24,12 @@ export type ChatMessageActivationOptions = {
     readonly onScientificVisualizationActivation?: (sessionID: string) => void;
     readonly onRootUserTurn?: (sessionID: string) => void | Promise<void>;
     readonly onSkillActivation?: (sessionID: string, skillId: string, appendedLit?: boolean) => void | Promise<void>;
-    readonly trustedInjectedSkill?: (sessionID: string, parts: readonly {
-        readonly type: string;
-        readonly metadata?: {
-            readonly [key: string]: unknown;
-        };
-    }[]) => string | undefined;
+    /** Consumes the skill a trusted command activation recorded for this session, if any. */
+    readonly trustedInjectedSkill?: (sessionID: string) => string | undefined;
+    /** Restores that skill after the root-turn reset; the command already showed its activation toast. */
+    readonly onTrustedSkillResume?: (sessionID: string, skillId: string) => void | Promise<void>;
+    /** Consumes the mark `command.execute.before` left for this session's next message. */
+    readonly isCommandTurn?: (sessionID: string) => boolean;
+    readonly skillHint?: (sessionID: string, promptText: string) => Promise<JevSkillHintPart | undefined>;
 };
 export declare function createChatMessageActivationHook(projectRoot: string, options?: ChatMessageActivationOptions): ChatMessageHook;

package/dist/activation.js

@@ -7,6 +7,7 @@ import { isReadOnlyWorkflowFamilyPlan } from "./workflow-families.js";
 import { queryKnowledge } from "./knowledge.js";
 import { activationDiscipline } from "./activation-probe.js";
 import { micro, supportsMarkGlyphs } from "./lit-mark.js";
+import { jevSkillHintAwarenessText, jevSkillHintToastText } from "./jev-skill-hint.js";
 // Prompt modules preserve minimum-first, single-task or few-task planning, avoidable custom code review,
 // and external-source safety; this module only coordinates their unchanged activation surfaces.
 export { litHandoffPromptInjection, scientificVisualizationPromptInjection } from "./activation-managed-prompts.js";
@@ -33,6 +34,32 @@ export function showActivationToast(client, skillId, env = process.env) {
         // The activation prompt is the primary surface; this toast is best-effort UI feedback.
     }
 }
+/**
+ * One quiet `info` toast per hinted turn; notes, `none` and silent turns never reach it. On the first
+ * eligible turn of a session (`announce`) the standout ON notice goes out instead, with that turn's hint
+ * as its body: the TUI keeps a single toast, so a second one would replace the notice at once.
+ */
+export function showJevSkillHintToast(client, hint, announce = false) {
+    const hinted = hint?.kind === "hint" ? jevSkillHintToastText(hint.skillId, hint.latencyMs) : undefined;
+    let body;
+    if (announce) {
+        body = hinted === undefined
+            ? { message: jevSkillHintAwarenessText, variant: "warning" }
+            : { title: jevSkillHintAwarenessText, message: hinted, variant: "warning" };
+    }
+    else if (hinted !== undefined) {
+        body = { message: hinted, variant: "info" };
+    }
+    else {
+        return;
+    }
+    try {
+        const pending = client?.tui?.showToast({ body });
+        void pending?.catch(() => undefined);
+    }
+    catch { // no-excuse-ok: catch -- a missing or failing TUI must never block the user message.
+    }
+}
 const knownSubagentAgentNames = new Set([
     ...litOpenCodeAgents.filter((agent) => agent.mode !== "primary").map((agent) => agent.id),
     "build",
@@ -64,13 +91,16 @@ export function createChatMessageActivationHook(projectRoot, options = {}) {
         if (processedOutputs.has(output))
             return;
         processedOutputs.add(output);
+        // Command marks are keyed by session and consumed here, on every turn: the host hands this hook a
+        // new parts array, so the array `command.execute.before` saw can never be matched by identity.
+        const commandTurn = options.isCommandTurn?.(input.sessionID) === true;
+        const trustedInjectedSkill = options.trustedInjectedSkill?.(input.sessionID);
         const agent = input.agent ?? (typeof output.message.agent === "string" ? output.message.agent : undefined);
         const childSession = await isChildSessionMessage(input.sessionID, agent, options.getSession);
         if (!childSession) {
-            const trustedInjectedSkill = options.trustedInjectedSkill?.(input.sessionID, output.parts);
             await options.onRootUserTurn?.(input.sessionID);
             if (trustedInjectedSkill !== undefined) {
-                await options.onSkillActivation?.(input.sessionID, trustedInjectedSkill);
+                await options.onTrustedSkillResume?.(input.sessionID, trustedInjectedSkill);
                 return;
             }
         }
@@ -111,6 +141,30 @@ export function createChatMessageActivationHook(projectRoot, options = {}) {
                 // A malformed or unreadable knowledge store stays silent instead of inventing context.
             }
         }
+        // The optional skill hint only speaks on root turns that no command or deterministic route claimed.
+        if (!childSession && mode === undefined && options.skillHint !== undefined && !commandTurn) {
+            const promptText = nonEmptyTextParts
+                .filter((part) => part.synthetic !== true)
+                .map((part) => part.text)
+                .join("\n");
+            try {
+                const hint = await options.skillHint(input.sessionID, promptText);
+                if (hint !== undefined) {
+                    output.parts.push({
+                        id: `prt_litopencode_skill_hint_${idSuffix(input.messageID ?? output.message.id)}`,
+                        sessionID: input.sessionID,
+                        messageID: input.messageID ?? output.message.id,
+                        type: "text",
+                        text: hint.text,
+                        // Sent to the model like any text part, but not shown or copied as the user's own words.
+                        synthetic: true,
+                        metadata: { litopencodeSkillHint: { kind: hint.kind, source: "chat.message" } }
+                    });
+                }
+            }
+            catch { // no-excuse-ok: catch -- the optional hint must never block the user message.
+            }
+        }
         if (mode === undefined || childSession)
             return;
         const trigger = mode === "lit-handoff" ? "handoff" : mode === "lit-scientific-visualization" ? mode : "lit";

package/dist/cli/doctor.js

@@ -12,6 +12,7 @@ import { inspectHostLimits } from "./host-limits.js";
 import { inspectLspCapability } from "./lsp-capability.js";
 import { probeMotionRuntime } from "./motion-runtime.js";
 import { isLitOpenCodeEntry } from "./plugin-mutation.js";
+import { jevSkillHintDoctorLine } from "../jev-skill-hint.js";
 import { autoUpdateInstallLockPath, autoUpdateJournalPath, autoUpdateReceiptPath, isAutoUpdateDisabled, readAutoUpdateReceipt } from "./auto-update.js";
 function pluginSpec(metadata) {
     return metadata.name + "@" + metadata.version;
@@ -122,6 +123,7 @@ export async function doctor(root) {
             hostLimits: { path: hostConfig.path, ...inspectHostLimits(hostConfig.config) },
             lsp: inspectLspCapability(hostConfig.config),
             motion,
+            jevSkillHint: jevSkillHintDoctorLine(process.env),
             config: {
                 source: loaded.source,
                 sources: loaded.sources,

package/dist/jev-skill-hint.d.ts

@@ -0,0 +1,50 @@
+export declare const jevEndpoint = "https://api.typesafe.ai/v1/systemone";
+export declare const jevFlag = "LITOPENCODE_JEV";
+/** Shown once per session so a user who switched the hint on notices it; never carries the key. */
+export declare const jevSkillHintAwarenessText = "\u2726 Jev skill hint is ON";
+export type JevFetch = (url: string, init: RequestInit) => Promise<Response>;
+export type JevCatalogEntry = {
+    readonly id: string;
+    readonly description: string;
+};
+export type JevSkillHintStatus = "off" | "on" | "key-missing";
+export type JevSkillHintPart = {
+    readonly kind: "hint";
+    readonly text: string;
+    readonly skillId: string;
+    readonly latencyMs: number;
+} | {
+    readonly kind: "note";
+    readonly text: string;
+};
+export type JevSkillHintOptions = {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly fetch?: JevFetch;
+    readonly catalog?: readonly JevCatalogEntry[];
+    readonly traceFile?: string;
+    /** Project root: every folder between it and the trace file must be a real folder, never a symlink. */
+    readonly traceRoot?: string;
+    readonly now?: () => number;
+};
+export declare function jevSkillHintStatus(env?: NodeJS.ProcessEnv): JevSkillHintStatus;
+export declare function jevSkillHintDoctorLine(env?: NodeJS.ProcessEnv): string;
+export declare function jevSkillHintText(skillId: string): string;
+/** The visible toast names only the validated skill id and the request latency. */
+export declare function jevSkillHintToastText(skillId: string, latencyMs: number): string;
+export declare function jevSkillHintUnavailableText(reason: string): string;
+/** Eligibility that depends on the prompt text alone; routing and command checks live in the hook. */
+export declare function isJevEligiblePrompt(text: string): boolean;
+/**
+ * Redact a bounded window first, then truncate, so a secret that straddles the 2,000-character cut is
+ * masked whole. When either cut happened, a token run left dangling at the end is masked as well.
+ */
+export declare function redactJevPrompt(text: string): string;
+export declare function defaultJevCatalog(): readonly JevCatalogEntry[];
+export declare function buildJevRequestBody(state: string, catalog: readonly JevCatalogEntry[], model: string): string;
+export type JevSkillHint = {
+    hintFor(sessionID: string, promptText: string): Promise<JevSkillHintPart | undefined>;
+    /** True exactly once per session: on its first eligible turn while both switches are on. */
+    claimAwareness(sessionID: string, promptText: string): boolean;
+    forget(sessionID: string): void;
+};
+export declare function createJevSkillHint(options?: JevSkillHintOptions): JevSkillHint;

package/dist/jev-skill-hint.js

@@ -0,0 +1,318 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { litOpenCodeRuntimeSkills } from "./skills.js";
+// Optional Jev skill hint for the chat.message hook. It is off unless LITOPENCODE_JEV=1 and
+// TYPESAFE_API_KEY are both set in the process environment. The key is read from the environment
+// only and goes nowhere except the Authorization header: not into errors, notes, traces or doctor.
+// The response is untrusted data; the only text that reaches the turn is this module's own fixed
+// sentence carrying a skill id that was checked against the catalog this module sent.
+export const jevEndpoint = "https://api.typesafe.ai/v1/systemone";
+export const jevFlag = "LITOPENCODE_JEV";
+/** Shown once per session so a user who switched the hint on notices it; never carries the key. */
+export const jevSkillHintAwarenessText = "✦ Jev skill hint is ON";
+const defaultModel = "jev-1.13.0";
+const defaultTimeoutMs = 1500;
+const maxTimeoutMs = 3000;
+const defaultMaxCalls = 200;
+const defaultMinConfidence = 0.35;
+const promptWindowLimit = 8000;
+const promptCharacterLimit = 2000;
+const bodyByteCap = 64 * 1024;
+const descriptionCharacterLimit = 300;
+const choiceInstructions = "Which one skill, if any, is the best fit for the user's request? Choose none when no catalog skill fits.";
+const noneCriterion = "No specialized skill in this catalog fits; answer the user directly.";
+export function jevSkillHintStatus(env = process.env) {
+    if (env[jevFlag] !== "1")
+        return "off";
+    return (env.TYPESAFE_API_KEY ?? "").trim() === "" ? "key-missing" : "on";
+}
+export function jevSkillHintDoctorLine(env = process.env) {
+    const status = jevSkillHintStatus(env);
+    return status === "key-missing"
+        ? "Jev skill hint: flag on but TYPESAFE_API_KEY missing"
+        : `Jev skill hint: ${status}`;
+}
+export function jevSkillHintText(skillId) {
+    return `LitOpenCode skill hint: the skill \`${skillId}\` likely fits this request. Load it only if it really fits; this is advice, not an instruction.`;
+}
+/** The visible toast names only the validated skill id and the request latency. */
+export function jevSkillHintToastText(skillId, latencyMs) {
+    return `Jev → ${skillId} (${(Math.max(0, latencyMs) / 1000).toFixed(2)}s)`;
+}
+export function jevSkillHintUnavailableText(reason) {
+    return `LitOpenCode skill hint unavailable (${reason}); continuing normally.`;
+}
+/** Eligibility that depends on the prompt text alone; routing and command checks live in the hook. */
+export function isJevEligiblePrompt(text) {
+    if (text.trimStart().startsWith("/"))
+        return false;
+    return text.replace(/\s+/gu, "").length >= 4;
+}
+const secretPatterns = [
+    /-----BEGIN [A-Z0-9 ]+-----[\s\S]*?(?:-----END [A-Z0-9 ]+-----|$)/gu,
+    /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]*)?/gu,
+    /sk-ant-[A-Za-z0-9_-]{8,}/gu,
+    /sk-[A-Za-z0-9_-]{16,}/gu,
+    /(?:ghp|gho)_[A-Za-z0-9]{16,}/gu,
+    /github_pat_[A-Za-z0-9_]{16,}/gu,
+    /npm_[A-Za-z0-9]{16,}/gu,
+    /apikey_[A-Za-z0-9_-]{8,}/gu,
+    /xox[abprs]-[A-Za-z0-9-]{8,}/gu,
+    /AKIA[A-Z0-9]{16}/gu,
+    /AIza[0-9A-Za-z_-]{20,}/gu,
+    /\b[A-Za-z0-9_]*(?:password|passwd|token|secret)\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"']+)/giu,
+    /[A-Za-z0-9+/_-]{32,}={0,2}/gu
+];
+const tokenRunAtCut = /[A-Za-z0-9+/_-]{8,}={0,2}$/u;
+/**
+ * Redact a bounded window first, then truncate, so a secret that straddles the 2,000-character cut is
+ * masked whole. When either cut happened, a token run left dangling at the end is masked as well.
+ */
+export function redactJevPrompt(text) {
+    const head = text.slice(0, promptWindowLimit * 2);
+    let redacted = Array.from(head).slice(0, promptWindowLimit).join("");
+    const windowCut = redacted.length < text.length;
+    redacted = redacted
+        .replace(/\/(?:Users|home)\/[^/\s]+/gu, "~")
+        .replace(/[A-Za-z]:\\Users\\[^\\/\s]+(\\)?/giu, (_match, separator) => (separator === undefined ? "~" : "~/"));
+    // The lookbehind starts a match only at the head of a run, which keeps the 8,000-character window linear.
+    redacted = redacted.replace(/(?<![A-Za-z0-9._%+-])[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}/gu, "[email]");
+    for (const pattern of secretPatterns)
+        redacted = redacted.replace(pattern, "[secret]");
+    const characters = Array.from(redacted);
+    if (!windowCut && characters.length <= promptCharacterLimit)
+        return redacted;
+    return characters.slice(0, promptCharacterLimit).join("").replace(tokenRunAtCut, "[secret]");
+}
+export function defaultJevCatalog() {
+    return litOpenCodeRuntimeSkills.map((skill) => ({ id: skill.id, description: skill.summary }));
+}
+export function buildJevRequestBody(state, catalog, model) {
+    const criteria = {};
+    for (const entry of catalog)
+        criteria[entry.id] = Array.from(entry.description).slice(0, descriptionCharacterLimit).join("");
+    criteria.none = noneCriterion;
+    return JSON.stringify({
+        model,
+        state,
+        questions: { which: { type: "choice", instructions: choiceInstructions, criteria } }
+    });
+}
+function boundedInteger(raw, fallback, min, max) {
+    if (raw === undefined || !/^\d+$/u.test(raw.trim()))
+        return fallback;
+    return Math.min(max, Math.max(min, Number(raw.trim())));
+}
+function minConfidence(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return defaultMinConfidence;
+    const value = Number(raw);
+    return Number.isFinite(value) && value >= 0 && value <= 1 ? value : defaultMinConfidence;
+}
+async function readCappedBody(response) {
+    const declared = Number(response.headers.get("content-length") ?? "");
+    if (Number.isFinite(declared) && declared > bodyByteCap) {
+        await response.body?.cancel().catch(() => undefined);
+        return undefined;
+    }
+    if (response.body === null)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > bodyByteCap) {
+            await reader.cancel().catch(() => undefined);
+            return undefined;
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function validatedAnswer(raw, allowed, threshold) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { failure: "invalid response" };
+    }
+    const which = parsed?.answers?.which;
+    if (typeof which !== "object" || which === null)
+        return { failure: "invalid response" };
+    const { choice, confidence } = which;
+    if (typeof choice !== "string" || !allowed.has(choice))
+        return { failure: "invalid response" };
+    if (typeof confidence !== "number" || !Number.isFinite(confidence))
+        return { failure: "invalid response" };
+    if (choice === "none" || confidence < threshold)
+        return { confidence };
+    return { choice, confidence };
+}
+/**
+ * Walks the trace folder below the project root one level at a time, creating a missing folder
+ * without following links. Any symlink or non-folder on the way means no trace.
+ */
+async function realTraceFolder(root, folder) {
+    const relative = path.relative(root, folder);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        return false;
+    let current = root;
+    for (const segment of relative.split(path.sep).filter((part) => part !== "")) {
+        current = path.join(current, segment);
+        let stat = await fs.lstat(current).catch(() => undefined);
+        if (stat === undefined) {
+            await fs.mkdir(current).catch(() => undefined);
+            stat = await fs.lstat(current).catch(() => undefined);
+        }
+        if (stat === undefined || stat.isSymbolicLink() || !stat.isDirectory())
+            return false;
+    }
+    return true;
+}
+export function createJevSkillHint(options = {}) {
+    const env = options.env ?? process.env;
+    const fetchImpl = options.fetch ?? ((url, init) => fetch(url, init));
+    const now = options.now ?? Date.now;
+    const sessions = new Map();
+    async function trace(record) {
+        if (env[`${jevFlag}_TRACE`] !== "1" || options.traceFile === undefined)
+            return;
+        const folder = path.dirname(options.traceFile);
+        const root = options.traceRoot ?? path.dirname(folder);
+        try {
+            if (!(await realTraceFolder(root, folder)))
+                return;
+            // Refuse a symlink or other non-file at the trace path; O_NOFOLLOW closes the lstat race.
+            const existing = await fs.lstat(options.traceFile).catch(() => undefined);
+            if (existing !== undefined && !existing.isFile())
+                return;
+            const flags = fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | (fsConstants.O_NOFOLLOW ?? 0);
+            const handle = await fs.open(options.traceFile, flags, 0o600);
+            try {
+                // A folder swapped for a symlink after the first check still gets no record.
+                if (!(await realTraceFolder(root, folder)))
+                    return;
+                await handle.appendFile(`${JSON.stringify(record)}\n`, "utf8");
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch { // no-excuse-ok: catch -- the opt-in debug trace must never affect the turn.
+        }
+    }
+    async function ask(state, key) {
+        const catalog = options.catalog ?? defaultJevCatalog();
+        const model = (env[`${jevFlag}_MODEL`] ?? "").trim() || defaultModel;
+        const body = buildJevRequestBody(state, catalog, model);
+        if (Buffer.byteLength(body, "utf8") > bodyByteCap)
+            return { failure: "request too large" };
+        const timeoutMs = boundedInteger(env[`${jevFlag}_TIMEOUT_MS`], defaultTimeoutMs, 1, maxTimeoutMs);
+        const controller = new AbortController();
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                resolve({ failure: "timeout" });
+            }, timeoutMs);
+        });
+        const request = (async () => {
+            let response;
+            try {
+                response = await fetchImpl(jevEndpoint, {
+                    method: "POST",
+                    headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+                    body,
+                    redirect: "error",
+                    signal: controller.signal
+                });
+            }
+            catch {
+                return { failure: controller.signal.aborted ? "timeout" : "network" };
+            }
+            if (response.status !== 200) {
+                await response.body?.cancel().catch(() => undefined);
+                return { httpStatus: response.status, failure: `HTTP ${response.status}` };
+            }
+            let raw;
+            try {
+                raw = await readCappedBody(response);
+            }
+            catch {
+                return { httpStatus: 200, failure: controller.signal.aborted ? "timeout" : "network" };
+            }
+            if (raw === undefined)
+                return { httpStatus: 200, failure: "response too large" };
+            const allowed = new Set([...catalog.map((entry) => entry.id), "none"]);
+            return { httpStatus: 200, ...validatedAnswer(raw, allowed, minConfidence(env[`${jevFlag}_MIN_CONFIDENCE`])) };
+        })();
+        try {
+            return await Promise.race([request, timedOut]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return {
+        forget(sessionID) {
+            sessions.delete(sessionID);
+        },
+        claimAwareness(sessionID, promptText) {
+            if (jevSkillHintStatus(env) !== "on" || !isJevEligiblePrompt(promptText))
+                return false;
+            const session = sessions.get(sessionID) ?? { calls: 0, noted: false, announced: false };
+            sessions.set(sessionID, session);
+            if (session.announced)
+                return false;
+            session.announced = true;
+            return true;
+        },
+        async hintFor(sessionID, promptText) {
+            if (jevSkillHintStatus(env) !== "on" || !isJevEligiblePrompt(promptText))
+                return undefined;
+            const key = (env.TYPESAFE_API_KEY ?? "").trim();
+            const session = sessions.get(sessionID) ?? { calls: 0, noted: false, announced: false };
+            sessions.set(sessionID, session);
+            const started = now();
+            // A key pasted into the prompt is masked even when it is too short for a token shape.
+            const state = redactJevPrompt(promptText.split(key).join("[secret]"));
+            let outcome;
+            if (session.calls >= boundedInteger(env[`${jevFlag}_MAX_CALLS`], defaultMaxCalls, 0, Number.MAX_SAFE_INTEGER)) {
+                outcome = { failure: "call cap reached" };
+            }
+            else {
+                session.calls += 1;
+                try {
+                    outcome = await ask(state, key);
+                }
+                catch {
+                    outcome = { failure: "network" };
+                }
+            }
+            const latencyMs = now() - started;
+            await trace({
+                time: new Date(started).toISOString(),
+                promptSha256: createHash("sha256").update(state).digest("hex"),
+                choice: outcome.choice ?? null,
+                confidence: outcome.confidence ?? null,
+                latencyMs,
+                httpStatus: outcome.httpStatus ?? null,
+                fallback: outcome.failure ?? null
+            });
+            if (outcome.choice !== undefined) {
+                return { kind: "hint", text: jevSkillHintText(outcome.choice), skillId: outcome.choice, latencyMs };
+            }
+            if (outcome.failure === undefined || session.noted)
+                return undefined;
+            session.noted = true;
+            return { kind: "note", text: jevSkillHintUnavailableText(outcome.failure) };
+        }
+    };
+}

package/dist/knowledge.js

@@ -340,6 +340,9 @@ async function readRegularFileIfPresent(filePath, paths, options = {}) {
     try {
         await assertParentStable(parent, paths);
         const descriptorStat = await handle.stat();
+        if (descriptorStat.isFile() && descriptorStat.nlink === 0) {
+            throw new KnowledgeFileDisappearedError(`Knowledge file disappeared after descriptor open at ${filePath}.`);
+        }
         if (!descriptorStat.isFile() || !sameFileIdentity(fileIdentityOf(descriptorStat), fileIdentityOf(pathStat))) {
             throw new KnowledgeStoreError(`Unsafe knowledge file replacement at ${filePath}.`);
         }

package/dist/server.js

@@ -1,5 +1,6 @@
+import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { createChatMessageActivationHook, showActivationToast } from "./activation.js";
+import { createChatMessageActivationHook, showActivationToast, showJevSkillHintToast } from "./activation.js";
 import { registerLitOpenCodeAgents } from "./agents.js";
 import { createBoundedAuthorityEventHook } from "./bounded-authority-hooks.js";
 import { createCommandActivationHook } from "./commands.js";
@@ -7,6 +8,7 @@ import { loadConfig } from "./config.js";
 import { createDeliverableHedgeGuard } from "./deliverable-hedge-guard.js";
 import { createToolExecuteAfterHook, createToolExecuteBeforeHook } from "./hooks.js";
 import { createLogger } from "./logger.js";
+import { createJevSkillHint } from "./jev-skill-hint.js";
 import { createIgnitionState } from "./ignition.js";
 import { createSessionLookup } from "./session-lineage.js";
 import { applyCompactionRuleReset, applyStaticRuleInjection } from "./rules/hooks.js";
@@ -52,7 +54,13 @@ export function createLitOpenCodePlugin(autoUpdateRunner = runPluginAutoUpdate)
             ignitionState.activate(sessionID, skillId, !appendedLit);
         };
         const boundedAuthorityEvent = createBoundedAuthorityEventHook(root, input?.client, loaded.config.boundedAuthority);
-        const trustedCommandActivations = new WeakMap();
+        const skillHint = createJevSkillHint({
+            traceFile: path.join(loaded.paths.logsDir, "jev-skill-hint.jsonl"),
+            traceRoot: loaded.paths.projectRoot
+        });
+        // Keyed by session: the host resolves command parts into a new array before chat.message runs.
+        const pendingCommand = new Set();
+        const trustedCommandActivations = new Map();
         const commandActivation = createCommandActivationHook(root, {
             commandAliasRoot: defaultOpenCodeConfigRoot(),
             boundedAuthority: loaded.config.boundedAuthority,
@@ -66,6 +74,9 @@ export function createLitOpenCodePlugin(autoUpdateRunner = runPluginAutoUpdate)
             event: async (eventInput) => {
                 if (eventInput.event.type === "session.deleted") {
                     ignitionState.clear(eventInput.event.properties.info.id);
+                    skillHint.forget(eventInput.event.properties.info.id);
+                    pendingCommand.delete(eventInput.event.properties.info.id);
+                    trustedCommandActivations.delete(eventInput.event.properties.info.id);
                 }
                 await boundedAuthorityEvent(eventInput);
             },
@@ -78,20 +89,31 @@ export function createLitOpenCodePlugin(autoUpdateRunner = runPluginAutoUpdate)
                     ignitionState.resetDiscipline(sessionID);
                 },
                 onSkillActivation: recordSkillActivation,
-                trustedInjectedSkill: (sessionID, parts) => {
-                    const trusted = trustedCommandActivations.get(parts);
-                    trustedCommandActivations.delete(parts);
-                    return trusted?.sessionID === sessionID ? trusted.skillId : undefined;
+                isCommandTurn: (sessionID) => pendingCommand.delete(sessionID),
+                skillHint: async (sessionID, promptText) => {
+                    const hint = await skillHint.hintFor(sessionID, promptText);
+                    showJevSkillHintToast(input?.client, hint, skillHint.claimAwareness(sessionID, promptText));
+                    return hint;
+                },
+                trustedInjectedSkill: (sessionID) => {
+                    const skillId = trustedCommandActivations.get(sessionID);
+                    trustedCommandActivations.delete(sessionID);
+                    return skillId;
+                },
+                onTrustedSkillResume: (sessionID, skillId) => {
+                    ignitionState.activate(sessionID, skillId);
                 }
             }),
             "command.execute.before": async (commandInput, commandOutput) => {
+                pendingCommand.add(commandInput.sessionID);
                 const priorLength = commandOutput.parts.length;
                 await commandActivation(commandInput, commandOutput);
                 const activationPart = commandOutput.parts.slice(priorLength).reverse().find((part) => trustedCommandSkillId(part) !== undefined);
                 const skillId = trustedCommandSkillId(activationPart);
-                if (skillId !== undefined) {
-                    trustedCommandActivations.set(commandOutput.parts, { sessionID: commandInput.sessionID, skillId });
-                }
+                if (skillId === undefined)
+                    trustedCommandActivations.delete(commandInput.sessionID);
+                else
+                    trustedCommandActivations.set(commandInput.sessionID, skillId);
             },
             "experimental.text.complete": ignitionState.complete,
             "experimental.chat.system.transform": async (transformInput, transformOutput) => {

package/docs/assets/readme/badge-version.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.9"><title>release: 1.0.9</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.9</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.11"><title>release: 1.0.11</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.11</text></g></svg>

package/docs/privacy.md

@@ -14,6 +14,7 @@ providers, npm, and other tools have their own behavior and policies.
 | Project `.litopencode/litgoal/lit-loop/` | Goals, criteria, checkpoints, session identifiers, evidence references, a brief, ledger events, and bounded lifecycle state used to resume work. Evidence files can contain commands, output, or project material. |
 | Project `.litopencode/knowledge/` | Locally captured knowledge claims and review state. Legacy skill-learning files from earlier releases are left untouched and are no longer read. |
 | Project `.litopencode/logs/litopencode.log` | The logger's JSON-lines destination for timestamps, levels, and messages when explicitly enabled. The current server creates the logger with logging disabled by default. |
+| Project `.litopencode/logs/jev-skill-hint.jsonl` | Written only when `LITOPENCODE_JEV_TRACE=1`: one record per Jev skill hint request with time, prompt SHA-256, chosen skill id, confidence, latency, HTTP status and fallback reason. No prompt text, key or response body. |
 | OpenCode config root | Plugin registration, `litopencode.json` routes and choices, and installed command/skill files. The default is `~/.config/opencode`; `XDG_CONFIG_HOME` or a CLI `--root` changes the applicable root. |
 | Home `~/.litopencode/` | Update cache, locks, transaction journal and receipt, and retained recovery backups after an unsuccessful automatic update. Backups can contain OpenCode configuration and installed command/skill content. |
 
@@ -50,6 +51,17 @@ path and query string and normal network metadata. Never put secrets in a URL:
 redacting a returned result cannot retract a request already sent to its server.
 Retrieved text and source addresses can become part of tool output and host context.
 
+**Jev skill hint (off by default).** When `LITOPENCODE_JEV=1` and `TYPESAFE_API_KEY`
+are both set, the `chat.message` hook sends each eligible user prompt to TypeSafe at
+`api.typesafe.ai`, together with the LitOpenCode skill ids and summaries. The prompt is cut
+to 2,000 characters and home paths, e-mail addresses and token-shaped strings are replaced
+first. Anything in the prompt without a token shape is sent as written, for example hostnames,
+customer names, or a password that is not written as `password=...`. Files, tool output and
+earlier turns are not sent. Because `TYPESAFE_API_KEY` is exported in the shell that starts
+OpenCode, the agent's own tools can read it; use a key made only for this feature, with a low
+spending limit. TypeSafe's own retention and billing terms apply. Unset `LITOPENCODE_JEV` to
+stop these requests.
+
 **OpenCode and providers.** Agent prompts, user requests, selected files, and tool
 results are processed through the OpenCode host and configured provider. LitOpenCode
 does not establish their retention or training policy. Review the provider and