@sigrun/knowledge 0.0.0-stage → 0.1.1

package/dist/prompts.js

@@ -0,0 +1,16 @@
+/**
+ * The guidance bullets the curator's review prompt shows for the
+ * knowledge target (spec §6.3, plus the freshness ruling: fields that go
+ * out of date carry a horizon so staleness is visible).
+ */
+export function guidance() {
+    return [
+        "Record the inquiry and its why (the purpose, in the user's words where possible).",
+        "Find before creating: knowledge_find first, so entities de-duplicate across inquiries through identity keys.",
+        "Reuse or extend an existing type before defining a new one; type names are lowercase singular phrases.",
+        "When defining a type, give each field that goes out of date a horizonDays (prices ~30, opening hours ~180, addresses none).",
+        "Cite every field: each value carries its source recall handle and observed date.",
+        "Record the user's verdicts and outcomes, not your own guesses.",
+        "Capture nothing from transient errors or one-off chatter.",
+    ];
+}

package/dist/research.d.ts

@@ -0,0 +1,46 @@
+import type { ToolHookCall, ToolExecutionResult } from "@earendil-works/pi-durable";
+/**
+ * The per-conversation "researched since last review" flag, per user:
+ * `<user state>/research.json` maps conversationId (string key) to
+ * `{ lastResearchAt, requestedAt? }` (epoch ms).
+ */
+export interface ResearchFlags {
+    [conversationId: string]: {
+        lastResearchAt: number;
+        requestedAt?: number;
+    };
+}
+/** The window a queued review suppresses duplicate requests. */
+export declare const RESEARCH_WINDOW_MS: number;
+export declare function readResearchFlags(stateDir: string): ResearchFlags;
+export interface ResearchDeps {
+    /** Live conversation meta (internal flag + owner). */
+    conversationMeta(conversationId: number): Promise<{
+        owner?: string;
+        internal?: true;
+    }>;
+    /** The directory user's state dir (research.json lives there). */
+    userStateDir(user: string): string;
+    /** The extension's per-user settings (researchTools). */
+    userSettings(user: string): Promise<Record<string, unknown>>;
+    now(): number;
+}
+/**
+ * The afterTool hook: for a non-internal conversation with an owner and a
+ * tool name matching the owner's researchTools globs, stamp
+ * lastResearchAt. Never alters the result; errors are logged, never
+ * thrown (the hook must not break tool execution).
+ */
+export declare function createResearch(deps: ResearchDeps): (call: ToolHookCall, _result: ToolExecutionResult, api: {
+    conversationId: number;
+}, _context: unknown) => Promise<undefined>;
+/**
+ * Whether the target wants a review of this conversation (one per
+ * research burst): true when research happened and no request was made
+ * within the last RESEARCH_WINDOW_MS; stamps requestedAt so further
+ * settles while a review is queued don't enqueue a second one. A review
+ * that never completes is re-requested after the window.
+ */
+export declare function requestReview(stateDir: string, conversationId: number, now: number): boolean;
+/** The review consumed the flag: delete the entry. */
+export declare function clearReview(stateDir: string, conversationId: number): void;

package/dist/research.js

