@openagentsy/hooks 0.0.0-stage → 0.2.0

package/dist/policies/selection.js

@@ -0,0 +1,93 @@
+import { HIGH_RISK_PREFIX } from './high-risk.js';
+/**
+ * The selection of the policy stack (§21.4).
+ *
+ * The stack is assembled from the classification of the request, and the
+ * assembly is explainable: every module that was selected says why it was
+ * selected, so a reader can tell a guardrail that was always on from one
+ * that the classifier brought in.
+ */
+/**
+ * The stack every session gets (§21.4).
+ *
+ * The list is the one §21.4 names, with `oa.structural-bias` added: the
+ * detector of §21.5 is a layer 4 module, and a module that is not in the
+ * stack never runs.
+ */
+const BASELINE_POLICY_IDS = [
+    'oa.truthfulness-uncertainty',
+    'oa.anti-sycophancy',
+    'oa.anti-anthropomorphism',
+    'oa.anti-dependence',
+    'oa.agi-framing',
+    'oa.professional-displacement',
+    'oa.structural-bias',
+    'oa.dark-pattern',
+    'oa.scope-enforcement',
+    'oa.privacy-transparency',
+    'oa.third-party-impact',
+];
+/**
+ * The stack that is on every tool call (§21.2, layer 1).
+ *
+ * These are the guardrails that hold whatever the request is: the git
+ * hooks, the package manager, the writes, the files a person changes, the
+ * decisions a person makes, the secrets and the destructive commands.
+ */
+const ALWAYS_ON_POLICY_IDS = [
+    'oa.no-skip-git-hooks',
+    'oa.package-manager',
+    'oa.workspace-writes-only',
+    'oa.protect-policy',
+    'oa.human-only-decisions',
+    'oa.secret-scan-writes',
+    'oa.destructive-needs-approval',
+];
+/**
+ * The high-risk domain a policy id names, when it names one.
+ *
+ * The id of a high-risk policy is the domain it guards, so the selection
+ * reads the domain off the id rather than off a second list that could
+ * disagree with it.
+ */
+function highRiskDomainOf(id) {
+    if (!id.startsWith(HIGH_RISK_PREFIX))
+        return undefined;
+    const domain = id.slice(HIGH_RISK_PREFIX.length);
+    return domain.length === 0 ? undefined : domain;
+}
+/**
+ * The stack for a classification, and why each module is in it.
+ *
+ * A module of the always-on list is in every stack. A module of the
+ * baseline list is in every stack. A high-risk module is in the stack when
+ * the classification named its domain, and a plugin module is in the stack
+ * as well: a downstream project that installed a module asked for it to
+ * run.
+ */
+export function selectPolicies(modules, classification) {
+    const domain = classification.highRiskDomain;
+    const selected = [];
+    for (const module of modules) {
+        if (ALWAYS_ON_POLICY_IDS.includes(module.id)) {
+            selected.push({ module, reason: 'the guardrail applies to every tool call' });
+            continue;
+        }
+        const highRisk = highRiskDomainOf(module.id);
+        if (highRisk !== undefined) {
+            if (domain !== undefined && domain === highRisk) {
+                selected.push({
+                    module,
+                    reason: `the classification named the ${highRisk} domain`,
+                });
+            }
+            continue;
+        }
+        const reason = BASELINE_POLICY_IDS.includes(module.id)
+            ? 'every session gets this policy'
+            : 'a plugin brought this policy';
+        selected.push({ module, reason });
+    }
+    return selected;
+}
+//# sourceMappingURL=selection.js.map

package/dist/policies/selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection.js","sourceRoot":"","sources":["../../src/policies/selection.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,mBAAmB,GAAsB;IAC7C,6BAA6B;IAC7B,oBAAoB;IACpB,0BAA0B;IAC1B,oBAAoB;IACpB,gBAAgB;IAChB,8BAA8B;IAC9B,oBAAoB;IACpB,iBAAiB;IACjB,sBAAsB;IACtB,yBAAyB;IACzB,uBAAuB;CACxB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,oBAAoB,GAAsB;IAC9C,sBAAsB;IACtB,oBAAoB;IACpB,0BAA0B;IAC1B,mBAAmB;IACnB,yBAAyB;IACzB,uBAAuB;IACvB,+BAA+B;CAChC,CAAC;AAUF;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,EAAU;IAClC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,gBAAgB,CAAC;QAAE,OAAO,SAAS,CAAC;IACvD,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;AAClD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAgC,EAChC,cAAqC;IAErC,MAAM,MAAM,GAAG,cAAc,CAAC,cAAc,CAAC;IAC7C,MAAM,QAAQ,GAAqB,EAAE,CAAC;IACtC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,oBAAoB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;YAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC,CAAC;YAC9E,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC7C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAChD,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM;oBACN,MAAM,EAAE,gCAAgC,QAAQ,SAAS;iBAC1D,CAAC,CAAC;YACL,CAAC;YACD,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,mBAAmB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACpD,CAAC,CAAC,gCAAgC;YAClC,CAAC,CAAC,8BAA8B,CAAC;QACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/policies/structural-bias.d.ts

