@openagentsy/hooks 0.0.0-stage → 0.2.1

package/dist/policy-engine.js

@@ -0,0 +1,145 @@
+/**
+ * The policy engine (§21.3).
+ *
+ * The engine asks the stack for a decision and records what it decided. The
+ * record carries the id of the policy, the version it had at that moment,
+ * the session and the outcome, so a regression is attributed to the version
+ * that caused it.
+ *
+ * The engine writes through a sink and knows nothing of any store, so the
+ * log is the caller's choice: the ledger is the one the plan names, and the
+ * rows survive a restart because they are rows in a database and not words
+ * in a process.
+ */
+/** The id of the row that records the assembled stack. */
+export const STACK_POLICY_ID = 'oa.policy.stack';
+/** The version of the stack row. */
+export const STACK_POLICY_VERSION = '1.0.0';
+/**
+ * The moment a context is about.
+ *
+ * A context with a tool call is about the call, one with a response is
+ * about the reply, and one with a request is about the request. A context
+ * with none of them is about nothing, and no policy runs.
+ */
+export function momentOf(ctx) {
+    if (ctx.toolCall !== undefined)
+        return 'PreToolCall';
+    if (ctx.response !== undefined)
+        return 'PreResponse';
+    if (ctx.request !== undefined)
+        return 'UserPromptSubmit';
+    return undefined;
+}
+/**
+ * A decision, as the engine reports it.
+ *
+ * A decision that allowed the thing through carries no findings, and a
+ * decision that flagged carries the severity of the flag.
+ */
+export function outcomeOf(module, result) {
+    const base = { policyId: module.id, version: module.version, layer: module.layer };
+    switch (result.action) {
+        case 'allow':
+            return { ...base, action: 'allow', findings: [] };
+        case 'flag':
+            return { ...base, action: 'flag', severity: result.severity, findings: result.findings };
+        case 'block':
+            return {
+                ...base,
+                action: 'block',
+                reason: result.reason,
+                findings: result.finding === undefined ? [] : [result.finding],
+            };
+        case 'transform':
+            return { ...base, action: 'transform', findings: [] };
+    }
+}
+/** The engine of a registry. */
+export class PolicyEngine {
+    /** The registry the stack comes from. */
+    registry;
+    /** Where the firings go. */
+    sink;
+    /** The sessions whose stack was already recorded. */
+    assembled = new Set();
+    /**
+     * An engine of a registry.
+     *
+     * The engine holds no state beyond the sessions whose stack it recorded,
+     * so it may be built once for a session and used for every call in it.
+     */
+    constructor(registry, options = {}) {
+        this.registry = registry;
+        this.sink = options.sink;
+    }
+    /**
+     * Ask the stack, and record what it decided.
+     *
+     * The stack is recorded once per session: the first row of the session
+     * carries the whole stack, so a reader can see what the session was
+     * guarded by without reading every row.
+     */
+    evaluate(ctx) {
+        const classification = ctx.request?.classification ?? {};
+        const selection = this.registry.explain(classification);
+        this.recordStack(ctx, selection);
+        const moment = momentOf(ctx);
+        if (moment === undefined)
+            return [];
+        const outcomes = [];
+        for (const module of selection.modules) {
+            if (!module.appliesTo.includes(moment))
+                continue;
+            const result = module.evaluate(ctx);
+            const outcome = outcomeOf(module, result);
+            outcomes.push(outcome);
+            this.record(ctx, module, outcome);
+        }
+        return outcomes;
+    }
+    /** The row that records the stack of a session. */
+    recordStack(ctx, selection) {
+        if (this.sink === undefined)
+            return;
+        if (this.assembled.has(ctx.session.id))
+            return;
+        this.assembled.add(ctx.session.id);
+        const stack = selection.modules.map((module) => ({
+            id: module.id,
+            version: module.version,
+        }));
+        this.sink.record({
+            sessionId: ctx.session.id,
+            policyId: STACK_POLICY_ID,
+            policyVersion: STACK_POLICY_VERSION,
+            layer: 2,
+            action: 'allow',
+            reason: 'stack-assembled',
+            classification: ctx.highRiskDomain ?? ctx.request?.classification?.highRiskDomain,
+            detail: JSON.stringify(stack),
+            origin: 'first-party',
+        });
+    }
+    /** The row that records one decision. */
+    record(ctx, module, outcome) {
+        if (this.sink === undefined)
+            return;
+        const firing = {
+            sessionId: ctx.session.id,
+            policyId: outcome.policyId,
+            policyVersion: outcome.version,
+            layer: outcome.layer,
+            action: outcome.action,
+            severity: outcome.severity,
+            reason: outcome.reason,
+            classification: ctx.highRiskDomain ?? ctx.request?.classification?.highRiskDomain,
+            origin: module.origin,
+        };
+        if (outcome.findings.length > 0) {
+            firing.detail = JSON.stringify(outcome.findings);
+        }
+        this.sink.record(firing);
+    }
+}
+//# sourceMappingURL=policy-engine.js.map