@@ -0,0 +1,81 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { matchesGlob, resolveUserSettings } from "./config.js";
+/** The window a queued review suppresses duplicate requests. */
+export const RESEARCH_WINDOW_MS = 15 * 60 * 1000;
+export function readResearchFlags(stateDir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(stateDir, "research.json"), "utf8"));
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            return {};
+        return raw;
+    }
+    catch {
+        return {};
+    }
+}
+function writeResearchFlags(stateDir, flags) {
+    mkdirSync(stateDir, { recursive: true });
+    writeFileSync(join(stateDir, "research.json"), JSON.stringify(flags, null, "\t") + "\n");
+}
+/**
+ * The afterTool hook: for a non-internal conversation with an owner and a
+ * tool name matching the owner's researchTools globs, stamp
+ * lastResearchAt. Never alters the result; errors are logged, never
+ * thrown (the hook must not break tool execution).
+ */
+export function createResearch(deps) {
+    return async function afterTool(call, _result, api, _context) {
+        try {
+            const meta = await deps.conversationMeta(api.conversationId);
+            if (meta.internal === true || meta.owner === undefined)
+                return undefined;
+            const settings = await resolveUserSettings({
+                get: () => deps.userSettings(meta.owner),
+            });
+            if (!settings.researchTools.some((glob) => matchesGlob(glob, call.name))) {
+                return undefined;
+            }
+            const stateDir = deps.userStateDir(meta.owner);
+            const flags = readResearchFlags(stateDir);
+            const key = String(api.conversationId);
+            const entry = flags[key] ?? { lastResearchAt: 0 };
+            flags[key] = { ...entry, lastResearchAt: deps.now() };
+            writeResearchFlags(stateDir, flags);
+        }
+        catch (error) {
+            console.error("knowledge: research flag failed", error);
+        }
+        return undefined;
+    };
+}
+/**
+ * Whether the target wants a review of this conversation (one per
+ * research burst): true when research happened and no request was made
+ * within the last RESEARCH_WINDOW_MS; stamps requestedAt so further
+ * settles while a review is queued don't enqueue a second one. A review
+ * that never completes is re-requested after the window.
+ */
+export function requestReview(stateDir, conversationId, now) {
+    const flags = readResearchFlags(stateDir);
+    const key = String(conversationId);
+    const entry = flags[key];
+    if (entry === undefined || entry.lastResearchAt === 0)
+        return false;
+    if (entry.requestedAt !== undefined &&
+        now - entry.requestedAt < RESEARCH_WINDOW_MS) {
+        return false;
+    }
+    flags[key] = { ...entry, requestedAt: now };
+    writeResearchFlags(stateDir, flags);
+    return true;
+}
+/** The review consumed the flag: delete the entry. */
+export function clearReview(stateDir, conversationId) {
+    const flags = readResearchFlags(stateDir);
+    const key = String(conversationId);
+    if (flags[key] === undefined)
+        return;
+    delete flags[key];
+    writeResearchFlags(stateDir, flags);
+}

package/dist/schema.d.ts

@@ -0,0 +1,44 @@
+import { type TSchema } from "@earendil-works/pi-ai";
+export type FieldType = "string" | "number" | "boolean" | "date" | "url" | "money" | "enum" | "list";
+export interface FieldDef {
+    name: string;
+    type: FieldType;
+    /** Allowed values when type is "enum". */
+    values?: string[];
+    /** Item type when type is "list". */
+    item?: Exclude<FieldType, "list">;
+    /** Identity fields participate in the entity's identity keys. */
+    identity?: boolean;
+    /** Freshness horizon in days, for fields that age. */
+    horizonDays?: number;
+    description?: string;
+}
+export interface TypeDef {
+    /** Lowercase singular phrase, e.g. "clinic" or "service visit". */
+    name: string;
+    description: string;
+    /** Parent type name (same hierarchy = one identity family). */
+    parent?: string;
+    fields: FieldDef[];
+}
+/** Type names are lowercase singular phrases. */
+export declare const TYPE_NAME_PATTERN: RegExp;
+export declare const TypeDefSchema: TSchema;
+/**
+ * Validate one field value against its definition. Returns undefined when
+ * the value is valid, otherwise a short human-readable error text.
+ */
+export declare function validateValue(def: FieldDef, value: unknown): string | undefined;
+/** Minimal type row shape the hierarchy helpers need. */
+export interface TypeHierarchyRow {
+    id: number;
+    parentId: number | null;
+    /** Field defs, parsed (FieldDef[]) or still the stored JSON string. */
+    fields: string | FieldDef[];
+}
+/**
+ * Effective (own + inherited) field defs for a type: walk the parent
+ * chain root-first; a child field with the same name shadows the
+ * ancestor's def.
+ */
+export declare function effectiveFields(typesById: Map<number, TypeHierarchyRow>, typeId: number): FieldDef[];

package/dist/schema.js

