@openagentsy/hooks 0.0.0-stage → 0.2.1

package/dist/eval/types.js

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+/**
+ * The eval artifacts: the executable proof that a lesson is real.
+ *
+ * An artifact is a list of scenarios. A baseline scenario says what the
+ * behaviour is today, and a candidate scenario says what it should be. The
+ * runner executes them and writes a result that holds the verdicts and never
+ * the output, so a result can be kept without keeping what the run printed.
+ */
+/** The longest a scenario may run, in milliseconds. */
+export const MAX_TIMEOUT_MS = 300_000;
+/** The timeout a scenario gets when it names none. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/** The most scenarios an artifact may hold. */
+export const MAX_SCENARIOS = 20;
+/**
+ * What a scenario asserts about the run.
+ *
+ * Every field is optional, and a field that is absent is not asserted: a
+ * scenario that only names an exit code does not care what was printed.
+ */
+export const EvalExpectation = z.object({
+    exit_code: z.number().int().optional(),
+    stdout_includes: z.array(z.string()).optional(),
+    stdout_excludes: z.array(z.string()).optional(),
+    stderr_includes: z.array(z.string()).optional(),
+    stderr_excludes: z.array(z.string()).optional(),
+});
+/**
+ * One scenario: a command, a place to run it, and what it must show.
+ *
+ * The command is an argv, never a shell string. The schema says so by
+ * holding an array, and the runner says it again before it spawns, because a
+ * shell string is the one shape that turns a proof into an injection.
+ */
+export const EvalScenario = z.object({
+    id: z.string().min(1),
+    phase: z.enum(['baseline', 'candidate']),
+    cwd: z.string().min(1),
+    command: z.array(z.string()).min(1),
+    timeout_ms: z.number().int().max(MAX_TIMEOUT_MS).default(DEFAULT_TIMEOUT_MS),
+    expect: EvalExpectation,
+});
+/**
+ * The artifact.
+ *
+ * It needs at least one candidate scenario, because an artifact that only
+ * shows the current behaviour proves nothing, and the scenario ids have to be
+ * unique, because a result names its scenarios by id.
+ */
+export const EvalArtifact = z.object({
+    schema_version: z.literal('1'),
+    lesson_id: z.string().min(1),
+    name: z.string().min(1),
+    scenarios: z
+        .array(EvalScenario)
+        .min(1)
+        .max(MAX_SCENARIOS)
+        .refine((scenarios) => scenarios.some((scenario) => scenario.phase === 'candidate'), {
+        message: 'needs a candidate scenario',
+    })
+        .refine((scenarios) => new Set(scenarios.map((scenario) => scenario.id)).size === scenarios.length, { message: 'scenario ids must be unique' }),
+});
+/**
+ * The shape of a result, for a result that came from somewhere else.
+ *
+ * The runner builds its own results, so the type is enough for it. A result
+ * that arrives from a person or from a file has to be checked, because a
+ * result that is not one is not a proof.
+ */
+export const EvalResultShape = z.object({
+    schema_version: z.literal('1'),
+    lesson_id: z.string().min(1),
+    artifact_sha256: z.string().min(1),
+    started_at: z.string().min(1),
+    finished_at: z.string().min(1),
+    passed: z.boolean(),
+    runs: z.number().int().min(1),
+    scenarios: z.array(z.object({
+        id: z.string().min(1),
+        phase: z.enum(['baseline', 'candidate']),
+        command_sha256: z.string().min(1),
+        exit_code: z.number().int().nullable(),
+        timed_out: z.boolean(),
+        duration_ms: z.number().int(),
+        assertions: z.record(z.string(), z.boolean()),
+        passed: z.boolean(),
+    })),
+});
+/**
+ * The error the proof raises.
+ *
+ * It carries a hint, like every other error in this repository: the message
+ * says what happened, the hint says what to do next.
+ */
+export class ProofError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = 'ProofError';
+        this.hint = hint;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/eval/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/eval/types.ts"],"names":[],"mappings":"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"}