package/dist/policy-engine.js.map

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

package/dist/policy-registry.d.ts

@@ -0,0 +1,62 @@
+import type { RequestClassification } from '@openagentsy/core';
+import type { PolicyLayer, PolicyModule } from './policy.js';
+/**
+ * The policy registry (§21.4).
+ *
+ * The registry holds the modules and assembles the stack from a
+ * classification. The assembly is explainable: `explain` says which modules
+ * were selected and why each of them is in the stack, so a reader can tell
+ * a guardrail that is always on from one the classifier brought in.
+ */
+/** Why a module is in the stack. */
+export interface PolicySelectionReason {
+    /** The stable id of the module. */
+    policyId: string;
+    /** The version it carried. */
+    version: string;
+    /** The layer it acts at. */
+    layer: PolicyLayer;
+    /** Why it was selected. */
+    reason: string;
+}
+/** The stack, and why it is what it is. */
+export interface PolicySelection {
+    /** The modules that were selected. */
+    modules: PolicyModule[];
+    /** The reason of each of them, in the order they were selected. */
+    reasons: PolicySelectionReason[];
+}
+/** The registry of a set of modules. */
+export declare class PolicyRegistry {
+    /** The modules, by id. */
+    private readonly byId;
+    /**
+     * A registry of a set of modules.
+     *
+     * Two modules with the same id are one module: the first one wins, and a
+     * plugin that claims the id of a first-party policy does not replace it.
+     */
+    constructor(modules: readonly PolicyModule[]);
+    /** Every module of the registry. */
+    list(): PolicyModule[];
+    /**
+     * A registry of the first-party policies and the ones a plugin brought.
+     *
+     * The candidates are the modules a host loaded, and the ones that are
+     * policies are marked external: a module that came from a plugin is the
+     * plugin's, and it does not count towards the first-party release
+     * criteria.
+     */
+    static withPlugins(firstParty: readonly PolicyModule[], candidates: readonly unknown[]): PolicyRegistry;
+    /** The stack for a classification. */
+    select(classification: RequestClassification): PolicyModule[];
+    /**
+     * The stack for a classification, and why each module is in it.
+     *
+     * The explanation is the reason the stack is what it is, so it is built
+     * once and read twice: the modules come out of it and the reasons come
+     * with them.
+     */
+    explain(classification: RequestClassification): PolicySelection;
+}
+//# sourceMappingURL=policy-registry.d.ts.map