@@ -0,0 +1,145 @@
+import { Type } from "@earendil-works/pi-ai";
+const FIELD_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "date",
+    "url",
+    "money",
+    "enum",
+    "list",
+];
+const LIST_ITEM_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "date",
+    "url",
+    "money",
+    "enum",
+];
+/** Type names are lowercase singular phrases. */
+export const TYPE_NAME_PATTERN = /^[a-z][a-z0-9 -]{0,63}$/;
+const FieldDefSchema = Type.Object({
+    name: Type.String({ minLength: 1 }),
+    type: Type.Union(FIELD_TYPES.map((type) => Type.Literal(type))),
+    values: Type.Optional(Type.Array(Type.String())),
+    item: Type.Optional(Type.Union(LIST_ITEM_TYPES.map((type) => Type.Literal(type)))),
+    identity: Type.Optional(Type.Boolean()),
+    horizonDays: Type.Optional(Type.Number()),
+    description: Type.Optional(Type.String()),
+});
+export const TypeDefSchema = Type.Object({
+    name: Type.String({ pattern: TYPE_NAME_PATTERN.source }),
+    description: Type.String(),
+    parent: Type.Optional(Type.String({ pattern: TYPE_NAME_PATTERN.source })),
+    fields: Type.Array(FieldDefSchema),
+});
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+function checkScalar(type, value) {
+    switch (type) {
+        case "string":
+            return typeof value === "string" ? undefined : "expected a string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value)
+                ? undefined
+                : "expected a number";
+        case "boolean":
+            return typeof value === "boolean" ? undefined : "expected a boolean";
+        case "date": {
+            if (typeof value !== "string" || !ISO_DATE_PATTERN.test(value)) {
+                return "expected an ISO date (YYYY-MM-DD)";
+            }
+            const parsed = new Date(`${value}T00:00:00Z`);
+            if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== value) {
+                return "expected a valid calendar date";
+            }
+            return undefined;
+        }
+        case "url":
+            if (typeof value !== "string")
+                return "expected a url string";
+            try {
+                new URL(value);
+                return undefined;
+            }
+            catch {
+                return "expected a valid url";
+            }
+        case "money":
+            return checkMoney(value);
+    }
+}
+function checkMoney(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return "expected money { amount, currency }";
+    }
+    const raw = value;
+    if (typeof raw.amount !== "number" || !Number.isFinite(raw.amount)) {
+        return "money amount must be a number";
+    }
+    if (typeof raw.currency !== "string" ||
+        !/^[A-Za-z]{3}$/.test(raw.currency)) {
+        return "money currency must be a 3-letter code";
+    }
+    return undefined;
+}
+/**
+ * Validate one field value against its definition. Returns undefined when
+ * the value is valid, otherwise a short human-readable error text.
+ */
+export function validateValue(def, value) {
+    if (def.type === "enum") {
+        if (typeof value !== "string")
+            return "expected an enum string";
+        if (def.values === undefined || !def.values.includes(value)) {
+            return `expected one of: ${(def.values ?? []).join(", ")}`;
+        }
+        return undefined;
+    }
+    if (def.type === "list") {
+        if (!Array.isArray(value))
+            return "expected a list";
+        const itemType = def.item ?? "string";
+        for (const item of value) {
+            // List-of-enum: membership comes from the owning def's values
+            // (the item type carries no values of its own); permissive only
+            // when no values are declared.
+            if (itemType === "enum" && def.values !== undefined) {
+                if (typeof item !== "string" || !def.values.includes(item)) {
+                    return `list item: expected one of: ${def.values.join(", ")}`;
+                }
+                continue;
+            }
+            const error = checkScalar(itemType === "enum" ? "string" : itemType, item);
+            if (error !== undefined)
+                return `list item: ${error}`;
+        }
+        return undefined;
+    }
+    return checkScalar(def.type, value);
+}
+/**
+ * Effective (own + inherited) field defs for a type: walk the parent
+ * chain root-first; a child field with the same name shadows the
+ * ancestor's def.
+ */
+export function effectiveFields(typesById, typeId) {
+    const chain = [];
+    let current = typesById.get(typeId);
+    while (current !== undefined) {
+        chain.unshift(current);
+        current =
+            current.parentId === null ? undefined : typesById.get(current.parentId);
+    }
+    const byName = new Map();
+    for (const type of chain) {
+        const fields = typeof type.fields === "string"
+            ? JSON.parse(type.fields)
+            : type.fields;
+        for (const field of fields) {
+            byName.set(field.name, field);
+        }
+    }
+    return [...byName.values()];
+}