package/dist/event.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The event a tool call arrives as.
+ *
+ * The host hands a tool call over in its own shape: the tool name, the
+ * arguments, and the files the call touches are somewhere in the arguments.
+ * The rules are written against this shape instead, so a rule reads the
+ * same field whichever host called.
+ */
+/** A file a call touches. */
+export interface FileRef {
+    /** The path the call writes to, when it names one. */
+    path?: string;
+    /** The path the call moves from, when it names one. */
+    fromPath?: string;
+}
+/** The event a tool call arrives as. */
+export interface PreToolCallEvent {
+    /** The base name of the tool: `write`, `bash`, `oa_task_list`. */
+    toolName: string;
+    /** The arguments the call was made with. */
+    args: Record<string, unknown>;
+    /** The files the call touches. */
+    files: FileRef[];
+    /** The command, for a shell call. */
+    command?: string;
+    /** The call id, for the approval gate. */
+    callID?: string;
+    /** The role the call is made for. */
+    role?: string;
+    /** The session the call is made in. */
+    sessionID?: string;
+}
+/**
+ * Whether a tool only reads.
+ *
+ * A reader names a file as well, and a read of a policy file has to stay
+ * possible, so the write rules are about the tools that are not readers.
+ */
+export declare function isReaderTool(toolName: string): boolean;
+/**
+ * Whether a tool writes a file.
+ *
+ * The name is read on its token boundaries, in either direction: the
+ * built-in names (write, edit, multi_edit, patch, apply_patch) and the
+ * names a host composes (write_file, create_file) are the same thing.
+ */
+export declare function isWritingTool(toolName: string): boolean;
+/**
+ * The event, when it is a tool call.
+ *
+ * The host hands the raw arguments over, and the rules read the normalised
+ * fields. So the normalisation happens here: a command that is named in the
+ * arguments is the command, and a file that is named in the arguments is
+ * the file the call touches. A host that already normalises (the adapter
+ * does) is not contradicted: the files it supplies are kept, and the
+ * arguments are the fallback.
+ */
+export declare function readPreToolCall(event: unknown): PreToolCallEvent | undefined;
+//# sourceMappingURL=event.d.ts.map

package/dist/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6BAA6B;AAC7B,MAAM,WAAW,OAAO;IACtB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,kCAAkC;IAClC,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA8DD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGtD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAYvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAmB5E"}

package/dist/event.js