package/dist/policy-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-registry.d.ts","sourceRoot":"","sources":["../src/policy-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG/D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D;;;;;;;GAOG;AAEH,oCAAoC;AACpC,MAAM,WAAW,qBAAqB;IACpC,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,KAAK,EAAE,WAAW,CAAC;IACnB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,mEAAmE;IACnE,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAED,wCAAwC;AACxC,qBAAa,cAAc;IACzB,0BAA0B;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IAEjD;;;;;OAKG;gBACS,OAAO,EAAE,SAAS,YAAY,EAAE;IAQ5C,oCAAoC;IACpC,IAAI,IAAI,YAAY,EAAE;IAItB;;;;;;;OAOG;IACH,MAAM,CAAC,WAAW,CAChB,UAAU,EAAE,SAAS,YAAY,EAAE,EACnC,UAAU,EAAE,SAAS,OAAO,EAAE,GAC7B,cAAc;IAIjB,sCAAsC;IACtC,MAAM,CAAC,cAAc,EAAE,qBAAqB,GAAG,YAAY,EAAE;IAI7D;;;;;;OAMG;IACH,OAAO,CAAC,cAAc,EAAE,qBAAqB,GAAG,eAAe;CAehE"}

package/dist/policy-registry.js

@@ -0,0 +1,63 @@
+import { discoverPolicyModules } from './policies/discovery.js';
+import { selectPolicies } from './policies/selection.js';
+/** The registry of a set of modules. */
+export class PolicyRegistry {
+    /** The modules, by id. */
+    byId;
+    /**
+     * A registry of a set of modules.
+     *
+     * Two modules with the same id are one module: the first one wins, and a
+     * plugin that claims the id of a first-party policy does not replace it.
+     */
+    constructor(modules) {
+        this.byId = new Map();
+        for (const module of modules) {
+            if (this.byId.has(module.id))
+                continue;
+            this.byId.set(module.id, module);
+        }
+    }
+    /** Every module of the registry. */
+    list() {
+        return [...this.byId.values()];
+    }
+    /**
+     * A registry of the first-party policies and the ones a plugin brought.
+     *
+     * The candidates are the modules a host loaded, and the ones that are
+     * policies are marked external: a module that came from a plugin is the
+     * plugin's, and it does not count towards the first-party release
+     * criteria.
+     */
+    static withPlugins(firstParty, candidates) {
+        return new PolicyRegistry([...firstParty, ...discoverPolicyModules(candidates)]);
+    }
+    /** The stack for a classification. */
+    select(classification) {
+        return this.explain(classification).modules;
+    }
+    /**
+     * The stack for a classification, and why each module is in it.
+     *
+     * The explanation is the reason the stack is what it is, so it is built
+     * once and read twice: the modules come out of it and the reasons come
+     * with them.
+     */
+    explain(classification) {
+        const selected = selectPolicies(this.list(), classification);
+        const modules = [];
+        const reasons = [];
+        for (const entry of selected) {
+            modules.push(entry.module);
+            reasons.push({
+                policyId: entry.module.id,
+                version: entry.module.version,
+                layer: entry.module.layer,
+                reason: entry.reason,
+            });
+        }
+        return { modules, reasons };
+    }
+}
+//# sourceMappingURL=policy-registry.js.map

package/dist/policy-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-registry.js","sourceRoot":"","sources":["../src/policy-registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAgCzD,wCAAwC;AACxC,MAAM,OAAO,cAAc;IACzB,0BAA0B;IACT,IAAI,CAA4B;IAEjD;;;;;OAKG;IACH,YAAY,OAAgC;QAC1C,IAAI,CAAC,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBAAE,SAAS;YACvC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,oCAAoC;IACpC,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,WAAW,CAChB,UAAmC,EACnC,UAA8B;QAE9B,OAAO,IAAI,cAAc,CAAC,CAAC,GAAG,UAAU,EAAE,GAAG,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACnF,CAAC;IAED,sCAAsC;IACtC,MAAM,CAAC,cAAqC;QAC1C,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC;IAC9C,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,cAAqC;QAC3C,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,cAAc,CAAC,CAAC;QAC7D,MAAM,OAAO,GAAmB,EAAE,CAAC;QACnC,MAAM,OAAO,GAA4B,EAAE,CAAC;QAC5C,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC;gBACX,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE;gBACzB,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO;gBAC7B,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK;gBACzB,MAAM,EAAE,KAAK,CAAC,MAAM;aACrB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC9B,CAAC;CACF"}

package/dist/policy-registry.test.d.ts

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