package/dist/target.d.ts

@@ -0,0 +1,23 @@
+import type { CurationTarget } from "@sigrun/sigrun/extension";
+import type { KnowledgeDb } from "./db.js";
+import { type MirrorHost } from "./mirror.js";
+export interface TargetDeps {
+    host: MirrorHost & {
+        stores: {
+            user(user: string): {
+                paths: {
+                    state: string;
+                };
+            };
+        };
+    };
+    dbForUser(user: string): KnowledgeDb;
+    now(): number;
+}
+/**
+ * The knowledge curation target (curator P7): knowledge_record is the
+ * wrapped write surface; knowledge_find is a read tool the review may
+ * call (never wrapped). undo reverts a change and re-mirrors every
+ * touched entity. wantsReview/reviewed drive the research flag.
+ */
+export declare function createTarget(deps: TargetDeps): CurationTarget;

package/dist/target.js

@@ -0,0 +1,29 @@
+import { undoChange } from "./undo.js";
+import { mirrorEntities } from "./mirror.js";
+import { maintain } from "./maintain.js";
+import { guidance } from "./prompts.js";
+import { requestReview, clearReview } from "./research.js";
+/**
+ * The knowledge curation target (curator P7): knowledge_record is the
+ * wrapped write surface; knowledge_find is a read tool the review may
+ * call (never wrapped). undo reverts a change and re-mirrors every
+ * touched entity. wantsReview/reviewed drive the research flag.
+ */
+export function createTarget(deps) {
+    return {
+        name: "knowledge",
+        tools: ["knowledge_record"],
+        readTools: ["knowledge_find"],
+        guidance: () => guidance(),
+        async undo(user, changeId, _ctx) {
+            const db = deps.dbForUser(user);
+            const result = undoChange(db, changeId, deps.now());
+            await mirrorEntities(deps.host, db, user, result.touched, deps.now());
+        },
+        wantsReview: (user, id) => requestReview(deps.host.stores.user(user).paths.state, id, deps.now()),
+        reviewed: (user, id) => {
+            clearReview(deps.host.stores.user(user).paths.state, id);
+        },
+        maintain: (user, ctx, budget) => maintain(user, ctx, budget, deps),
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,45 @@
+import { type ToolRegistration } from "@earendil-works/pi-durable";
+import type { KnowledgeDb } from "./db.js";
+type HookResult = {
+    status: "absent";
+} | {
+    status: "ok";
+    value?: unknown;
+} | {
+    status: "rejected" | "failed";
+    [key: string]: unknown;
+};
+export interface ToolsHost {
+    identity: {
+        actingUser(conversationId: number): Promise<string | undefined>;
+    };
+    conversations: {
+        meta(id: number): Promise<{
+            owner?: string;
+            internal?: true;
+            sharing?: import("@sigrun/shared/access").Sharing;
+        }>;
+        entries(id: number, query: {
+            order?: "ascending" | "descending";
+        }, limit: number, cursor?: unknown): Promise<{
+            items: readonly {
+                conversationId: number;
+            }[];
+            next?: unknown;
+        }>;
+    };
+    publishedHooks: {
+        call(name: string, payload: unknown, opts?: {
+            user?: string;
+            conversationId?: number;
+        }): Promise<HookResult>;
+    };
+}
+export interface ToolsDeps {
+    host: ToolsDepsHost;
+    dbForUser(user: string): KnowledgeDb;
+    now(): number;
+}
+export type ToolsDepsHost = ToolsHost;
+export declare function createTools(deps: ToolsDeps): readonly ToolRegistration[];
+export {};