@@ -0,0 +1,178 @@
+/**
+ * The event a tool call arrives as.
+ *
+ * The host hands a tool call over in its own shape: the tool name, the
+ * arguments, and the files the call touches are somewhere in the arguments.
+ * The rules are written against this shape instead, so a rule reads the
+ * same field whichever host called.
+ */
+/**
+ * The argument names a write tool names its file with.
+ *
+ * The names are the ones the host uses: `filePath` is OpenCode's, `path`
+ * and `file` are the ones other tools use.
+ */
+const PATH_ARGS = ['filePath', 'file_path', 'path', 'file'];
+/**
+ * The tools that write, by their exact name.
+ */
+const WRITING_TOOLS = ['write', 'edit', 'multi_edit', 'patch', 'apply_patch'];
+/**
+ * The verbs that say a tool writes, on their own.
+ */
+const WRITING_VERBS_ALWAYS = ['move', 'delete', 'rename'];
+/**
+ * The verbs that say a tool writes a file.
+ */
+const WRITING_VERBS = [
+    'write',
+    'edit',
+    'patch',
+    'create',
+    'update',
+    'remove',
+    'copy',
+    'upload',
+    'save',
+    'push',
+    'truncate',
+    'replace',
+];
+/**
+ * The nouns that say a tool touches a file.
+ */
+const FILE_NOUNS = ['file', 'files', 'directory', 'dir'];
+/**
+ * The tools that only read.
+ */
+const READER_TOOLS = [
+    'read',
+    'grep',
+    'glob',
+    'list',
+    'ls',
+    'search',
+    'find',
+    'cat',
+    'view',
+    'open',
+    'fetch',
+    'webfetch',
+    'websearch',
+];
+/**
+ * Whether a tool only reads.
+ *
+ * A reader names a file as well, and a read of a policy file has to stay
+ * possible, so the write rules are about the tools that are not readers.
+ */
+export function isReaderTool(toolName) {
+    const lower = toolName.toLowerCase();
+    return READER_TOOLS.some((tool) => lower === tool || lower.endsWith(`_${tool}`));
+}
+/**
+ * Whether a tool writes a file.
+ *
+ * The name is read on its token boundaries, in either direction: the
+ * built-in names (write, edit, multi_edit, patch, apply_patch) and the
+ * names a host composes (write_file, create_file) are the same thing.
+ */
+export function isWritingTool(toolName) {
+    const lower = toolName.toLowerCase();
+    if (WRITING_TOOLS.some((tool) => lower === tool || lower.endsWith(`_${tool}`)))
+        return true;
+    const tokens = toolName
+        .split(/[^A-Za-z0-9]+|(?=[a-z0-9][A-Z])/)
+        .filter((token) => token.length > 0)
+        .map((token) => token.toLowerCase());
+    if (WRITING_TOOLS.includes(tokens.join('_')))
+        return true;
+    if (tokens.some((token) => WRITING_VERBS_ALWAYS.includes(token)))
+        return true;
+    const verb = tokens.some((token) => WRITING_VERBS.includes(token));
+    const noun = tokens.some((token) => FILE_NOUNS.includes(token));
+    return verb && noun;
+}
+/**
+ * The event, when it is a tool call.
+ *
+ * The host hands the raw arguments over, and the rules read the normalised
+ * fields. So the normalisation happens here: a command that is named in the
+ * arguments is the command, and a file that is named in the arguments is
+ * the file the call touches. A host that already normalises (the adapter
+ * does) is not contradicted: the files it supplies are kept, and the
+ * arguments are the fallback.
+ */
+export function readPreToolCall(event) {
+    if (typeof event !== 'object' || event === null)
+        return undefined;
+    const candidate = event;
+    if (typeof candidate.toolName !== 'string')
+        return undefined;
+    const args = isArgs(candidate.args) ? candidate.args : {};
+    const files = fileRefs(candidate.files);
+    const command = readString(candidate.command) ?? readString(args['command']);
+    // The file is read out of the arguments for the tools that write. A
+    // read names a file as well, and that is not a write.
+    const inferred = isWritingTool(candidate.toolName) ? filesFromArgs(args) : [];
+    return {
+        toolName: candidate.toolName,
+        args,
+        files: files.length > 0 ? files : inferred,
+        ...(command !== undefined ? { command } : {}),
+        ...(typeof candidate.callID === 'string' ? { callID: candidate.callID } : {}),
+        ...(typeof candidate.role === 'string' ? { role: candidate.role } : {}),
+        ...(typeof candidate.sessionID === 'string' ? { sessionID: candidate.sessionID } : {}),
+    };
+}
+/**
+ * The arguments, when they are an object.
+ *
+ * The host hands unknown shapes over, and an array is not a set of named
+ * arguments, so an array is not one either.
+ */
+function isArgs(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * A string, when the field is one.
+ */
+function readString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * The files, when they are files.
+ *
+ * A path that is not a string is not a path, so it is dropped rather than
+ * carried into a rule that would compare it as one.
+ */
+function fileRefs(value) {
+    if (!Array.isArray(value))
+        return [];
+    const refs = [];
+    for (const entry of value) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = entry;
+        refs.push({
+            ...(typeof record.path === 'string' ? { path: record.path } : {}),
+            ...(typeof record.fromPath === 'string' ? { fromPath: record.fromPath } : {}),
+        });
+    }
+    return refs;
+}
+/**
+ * The file a call writes to, when the arguments name one.
+ *
+ * The arguments are the raw shape of the host, so this is where a path
+ * that was never normalised is found.
+ */
+function filesFromArgs(args) {
+    for (const key of PATH_ARGS) {
+        const path = readString(args[key]);
+        if (path !== undefined)
+            return [{ path }];
+    }
+    return [];
+}
+//# sourceMappingURL=event.js.map

package/dist/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"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"}

package/dist/event.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=event.test.d.ts.map

package/dist/event.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.test.d.ts","sourceRoot":"","sources":["../src/event.test.ts"],"names":[],"mappings":""}