package/dist/policy-registry.test.d.ts.map

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

package/dist/policy-registry.test.js

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { FIRST_PARTY_POLICY_IDS, firstPartyPolicyModules } from './policies/index.js';
+import { PolicyRegistry } from './policy-registry.js';
+/**
+ * The selection of the policy stack (§21.4).
+ *
+ * The registry assembles the stack from the classification, and the
+ * assembly is explainable: every module says why it is in the stack.
+ */
+/** The catalogue of the first-party policies. */
+function registry() {
+    return new PolicyRegistry(firstPartyPolicyModules({ workspace: '/tmp/openagentsy-registry-test' }));
+}
+describe('the policy registry', () => {
+    it('gives every session the baseline stack and the always-on guardrails', () => {
+        const selected = registry().select({});
+        const ids = selected.map((module) => module.id);
+        expect(ids).toContain('oa.truthfulness-uncertainty');
+        expect(ids).toContain('oa.anti-sycophancy');
+        expect(ids).toContain('oa.no-skip-git-hooks');
+        expect(ids).not.toContain('oa.high-risk.medical');
+    });
+    it('adds the high-risk module of the domain the classification named', () => {
+        const selected = registry().select({ highRiskDomain: 'medical', confidence: 0.9 });
+        const ids = selected.map((module) => module.id);
+        expect(ids).toContain('oa.high-risk.medical');
+        expect(ids).not.toContain('oa.high-risk.legal');
+    });
+    it('says why each module was selected', () => {
+        const selection = registry().explain({ highRiskDomain: 'legal' });
+        const reason = (id) => selection.reasons.find((entry) => entry.policyId === id)?.reason;
+        expect(reason('oa.no-skip-git-hooks')).toBe('the guardrail applies to every tool call');
+        expect(reason('oa.anti-sycophancy')).toBe('every session gets this policy');
+        expect(reason('oa.high-risk.legal')).toBe('the classification named the legal domain');
+        expect(reason('oa.high-risk.medical')).toBeUndefined();
+    });
+    it('carries the version of every module it selected', () => {
+        const selection = registry().explain({});
+        for (const entry of selection.reasons) {
+            expect(entry.version).toMatch(/^\d+\.\d+\.\d+$/);
+        }
+    });
+    it('runs a module a plugin brought, and marks it external', () => {
+        const candidate = {
+            id: 'acme.no-warnings',
+            version: '0.1.0',
+            layer: 4,
+            description: 'A module a downstream project brought.',
+            appliesTo: ['PreResponse'],
+            evaluate: () => ({ action: 'allow' }),
+        };
+        const registry = PolicyRegistry.withPlugins(firstPartyPolicyModules({ workspace: '/tmp/ws' }), [
+            candidate,
+        ]);
+        const selected = registry.select({});
+        const module = selected.find((entry) => entry.id === 'acme.no-warnings');
+        expect(module?.origin).toBe('external');
+    });
+    it('drops a candidate that is not a policy', () => {
+        const registry = PolicyRegistry.withPlugins(firstPartyPolicyModules({ workspace: '/tmp/ws' }), [
+            { id: 'acme.broken', version: 'not-a-version' },
+            'nonsense',
+        ]);
+        expect(registry.select({}).map((module) => module.id)).not.toContain('acme.broken');
+    });
+    it('holds every first-party policy of §21.2 with an id and a version', () => {
+        const modules = firstPartyPolicyModules({ workspace: '/tmp/ws' });
+        const ids = modules.map((module) => module.id);
+        for (const id of FIRST_PARTY_POLICY_IDS) {
+            expect(ids).toContain(id);
+        }
+        expect(new Set(ids).size).toBe(ids.length);
+        for (const module of modules) {
+            expect(module.version).toMatch(/^\d+\.\d+\.\d+$/);
+            expect(module.origin).toBe('first-party');
+        }
+    });
+});
+//# sourceMappingURL=policy-registry.test.js.map

package/dist/policy-registry.test.js.map

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