@@ -0,0 +1,14 @@
+import { type PolicyModule } from '../policy.js';
+/**
+ * The structural bias policy (§21.2, §21.5).
+ *
+ * It flags the defaults and affordances that systematically advantage a
+ * privileged user profile: copy that assumes a GPU, English, broadband, a
+ * US grid factor, a Mac or a corporate GitHub account. It flags and does not
+ * block: the reader decides who the copy is for.
+ */
+/** The stable id of the policy. */
+export declare const STRUCTURAL_BIAS_ID = "oa.structural-bias";
+/** The policy itself. */
+export declare const structuralBias: PolicyModule;
+//# sourceMappingURL=structural-bias.d.ts.map

package/dist/policies/structural-bias.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-bias.d.ts","sourceRoot":"","sources":["../../src/policies/structural-bias.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;;;;GAOG;AAEH,mCAAmC;AACnC,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAavD,yBAAyB;AACzB,eAAO,MAAM,cAAc,EAAE,YAc5B,CAAC"}

package/dist/policies/structural-bias.js

@@ -0,0 +1,41 @@
+import { allow, findingsOf, flag } from '../policy.js';
+import { matches } from './patterns.js';
+/**
+ * The structural bias policy (§21.2, §21.5).
+ *
+ * It flags the defaults and affordances that systematically advantage a
+ * privileged user profile: copy that assumes a GPU, English, broadband, a
+ * US grid factor, a Mac or a corporate GitHub account. It flags and does not
+ * block: the reader decides who the copy is for.
+ */
+/** The stable id of the policy. */
+export const STRUCTURAL_BIAS_ID = 'oa.structural-bias';
+/** The assumptions that leave somebody out. */
+const BIAS = [
+    /\b(?:assumes?|assuming|requires?|needs?|expects?)\b[^.]{0,40}\b(?:gpu|cuda|nvidia)\b/gi,
+    /\b(?:assumes?|assuming|requires?|needs?|expects?)\b[^.]{0,40}\benglish\b/gi,
+    /\b(?:assumes?|assuming|requires?|needs?|expects?)\b[^.]{0,40}\b(?:broadband|fiber|high[- ]speed)\b/gi,
+    /\b(?:assumes?|assuming|requires?|needs?|expects?)\b[^.]{0,40}\bus\s+grid\s+factor\b/gi,
+    /\b(?:assumes?|assuming|requires?|needs?|expects?)\b[^.]{0,40}\bmac\b/gi,
+    /\b(?:assumes?|assuming|requires?|needs?|expects?)\b[^.]{0,40}\b(?:corporate|company|organisation|organization)\s+github\b/gi,
+    /\bgithub\s+(?:enterprise|team)\s+account\b/gi,
+];
+/** The policy itself. */
+export const structuralBias = {
+    id: STRUCTURAL_BIAS_ID,
+    version: '1.0.0',
+    layer: 4,
+    description: 'Flags defaults and affordances that advantage a privileged user profile.',
+    appliesTo: ['PreResponse'],
+    origin: 'first-party',
+    evaluate(ctx) {
+        const text = ctx.response?.text ?? ctx.request?.text ?? '';
+        if (text === '')
+            return allow();
+        const found = matches(BIAS, text);
+        if (found.length === 0)
+            return allow();
+        return flag(findingsOf(STRUCTURAL_BIAS_ID, 'structural-bias', found));
+    },
+};
+//# sourceMappingURL=structural-bias.js.map