package/dist/event.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { readPreToolCall } from './event.js';
+describe('readPreToolCall', () => {
+    it('keeps the files the host normalised', () => {
+        const event = readPreToolCall({
+            toolName: 'write',
+            args: { filePath: '/repo/src/a.ts' },
+            files: [{ path: '/repo/src/a.ts', fromPath: '/repo/src/b.ts' }],
+        });
+        expect(event?.files).toEqual([{ path: '/repo/src/a.ts', fromPath: '/repo/src/b.ts' }]);
+    });
+    it('reads the command out of the raw arguments', () => {
+        const event = readPreToolCall({ toolName: 'bash', args: { command: 'ls -la' }, files: [] });
+        expect(event?.command).toBe('ls -la');
+    });
+    it('reads the file out of the raw arguments', () => {
+        const event = readPreToolCall({
+            toolName: 'write',
+            args: { filePath: '/repo/src/a.ts' },
+            files: [],
+        });
+        expect(event?.files).toEqual([{ path: '/repo/src/a.ts' }]);
+    });
+    it('prefers the command the host normalised', () => {
+        const event = readPreToolCall({
+            toolName: 'bash',
+            command: 'ls',
+            args: { command: 'rm -rf /' },
+            files: [],
+        });
+        expect(event?.command).toBe('ls');
+    });
+    it('carries the call id and the role', () => {
+        const event = readPreToolCall({
+            toolName: 'bash',
+            args: {},
+            files: [],
+            callID: 'call-1',
+            role: 'builder',
+        });
+        expect(event?.callID).toBe('call-1');
+        expect(event?.role).toBe('builder');
+    });
+    it('says nothing about an event that is not a tool call', () => {
+        expect(readPreToolCall({})).toBeUndefined();
+        expect(readPreToolCall('not an event')).toBeUndefined();
+    });
+});
+//# sourceMappingURL=event.test.js.map

package/dist/event.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.test.js","sourceRoot":"","sources":["../src/event.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,KAAK,GAAG,eAAe,CAAC;YAC5B,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE;YACpC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;SAChE,CAAC,CAAC;QACH,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,KAAK,GAAG,eAAe,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QAC5F,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,KAAK,GAAG,eAAe,CAAC;YAC5B,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE;YACpC,KAAK,EAAE,EAAE;SACV,CAAC,CAAC;QACH,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,KAAK,GAAG,eAAe,CAAC;YAC5B,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE;YAC7B,KAAK,EAAE,EAAE;SACV,CAAC,CAAC;QACH,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,KAAK,GAAG,eAAe,CAAC;YAC5B,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,EAAE;YACR,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,QAAQ;YAChB,IAAI,EAAE,SAAS;SAChB,CAAC,CAAC;QACH,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;QAC5C,MAAM,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @openagentsy/hooks
+ *
+ * The deterministic guardrails: the rule registry, the default rules, the
+ * output checks, the shell environment policy, the redaction wrapper and
+ * the approval gate.
+ *
+ * It is a library. The adapter (the OpenCode plugin) calls it; OpenCode
+ * never loads it, and nothing here decides on its own what a person
+ * decided.
+ */
+export * from './accountability.js';
+export * from './approvals.js';
+export * from './base-tool.js';
+export * from './eval/index.js';
+export * from './event.js';
+export * from './lessons/index.js';
+export * from './output-checks.js';
+export * from './paths.js';
+export { discoverPolicyModules, FIRST_PARTY_POLICY_IDS, firstPartyPolicyModules, type PolicyCatalogueOptions, } from './policies/index.js';
+export type { FileChange, PolicyContext, PolicyFinding, PolicyLayer, PolicyModule, PolicyMoment, PolicyOutcome, PolicyResult, } from './policy.js';
+export * from './policy-engine.js';
+export * from './policy-registry.js';
+export * from './policy-release.js';
+export * from './quality/index.js';
+export * from './registry.js';
+export * from './rules.js';
+export * from './secrets.js';
+export * from './shell-env.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,UAAU,EACV,aAAa,EACb,aAAa,EACb,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * @openagentsy/hooks
+ *
+ * The deterministic guardrails: the rule registry, the default rules, the
+ * output checks, the shell environment policy, the redaction wrapper and
+ * the approval gate.
+ *
+ * It is a library. The adapter (the OpenCode plugin) calls it; OpenCode
+ * never loads it, and nothing here decides on its own what a person
+ * decided.
+ */
+export * from './accountability.js';
+export * from './approvals.js';
+export * from './base-tool.js';
+export * from './eval/index.js';
+export * from './event.js';
+export * from './lessons/index.js';
+export * from './output-checks.js';
+export * from './paths.js';
+export { discoverPolicyModules, FIRST_PARTY_POLICY_IDS, firstPartyPolicyModules, } from './policies/index.js';
+export * from './policy-engine.js';
+export * from './policy-registry.js';
+export * from './policy-release.js';
+export * from './quality/index.js';
+export * from './registry.js';
+export * from './rules.js';
+export * from './secrets.js';
+export * from './shell-env.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,GAExB,MAAM,qBAAqB,CAAC;AAW7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC"}