package/dist/policy-release.d.ts

@@ -0,0 +1,44 @@
+import type { PolicyModule } from './policy.js';
+/**
+ * The release criteria of the policy library (§18.3).
+ *
+ * `oa release-check` is a later bean; what it needs from here is the list
+ * of criteria the policy library answers, the severity of each of them and
+ * whether it is met. The severity follows the decision the human made: a
+ * first-party template and a first-party role are held to the criteria
+ * hard, and a library is held to them softly.
+ */
+/** What is being released. */
+export type ReleaseScope = 'template' | 'role' | 'library';
+/** How hard a criterion is held. */
+export type ReleaseSeverity = 'hard' | 'soft';
+/** One criterion, and whether it is met. */
+export interface ReleaseCriterion {
+    /** The stable id of the criterion. */
+    id: string;
+    /** What the criterion asks for, in a line. */
+    description: string;
+    /** How hard the criterion is held. */
+    severity: ReleaseSeverity;
+    /** Whether the modules meet it. */
+    met: boolean;
+    /** What the answer was, in a line. */
+    detail: string;
+}
+/**
+ * The severity a scope holds a criterion to.
+ *
+ * A template and a role are what a person installs and trusts, so a
+ * criterion is hard there. A library is a building block, and a soft
+ * criterion is what a soft failure looks like.
+ */
+export declare function severityFor(scope: ReleaseScope): ReleaseSeverity;
+/**
+ * The criteria the policy library answers, and their answers.
+ *
+ * Only the first-party modules are counted: a module a plugin brought is
+ * marked external and does not count towards the criteria of a first-party
+ * release.
+ */
+export declare function policyReleaseCriteria(modules: readonly PolicyModule[], scope: ReleaseScope): ReleaseCriterion[];
+//# sourceMappingURL=policy-release.d.ts.map

package/dist/policy-release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-release.d.ts","sourceRoot":"","sources":["../src/policy-release.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;GAQG;AAEH,8BAA8B;AAC9B,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,oCAAoC;AACpC,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,QAAQ,EAAE,eAAe,CAAC;IAC1B,mCAAmC;IACnC,GAAG,EAAE,OAAO,CAAC;IACb,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,KAAK,EAAE,YAAY,GAClB,gBAAgB,EAAE,CAoDpB"}

package/dist/policy-release.js

@@ -0,0 +1,65 @@
+import { isSemver } from './policies/discovery.js';
+/**
+ * The severity a scope holds a criterion to.
+ *
+ * A template and a role are what a person installs and trusts, so a
+ * criterion is hard there. A library is a building block, and a soft
+ * criterion is what a soft failure looks like.
+ */
+export function severityFor(scope) {
+    return scope === 'library' ? 'soft' : 'hard';
+}
+/**
+ * The criteria the policy library answers, and their answers.
+ *
+ * Only the first-party modules are counted: a module a plugin brought is
+ * marked external and does not count towards the criteria of a first-party
+ * release.
+ */
+export function policyReleaseCriteria(modules, scope) {
+    const severity = severityFor(scope);
+    const firstParty = modules.filter((module) => module.origin === 'first-party');
+    const external = modules.filter((module) => module.origin === 'external');
+    const withoutId = firstParty.filter((module) => module.id.trim().length === 0);
+    const withoutVersion = firstParty.filter((module) => !isSemver(module.version));
+    const withoutLayer = firstParty.filter((module) => !Number.isInteger(module.layer));
+    return [
+        {
+            id: 'policy-ids',
+            description: 'Every first-party policy module carries a stable id.',
+            severity,
+            met: withoutId.length === 0,
+            detail: withoutId.length === 0
+                ? `${firstParty.length} first-party modules carry an id`
+                : `${withoutId.length} modules carry no id`,
+        },
+        {
+            id: 'policy-versions',
+            description: 'Every first-party policy module carries a version.',
+            severity,
+            met: withoutVersion.length === 0,
+            detail: withoutVersion.length === 0
+                ? `${firstParty.length} first-party modules carry a version`
+                : `${withoutVersion.length} modules carry no version`,
+        },
+        {
+            id: 'policy-layers',
+            description: 'Every first-party policy module maps to a layer of the guardrail stack.',
+            severity,
+            met: withoutLayer.length === 0,
+            detail: withoutLayer.length === 0
+                ? `${firstParty.length} first-party modules map to a layer`
+                : `${withoutLayer.length} modules map to no layer`,
+        },
+        {
+            id: 'policy-origin',
+            description: 'The modules a plugin brought are marked external and do not count towards the criteria.',
+            severity,
+            met: external.every((module) => module.origin === 'external'),
+            detail: external.length === 0
+                ? 'no plugin module is in the release'
+                : `${external.length} plugin modules are marked external and are not counted`,
+        },
+    ];
+}
+//# sourceMappingURL=policy-release.js.map