package/dist/policies/structural-bias.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-bias.js","sourceRoot":"","sources":["../../src/policies/structural-bias.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAqB,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC;;;;;;;GAOG;AAEH,mCAAmC;AACnC,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEvD,+CAA+C;AAC/C,MAAM,IAAI,GAAG;IACX,wFAAwF;IACxF,4EAA4E;IAC5E,sGAAsG;IACtG,uFAAuF;IACvF,wEAAwE;IACxE,6HAA6H;IAC7H,8CAA8C;CAC/C,CAAC;AAEF,yBAAyB;AACzB,MAAM,CAAC,MAAM,cAAc,GAAiB;IAC1C,EAAE,EAAE,kBAAkB;IACtB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,CAAC;IACR,WAAW,EAAE,0EAA0E;IACvF,SAAS,EAAE,CAAC,aAAa,CAAC;IAC1B,MAAM,EAAE,aAAa;IACrB,QAAQ,CAAC,GAAG;QACV,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,EAAE,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;QAC3D,IAAI,IAAI,KAAK,EAAE;YAAE,OAAO,KAAK,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAClC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC,UAAU,CAAC,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC;CACF,CAAC"}

package/dist/policies/third-party-impact.d.ts

@@ -0,0 +1,13 @@
+import { type PolicyModule } from '../policy.js';
+/**
+ * The third-party impact policy (§21.2).
+ *
+ * It flags the output that reaches people who are not in the conversation:
+ * the users a change lands on, the applicants a score ranks, and the
+ * decisions a person is not in the room for. It flags and does not block.
+ */
+/** The stable id of the policy. */
+export declare const THIRD_PARTY_IMPACT_ID = "oa.third-party-impact";
+/** The policy itself. */
+export declare const thirdPartyImpact: PolicyModule;
+//# sourceMappingURL=third-party-impact.d.ts.map

package/dist/policies/third-party-impact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"third-party-impact.d.ts","sourceRoot":"","sources":["../../src/policies/third-party-impact.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;;;GAMG;AAEH,mCAAmC;AACnC,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAW7D,yBAAyB;AACzB,eAAO,MAAM,gBAAgB,EAAE,YAc9B,CAAC"}

package/dist/policies/third-party-impact.js