package/dist/lessons/capture.d.ts

@@ -0,0 +1,66 @@
+import { type Lesson, type StartPacket } from './model.js';
+/**
+ * The capture.
+ *
+ * The archivist watches for the same kind of waste again and again, and it
+ * turns that into a candidate. It does so in two cases only:
+ *
+ * - the same waste kind with a similar detail shows up in three or more
+ *   sessions, which is a pattern rather than an accident;
+ * - a person corrects the agent outright, which is a lesson whatever the
+ *   count is.
+ *
+ * The observations are kept before there is a candidate, because the rule is
+ * about sessions: the third session is only a pattern if the first two are
+ * remembered. A candidate is deduplicated by its normalised summary, and
+ * every sighting of the same summary raises the count. The count is a
+ * priority, not evidence: a lesson that happened often is still only a claim
+ * until a person has decided it.
+ */
+/** How many sessions make a pattern. */
+export declare const SESSION_THRESHOLD = 3;
+/** One waste, as the archivist saw it. */
+export type WasteObservation = {
+    /** The waste kind. */
+    kind: string;
+    /** The detail the waste carried. */
+    detail: string;
+    /** The session it was seen in. */
+    session: string;
+};
+/** What the archivist saw. */
+export type CaptureInput = {
+    /** What happened, in one sentence. */
+    summary: string;
+    /** The waste, once per sighting. */
+    observations: WasteObservation[];
+    /** Whether a person corrected the agent outright. */
+    explicitCorrection?: boolean;
+    /** The evidence the lesson rests on. */
+    evidence?: string[];
+    /** The start packet, as far as the archivist can fill it. */
+    packet?: Partial<StartPacket>;
+};
+/** What the capture did. */
+export type CaptureOutcome = {
+    ok: true;
+    lesson: Lesson;
+    created: boolean;
+    redactions: number;
+} | {
+    ok: false;
+    reason: 'not_enough_sessions';
+    redactions: number;
+    sessions: number;
+};
+/**
+ * Capture a lesson.
+ *
+ * Nothing is written to the lesson store until there is something to write:
+ * a waste that has been seen once is not a pattern, and the archivist says
+ * so instead of filling the store with candidates nobody will read. The
+ * observations are kept either way, because the third session is only a
+ * pattern if the first two are remembered.
+ */
+export declare function captureCandidate(root: string, input: CaptureInput, now?: () => Date): Promise<CaptureOutcome>;
+//# sourceMappingURL=capture.d.ts.map

package/dist/lessons/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/lessons/capture.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAA6B,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAUtF;;;;;;;;;;;;;;;;;GAiBG;AAEH,wCAAwC;AACxC,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,0CAA0C;AAC1C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,8BAA8B;AAC9B,MAAM,MAAM,YAAY,GAAG;IACzB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,qDAAqD;IACrD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CAC/B,CAAC;AAEF,4BAA4B;AAC5B,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAiFvF;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,YAAY,EACnB,GAAG,GAAE,MAAM,IAAuB,GACjC,OAAO,CAAC,cAAc,CAAC,CAyEzB"}