package/dist/policy-release.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-release.js","sourceRoot":"","sources":["../src/policy-release.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAiCnD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAmB;IAC7C,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAgC,EAChC,KAAmB;IAEnB,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,aAAa,CAAC,CAAC;IAC/E,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;IAE1E,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;IAC/E,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAChF,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAEpF,OAAO;QACL;YACE,EAAE,EAAE,YAAY;YAChB,WAAW,EAAE,sDAAsD;YACnE,QAAQ;YACR,GAAG,EAAE,SAAS,CAAC,MAAM,KAAK,CAAC;YAC3B,MAAM,EACJ,SAAS,CAAC,MAAM,KAAK,CAAC;gBACpB,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,kCAAkC;gBACxD,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM,sBAAsB;SAChD;QACD;YACE,EAAE,EAAE,iBAAiB;YACrB,WAAW,EAAE,oDAAoD;YACjE,QAAQ;YACR,GAAG,EAAE,cAAc,CAAC,MAAM,KAAK,CAAC;YAChC,MAAM,EACJ,cAAc,CAAC,MAAM,KAAK,CAAC;gBACzB,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,sCAAsC;gBAC5D,CAAC,CAAC,GAAG,cAAc,CAAC,MAAM,2BAA2B;SAC1D;QACD;YACE,EAAE,EAAE,eAAe;YACnB,WAAW,EAAE,yEAAyE;YACtF,QAAQ;YACR,GAAG,EAAE,YAAY,CAAC,MAAM,KAAK,CAAC;YAC9B,MAAM,EACJ,YAAY,CAAC,MAAM,KAAK,CAAC;gBACvB,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,qCAAqC;gBAC3D,CAAC,CAAC,GAAG,YAAY,CAAC,MAAM,0BAA0B;SACvD;QACD;YACE,EAAE,EAAE,eAAe;YACnB,WAAW,EACT,yFAAyF;YAC3F,QAAQ;YACR,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC;YAC7D,MAAM,EACJ,QAAQ,CAAC,MAAM,KAAK,CAAC;gBACnB,CAAC,CAAC,oCAAoC;gBACtC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,yDAAyD;SAClF;KACF,CAAC;AACJ,CAAC"}

package/dist/policy.d.ts