@@ -0,0 +1,38 @@
+import { allow, findingsOf, flag } from '../policy.js';
+import { matches } from './patterns.js';
+/**
+ * The third-party impact policy (§21.2).
+ *
+ * It flags the output that reaches people who are not in the conversation:
+ * the users a change lands on, the applicants a score ranks, and the
+ * decisions a person is not in the room for. It flags and does not block.
+ */
+/** The stable id of the policy. */
+export const THIRD_PARTY_IMPACT_ID = 'oa.third-party-impact';
+/** The words that reach past the conversation. */
+const THIRD_PARTY = [
+    /\b(?:affects|impacts|changes|change)\s+(?:how\s+|the\s+way\s+)?(?:your|the)\s+(?:users|customers|clients|employees|end[- ]users|tenants)\b/gi,
+    /\b(?:affects|impacts)\s+(?:other\s+)?(?:users|customers|clients|employees|tenants|third\s+parties|stakeholders)\b/gi,
+    /\bwithout\s+(?:their|the\s+user'?s?)\s+(?:knowledge|consent)\b/gi,
+    /\b(?:ranks?|scores?|rejects?|approves?)\s+(?:applicants|candidates|tenants|borrowers|employees)\b/gi,
+    /\b(?:hiring|lending|criminal\s+justice|public\s+benefits)\s+decisions?\b/gi,
+];
+/** The policy itself. */
+export const thirdPartyImpact = {
+    id: THIRD_PARTY_IMPACT_ID,
+    version: '1.0.0',
+    layer: 4,
+    description: 'Flags the output that affects people who are not in the conversation.',
+    appliesTo: ['PreResponse'],
+    origin: 'first-party',
+    evaluate(ctx) {
+        const text = ctx.response?.text ?? ctx.request?.text ?? '';
+        if (text === '')
+            return allow();
+        const found = matches(THIRD_PARTY, text);
+        if (found.length === 0)
+            return allow();
+        return flag(findingsOf(THIRD_PARTY_IMPACT_ID, 'third-party-impact', found));
+    },
+};
+//# sourceMappingURL=third-party-impact.js.map

package/dist/policies/third-party-impact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"third-party-impact.js","sourceRoot":"","sources":["../../src/policies/third-party-impact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAqB,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC;;;;;;GAMG;AAEH,mCAAmC;AACnC,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAE7D,kDAAkD;AAClD,MAAM,WAAW,GAAG;IAClB,8IAA8I;IAC9I,qHAAqH;IACrH,kEAAkE;IAClE,qGAAqG;IACrG,4EAA4E;CAC7E,CAAC;AAEF,yBAAyB;AACzB,MAAM,CAAC,MAAM,gBAAgB,GAAiB;IAC5C,EAAE,EAAE,qBAAqB;IACzB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,CAAC;IACR,WAAW,EAAE,uEAAuE;IACpF,SAAS,EAAE,CAAC,aAAa,CAAC;IAC1B,MAAM,EAAE,aAAa;IACrB,QAAQ,CAAC,GAAG;QACV,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,EAAE,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;QAC3D,IAAI,IAAI,KAAK,EAAE;YAAE,OAAO,KAAK,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC,UAAU,CAAC,qBAAqB,EAAE,oBAAoB,EAAE,KAAK,CAAC,CAAC,CAAC;IAC9E,CAAC;CACF,CAAC"}

package/dist/policies/tool-call.d.ts

@@ -0,0 +1,38 @@
+import type { FileChange, PolicyContext } from '../policy.js';
+/**
+ * The tool call of a context, read out of it.
+ *
+ * The context carries the name of the tool and its arguments in the shape
+ * the host gave them, so the call is read the way the hook rules read it:
+ * the command is the one the arguments name, and the files are the ones the
+ * context carries or the arguments name.
+ */
+/** The tool call, as a policy reads it. */
+export interface ToolCallFacts {
+    /** The name of the tool. */
+    name: string;
+    /** The arguments the call was made with. */
+    args: Record<string, unknown>;
+    /** The command, for a shell call. */
+    command?: string | undefined;
+    /** The files the call touches. */
+    files: FileChange[];
+}
+/**
+ * The tool call of a context.
+ *
+ * A context without a tool call has none, and a policy that reads one lets
+ * the thing through.
+ */
+export declare function readToolCall(ctx: PolicyContext): ToolCallFacts | undefined;
+/**
+ * Whether a call writes a file.
+ *
+ * A tool that is known to write writes; a tool that is known to read does
+ * not, even when it names a file. A name that is neither is treated as a
+ * writer when the call names a file, because a policy that let an unknown
+ * name through would let every write the host names in an unfamiliar way
+ * through.
+ */
+export declare function writesFiles(call: ToolCallFacts): boolean;
+//# sourceMappingURL=tool-call.d.ts.map

package/dist/policies/tool-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call.d.ts","sourceRoot":"","sources":["../../src/policies/tool-call.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE9D;;;;;;;GAOG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,kCAAkC;IAClC,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAoBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,aAAa,GAAG,SAAS,CAY1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAGxD"}

package/dist/policies/tool-call.js

@@ -0,0 +1,53 @@
+import { isWritingTool } from '../event.js';
+/** The argument names a write tool names its file with. */
+const PATH_ARGS = ['filePath', 'file_path', 'path', 'file'];
+/** The arguments, when they are an object. */
+function argsOf(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return {};
+    return value;
+}
+/** The files the arguments name. */
+function filesFromArgs(args) {
+    for (const key of PATH_ARGS) {
+        const value = args[key];
+        if (typeof value === 'string' && value.length > 0)
+            return [{ path: value }];
+    }
+    return [];
+}
+/**
+ * The tool call of a context.
+ *
+ * A context without a tool call has none, and a policy that reads one lets
+ * the thing through.
+ */
+export function readToolCall(ctx) {
+    const call = ctx.toolCall;
+    if (call === undefined)
+        return undefined;
+    const args = argsOf(call.args);
+    const command = args['command'];
+    const files = ctx.files !== undefined && ctx.files.length > 0 ? ctx.files : filesFromArgs(args);
+    return {
+        name: call.name,
+        args,
+        command: typeof command === 'string' ? command : undefined,
+        files,
+    };
+}
+/**
+ * Whether a call writes a file.
+ *
+ * A tool that is known to write writes; a tool that is known to read does
+ * not, even when it names a file. A name that is neither is treated as a
+ * writer when the call names a file, because a policy that let an unknown
+ * name through would let every write the host names in an unfamiliar way
+ * through.
+ */
+export function writesFiles(call) {
+    if (isWritingTool(call.name))
+        return true;
+    return call.files.length > 0;
+}
+//# sourceMappingURL=tool-call.js.map

package/dist/policies/tool-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call.js","sourceRoot":"","sources":["../../src/policies/tool-call.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAwB5C,2DAA2D;AAC3D,MAAM,SAAS,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5D,8CAA8C;AAC9C,SAAS,MAAM,CAAC,KAAc;IAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnF,OAAO,KAAgC,CAAC;AAC1C,CAAC;AAED,oCAAoC;AACpC,SAAS,aAAa,CAAC,IAA6B;IAClD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,GAAkB;IAC7C,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC;IAC1B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAChG,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI;QACJ,OAAO,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;QAC1D,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,IAAmB;IAC7C,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AAC/B,CAAC"}

package/dist/policies/truthfulness-uncertainty.d.ts

@@ -0,0 +1,13 @@
+import { type PolicyModule } from '../policy.js';
+/**
+ * The truthfulness and uncertainty policy (§21.2, layer 3).
+ *
+ * It is the prompt module of the stack: it asks for the difference between
+ * a fact, an inference and a guess to be visible, and it flags the reply
+ * that asserts without any sign of doubt when the evidence is thin.
+ */
+/** The stable id of the policy. */
+export declare const TRUTHFULNESS_UNCERTAINTY_ID = "oa.truthfulness-uncertainty";
+/** The policy itself. */
+export declare const truthfulnessUncertainty: PolicyModule;
+//# sourceMappingURL=truthfulness-uncertainty.d.ts.map

package/dist/policies/truthfulness-uncertainty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truthfulness-uncertainty.d.ts","sourceRoot":"","sources":["../../src/policies/truthfulness-uncertainty.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;;;GAMG;AAEH,mCAAmC;AACnC,eAAO,MAAM,2BAA2B,gCAAgC,CAAC;AAiBzE,yBAAyB;AACzB,eAAO,MAAM,uBAAuB,EAAE,YAgBrC,CAAC"}

package/dist/policies/truthfulness-uncertainty.js

@@ -0,0 +1,45 @@
+import { allow, findingsOf, flag } from '../policy.js';
+import { matches } from './patterns.js';
+/**
+ * The truthfulness and uncertainty policy (§21.2, layer 3).
+ *
+ * It is the prompt module of the stack: it asks for the difference between
+ * a fact, an inference and a guess to be visible, and it flags the reply
+ * that asserts without any sign of doubt when the evidence is thin.
+ */
+/** The stable id of the policy. */
+export const TRUTHFULNESS_UNCERTAINTY_ID = 'oa.truthfulness-uncertainty';
+/** The words that claim more than the evidence carries. */
+const CERTAIN = [
+    /\b(?:definitely|certainly|guaranteed|without\s+doubt|100%\s+certain)\b/gi,
+    /\b(?:always|never)\s+(?:the\s+)?(?:case|true|right|wrong)\b/gi,
+];
+/** The words that mark an inference or a guess as one. */
+const DOUBT = [
+    /\b(?:probably|likely|unlikely|perhaps|maybe|possibly|apparently)\b/gi,
+    /\b(?:i\s+think|i\s+believe|it\s+seems|it\s+appears|as\s+far\s+as\s+i\s+can\s+tell)\b/gi,
+    /\b(?:unclear|uncertain|not\s+sure|cannot\s+be\s+sure)\b/gi,
+    /\b(?:roughly|approximately|about\s+\d)\b/gi,
+    /\b(?:may|might|could)\s+(?:be|have|not)\b/gi,
+];
+/** The policy itself. */
+export const truthfulnessUncertainty = {
+    id: TRUTHFULNESS_UNCERTAINTY_ID,
+    version: '1.0.0',
+    layer: 3,
+    description: 'Asks for facts, inferences and guesses to be told apart, and flags certainty without doubt.',
+    appliesTo: ['UserPromptSubmit', 'PreResponse'],
+    origin: 'first-party',
+    evaluate(ctx) {
+        const text = ctx.response?.text ?? ctx.request?.text ?? '';
+        if (text === '')
+            return allow();
+        const certain = matches(CERTAIN, text);
+        if (certain.length === 0)
+            return allow();
+        if (matches(DOUBT, text).length > 0)
+            return allow();
+        return flag(findingsOf(TRUTHFULNESS_UNCERTAINTY_ID, 'certainty', certain));
+    },
+};
+//# sourceMappingURL=truthfulness-uncertainty.js.map

package/dist/policies/truthfulness-uncertainty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truthfulness-uncertainty.js","sourceRoot":"","sources":["../../src/policies/truthfulness-uncertainty.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAqB,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC;;;;;;GAMG;AAEH,mCAAmC;AACnC,MAAM,CAAC,MAAM,2BAA2B,GAAG,6BAA6B,CAAC;AAEzE,2DAA2D;AAC3D,MAAM,OAAO,GAAG;IACd,0EAA0E;IAC1E,+DAA+D;CAChE,CAAC;AAEF,0DAA0D;AAC1D,MAAM,KAAK,GAAG;IACZ,sEAAsE;IACtE,wFAAwF;IACxF,2DAA2D;IAC3D,4CAA4C;IAC5C,6CAA6C;CAC9C,CAAC;AAEF,yBAAyB;AACzB,MAAM,CAAC,MAAM,uBAAuB,GAAiB;IACnD,EAAE,EAAE,2BAA2B;IAC/B,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,CAAC;IACR,WAAW,EACT,6FAA6F;IAC/F,SAAS,EAAE,CAAC,kBAAkB,EAAE,aAAa,CAAC;IAC9C,MAAM,EAAE,aAAa;IACrB,QAAQ,CAAC,GAAG;QACV,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,EAAE,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;QAC3D,IAAI,IAAI,KAAK,EAAE;YAAE,OAAO,KAAK,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,EAAE,CAAC;QACzC,IAAI,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC,UAAU,CAAC,2BAA2B,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7E,CAAC;CACF,CAAC"}

package/dist/policies/workspace-writes-only.d.ts

@@ -0,0 +1,25 @@
+import { type PolicyModule } from '../policy.js';
+/**
+ * The workspace-writes-only policy (§21.2, layer 1).
+ *
+ * It blocks a write outside the workspace and outside the OpenAgentsy
+ * worktrees of the same project. The policy is built with the workspace it
+ * guards, because the roots are what the decision is made against.
+ */
+/** The stable id of the policy. */
+export declare const WORKSPACE_WRITES_ONLY_ID = "oa.workspace-writes-only";
+/** What the policy is built with. */
+export interface WorkspaceWritesOnlyOptions {
+    /** The workspace root: the project the agent works in. */
+    workspace: string;
+    /** The home directory the worktrees live under; the home of the user by default. */
+    home?: string | undefined;
+}
+/**
+ * The policy itself.
+ *
+ * The roots are the workspace and the worktrees of the same project, and a
+ * write that lands outside both of them is the one that is blocked.
+ */
+export declare function workspaceWritesOnly(options: WorkspaceWritesOnlyOptions): PolicyModule;
+//# sourceMappingURL=workspace-writes-only.d.ts.map

package/dist/policies/workspace-writes-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-writes-only.d.ts","sourceRoot":"","sources":["../../src/policies/workspace-writes-only.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAG/D;;;;;;GAMG;AAEH,mCAAmC;AACnC,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE,qCAAqC;AACrC,MAAM,WAAW,0BAA0B;IACzC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAYD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,YAAY,CAuBrF"}

package/dist/policies/workspace-writes-only.js

@@ -0,0 +1,54 @@
+import { isAbsolute, resolve } from 'node:path';
+import { isInside, projectName, worktreeRoot } from '../paths.js';
+import { allow, block } from '../policy.js';
+import { readToolCall, writesFiles } from './tool-call.js';
+/**
+ * The workspace-writes-only policy (§21.2, layer 1).
+ *
+ * It blocks a write outside the workspace and outside the OpenAgentsy
+ * worktrees of the same project. The policy is built with the workspace it
+ * guards, because the roots are what the decision is made against.
+ */
+/** The stable id of the policy. */
+export const WORKSPACE_WRITES_ONLY_ID = 'oa.workspace-writes-only';
+/**
+ * A path, made absolute against the workspace.
+ *
+ * A host names a file either way, and a relative path is relative to the
+ * project the agent works in.
+ */
+function absolutePath(root, path) {
+    return isAbsolute(path) ? path : resolve(root, path);
+}
+/**
+ * The policy itself.
+ *
+ * The roots are the workspace and the worktrees of the same project, and a
+ * write that lands outside both of them is the one that is blocked.
+ */
+export function workspaceWritesOnly(options) {
+    const root = resolve(options.workspace);
+    const roots = [root, worktreeRoot(projectName(root), options.home)];
+    return {
+        id: WORKSPACE_WRITES_ONLY_ID,
+        version: '1.0.0',
+        layer: 1,
+        description: 'Blocks the writes that land outside the workspace and the worktrees.',
+        appliesTo: ['PreToolCall'],
+        origin: 'first-party',
+        evaluate(ctx) {
+            const call = readToolCall(ctx);
+            if (call === undefined)
+                return allow();
+            if (!writesFiles(call))
+                return allow();
+            const outside = call.files.some((file) => [file.path, file.fromPath]
+                .filter((path) => path !== undefined)
+                .some((path) => !isInside(absolutePath(root, path), roots)));
+            if (!outside)
+                return allow();
+            return block('Writes are limited to the workspace and OpenAgentsy worktrees.');
+        },
+    };
+}
+//# sourceMappingURL=workspace-writes-only.js.map

package/dist/policies/workspace-writes-only.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-writes-only.js","sourceRoot":"","sources":["../../src/policies/workspace-writes-only.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAqB,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE3D;;;;;;GAMG;AAEH,mCAAmC;AACnC,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAC;AAUnE;;;;;GAKG;AACH,SAAS,YAAY,CAAC,IAAY,EAAE,IAAY;IAC9C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAmC;IACrE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,OAAO;QACL,EAAE,EAAE,wBAAwB;QAC5B,OAAO,EAAE,OAAO;QAChB,KAAK,EAAE,CAAC;QACR,WAAW,EAAE,sEAAsE;QACnF,SAAS,EAAE,CAAC,aAAa,CAAC;QAC1B,MAAM,EAAE,aAAa;QACrB,QAAQ,CAAC,GAAG;YACV,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,KAAK,EAAE,CAAC;YACvC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;gBAAE,OAAO,KAAK,EAAE,CAAC;YACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CACvC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC;iBACvB,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC;iBACpD,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC,CAC9D,CAAC;YACF,IAAI,CAAC,OAAO;gBAAE,OAAO,KAAK,EAAE,CAAC;YAC7B,OAAO,KAAK,CAAC,gEAAgE,CAAC,CAAC;QACjF,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/policy-engine.d.ts

@@ -0,0 +1,69 @@
+import type { PolicyFiringSink } from '@openagentsy/core';
+import type { PolicyContext, PolicyModule, PolicyMoment, PolicyOutcome, PolicyResult } from './policy.js';
+import type { PolicyRegistry } from './policy-registry.js';
+/**
+ * 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 declare const STACK_POLICY_ID = "oa.policy.stack";
+/** The version of the stack row. */
+export declare const STACK_POLICY_VERSION = "1.0.0";
+/** What the engine is built with. */
+export interface PolicyEngineOptions {
+    /** Where the firings go; an engine without one records nothing. */
+    sink?: PolicyFiringSink | undefined;
+}
+/**
+ * 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 declare function momentOf(ctx: PolicyContext): PolicyMoment | 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 declare function outcomeOf(module: PolicyModule, result: PolicyResult): PolicyOutcome;
+/** The engine of a registry. */
+export declare class PolicyEngine {
+    /** The registry the stack comes from. */
+    private readonly registry;
+    /** Where the firings go. */
+    private readonly sink;
+    /** The sessions whose stack was already recorded. */
+    private readonly assembled;
+    /**
+     * 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: PolicyRegistry, options?: PolicyEngineOptions);
+    /**
+     * 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: PolicyContext): PolicyOutcome[];
+    /** The row that records the stack of a session. */
+    private recordStack;
+    /** The row that records one decision. */
+    private record;
+}
+//# sourceMappingURL=policy-engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy-engine.d.ts","sourceRoot":"","sources":["../src/policy-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,EACb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,sBAAsB,CAAC;AAE5E;;;;;;;;;;;;GAYG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD,oCAAoC;AACpC,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C,qCAAqC;AACrC,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,GAAG,SAAS,CAKrE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,aAAa,CAiBnF;AAED,gCAAgC;AAChC,qBAAa,YAAY;IACvB,yCAAyC;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,4BAA4B;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA+B;IACpD,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IAEpD;;;;;OAKG;gBACS,QAAQ,EAAE,cAAc,EAAE,OAAO,GAAE,mBAAwB;IAKvE;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,aAAa,EAAE;IAkB7C,mDAAmD;IACnD,OAAO,CAAC,WAAW;IAqBnB,yCAAyC;IACzC,OAAO,CAAC,MAAM;CAkBf"}