@@ -0,0 +1,141 @@
+import type { PolicyAction, PolicyOrigin, PolicySeverity, RequestClassification } from '@openagentsy/core';
+/**
+ * The policy module interface (§21.1).
+ *
+ * A policy is a module with a stable id, a version and a decision. The id
+ * is what a firing is attributed to and what a project enables or disables,
+ * so it does not change when the behaviour does — the version changes then,
+ * and the firing log records the version that was in force when the policy
+ * fired.
+ */
+/** The layers of the guardrail stack (§17.4). */
+export type PolicyLayer = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+/** The moments a policy is checked at (§21.1). */
+export type PolicyMoment = 'UserPromptSubmit' | 'PreToolCall' | 'PostToolCall' | 'PreResponse' | 'PostResponse' | 'PreCompact' | 'SubagentStop';
+/** A file a call touches. */
+export interface FileChange {
+    /** The path the change writes to, when it names one. */
+    path?: string;
+    /** The path the change moves from, when it names one. */
+    fromPath?: string;
+}
+/** What a policy found. */
+export interface PolicyFinding {
+    /** The policy that found it. */
+    policyId: string;
+    /** What kind of thing it is. */
+    type: string;
+    /** The text that matched. */
+    match: string;
+}
+/**
+ * What a policy is asked.
+ *
+ * The context carries what the policy needs and nothing else: the request
+ * and its classification, the tool call and its result, the response, the
+ * session the work happens in, the files it touches and the high-risk domain
+ * the classifier fired on (§20.3).
+ */
+export interface PolicyContext {
+    /** The request, and the classification of it. */
+    request?: {
+        text: string;
+        classification?: RequestClassification;
+    };
+    /** The tool call, when the policy is asked about one. */
+    toolCall?: {
+        name: string;
+        args: unknown;
+    };
+    /** The result of the tool call, when there is one. */
+    toolResult?: {
+        output: unknown;
+    };
+    /** The response, when the policy is asked about one. */
+    response?: {
+        text: string;
+    };
+    /** The session the work happens in. */
+    session: {
+        id: string;
+        taskId?: string;
+        roleId: string;
+    };
+    /** The files the work touches. */
+    files?: FileChange[];
+    /** The high-risk domain the classifier fired on, when it fired (§20.3). */
+    highRiskDomain?: string;
+    /** The declared scope of the role (§22), when the role declares one. */
+    scope?: {
+        declaredPaths?: readonly string[];
+    };
+}
+/**
+ * What a policy decided.
+ *
+ * A policy that lets the thing through says so, a policy that notes
+ * something flags it, a policy that stops it blocks it with a reason, and a
+ * policy that changes it hands the change back.
+ */
+export type PolicyResult = {
+    action: 'allow';
+} | {
+    action: 'flag';
+    findings: PolicyFinding[];
+    severity: PolicySeverity;
+} | {
+    action: 'block';
+    reason: string;
+    finding?: PolicyFinding;
+} | {
+    action: 'transform';
+    payload: unknown;
+};
+/** A policy module. */
+export interface PolicyModule {
+    /** The stable id of the policy, e.g. `oa.anti-sycophancy`. */
+    id: string;
+    /** The version of the policy, e.g. `1.0.0`. */
+    version: string;
+    /** The layer of the guardrail stack the policy acts at (§17.4). */
+    layer: PolicyLayer;
+    /** What the policy is for, in a line. */
+    description: string;
+    /** The moments the policy is checked at. */
+    appliesTo: PolicyMoment[];
+    /** Whether the policy is ours or came from a plugin (§21). */
+    origin: PolicyOrigin;
+    /** The decision the policy makes. */
+    evaluate: (ctx: PolicyContext) => PolicyResult;
+}
+/** The result of a policy that let the thing through. */
+export declare function allow(): PolicyResult;
+/** The result of a policy that noted something. */
+export declare function flag(findings: PolicyFinding[], severity?: PolicySeverity): PolicyResult;
+/** The result of a policy that stopped the thing. */
+export declare function block(reason: string, finding?: PolicyFinding): PolicyResult;
+/**
+ * The findings of a set of matches.
+ *
+ * The policy id is on every finding, so a finding that travels on its own
+ * still says which policy produced it.
+ */
+export declare function findingsOf(policyId: string, type: string, matches: readonly string[]): PolicyFinding[];
+/** What a policy did, as the engine reports it. */
+export type PolicyOutcome = {
+    /** The policy that was asked. */
+    policyId: string;
+    /** The version it carried at that moment. */
+    version: string;
+    /** The layer it acts at. */
+    layer: PolicyLayer;
+    /** What it decided. */
+    action: PolicyAction;
+    /** The severity of a flag. */
+    severity?: PolicySeverity | undefined;
+    /** Why it acted. */
+    reason?: string | undefined;
+    /** What it found. */
+    findings: PolicyFinding[];
+};
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

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