@agentpolicyspecification/core 0.1.0

package/dist/generated/policy-set.d.ts

@@ -0,0 +1,139 @@
+/**
+ * A condition evaluated against the context
+ */
+export type Condition = EqualsCondition | ContainsCondition | NotInCondition | GreaterThanCondition | AlwaysCondition;
+/**
+ * A collection of DSL policies with interception point and tool scope bindings
+ */
+export interface PolicySet {
+    /**
+     * The APS specification version this policy set targets (e.g. '0.1.0').
+     */
+    aps_version: string;
+    /**
+     * The list of policies in this set
+     */
+    policies: PolicyEntry[];
+}
+/**
+ * A DSL policy rule with optional scope restrictions
+ */
+export interface PolicyEntry {
+    condition: Condition;
+    /**
+     * The action to take when the condition matches
+     */
+    action: "allow" | "deny" | "redact" | "transform" | "audit";
+    /**
+     * Optional human-readable reason, typically used with deny
+     */
+    reason?: string;
+    /**
+     * Redaction instructions to apply when action is 'redact'.
+     *
+     * @minItems 1
+     */
+    redactions?: [
+        {
+            /**
+             * Dot-notation path to the field being redacted (e.g. 'response.content').
+             */
+            field: string;
+            /**
+             * 'mask' replaces with a fixed string, 'remove' deletes the field, 'replace' substitutes matched patterns.
+             */
+            strategy: "mask" | "remove" | "replace";
+            /**
+             * Replacement string. Required when strategy is 'mask' or 'replace'.
+             */
+            replacement?: string;
+            /**
+             * Regex pattern identifying the content to redact. Required when strategy is 'replace'.
+             */
+            pattern?: string;
+        },
+        ...{
+            /**
+             * Dot-notation path to the field being redacted (e.g. 'response.content').
+             */
+            field: string;
+            /**
+             * 'mask' replaces with a fixed string, 'remove' deletes the field, 'replace' substitutes matched patterns.
+             */
+            strategy: "mask" | "remove" | "replace";
+            /**
+             * Replacement string. Required when strategy is 'mask' or 'replace'.
+             */
+            replacement?: string;
+            /**
+             * Regex pattern identifying the content to redact. Required when strategy is 'replace'.
+             */
+            pattern?: string;
+        }[]
+    ];
+    /**
+     * Field transformations when action is 'transform'. Keys are dot-notation field paths, values are template strings supporting {{field.path}} interpolation.
+     */
+    transformation?: {
+        [k: string]: string;
+    };
+    /**
+     * Interception points this policy applies to. Omit to apply to all points.
+     *
+     * @minItems 1
+     */
+    applies_to?: ["input" | "output" | "tool_call", ...("input" | "output" | "tool_call")[]];
+    /**
+     * Tool names this policy applies to. Only evaluated when applies_to includes 'tool_call'. Omit to apply to all tools.
+     */
+    tools?: string[];
+}
+/**
+ * Matches when the resolved field value strictly equals the operand
+ */
+export interface EqualsCondition {
+    /**
+     * Dot-notation path to the field in the context (e.g. 'tool_name', 'messages.0.content')
+     */
+    field: string;
+    /**
+     * The value to compare against using strict equality
+     */
+    equals: {
+        [k: string]: unknown;
+    };
+}
+/**
+ * Matches when the resolved field value contains any of the given substrings (case-insensitive)
+ */
+export interface ContainsCondition {
+    field: string;
+    /**
+     * @minItems 1
+     */
+    contains: [string, ...string[]];
+}
+/**
+ * Matches when the resolved field value is not present in the given list
+ */
+export interface NotInCondition {
+    field: string;
+    /**
+     * List of values the field must not be equal to
+     */
+    not_in: unknown[];
+}
+/**
+ * Matches when the resolved field value is numerically greater than the operand
+ */
+export interface GreaterThanCondition {
+    field: string;
+    greater_than: number;
+}
+/**
+ * Always matches, regardless of context
+ */
+export interface AlwaysCondition {
+    always: true;
+}
+//# sourceMappingURL=policy-set.d.ts.map

package/dist/generated/policy-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-set.d.ts","sourceRoot":"","sources":["../../src/generated/policy-set.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,iBAAiB,GAAG,cAAc,GAAG,oBAAoB,GAAG,eAAe,CAAC;AAEtH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AACD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB;;OAEG;IACH,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;IAC5D;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE;QACX;YACE;;eAEG;YACH,KAAK,EAAE,MAAM,CAAC;YACd;;eAEG;YACH,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;YACxC;;eAEG;YACH,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB;;eAEG;YACH,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB;QACD,GAAG;YACD;;eAEG;YACH,KAAK,EAAE,MAAM,CAAC;YACd;;eAEG;YACH,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;YACxC;;eAEG;YACH,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB;;eAEG;YACH,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB,EAAE;KACJ,CAAC;IACF;;OAEG;IACH,cAAc,CAAC,EAAE;QACf,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KACrB,CAAC;IACF;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,GAAG,QAAQ,GAAG,WAAW,EAAE,GAAG,CAAC,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IACzF;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AACD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,MAAM,EAAE;QACN,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;KACtB,CAAC;CACH;AACD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;CACjC;AACD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AACD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB;AACD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,IAAI,CAAC;CACd"}

package/dist/generated/policy-set.js

@@ -0,0 +1,4 @@
+/* eslint-disable */
+// This file is auto-generated from policy-set.schema.json. Do not edit manually.
+export {};
+//# sourceMappingURL=policy-set.js.map

package/dist/generated/policy-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-set.js","sourceRoot":"","sources":["../../src/generated/policy-set.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,iFAAiF"}

package/dist/generated/tool-call-context.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The evaluation input provided to policies at the Tool Call Interception point.
+ */
+export type ToolCallContext = ApsBase & {
+    /**
+     * The name of the tool the LLM has requested to invoke.
+     */
+    tool_name: string;
+    /**
+     * The arguments provided by the LLM for the tool invocation.
+     */
+    arguments: {
+        [k: string]: unknown;
+    };
+    calling_message: AssistantMessage;
+    metadata: Metadata;
+};
+/**
+ * Base schema for the Agent Policy Specification v0.1.0. All other APS schemas extend this schema. Defines shared types used across the specification.
+ */
+export interface ApsBase {
+    [k: string]: unknown;
+}
+/**
+ * A message produced by the LLM (role must be 'assistant').
+ */
+export interface AssistantMessage {
+    role: "assistant";
+    /**
+     * The text content of the assistant message.
+     */
+    content: string;
+}
+/**
+ * Common metadata attached to every APS context object.
+ */
+export interface Metadata {
+    /**
+     * Unique identifier for the agent that owns this session.
+     */
+    agent_id: string;
+    /**
+     * Unique identifier for the current session.
+     */
+    session_id: string;
+    /**
+     * ISO 8601 timestamp of when the interception occurred.
+     */
+    timestamp: string;
+    [k: string]: unknown;
+}
+//# sourceMappingURL=tool-call-context.d.ts.map

package/dist/generated/tool-call-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call-context.d.ts","sourceRoot":"","sources":["../../src/generated/tool-call-context.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG;IACtC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,SAAS,EAAE;QACT,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;KACtB,CAAC;IACF,eAAe,EAAE,gBAAgB,CAAC;IAClC,QAAQ,EAAE,QAAQ,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AACD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AACD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB"}

package/dist/generated/tool-call-context.js

@@ -0,0 +1,4 @@
+/* eslint-disable */
+// This file is auto-generated from tool-call-context.schema.json. Do not edit manually.
+export {};
+//# sourceMappingURL=tool-call-context.js.map

package/dist/generated/tool-call-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call-context.js","sourceRoot":"","sources":["../../src/generated/tool-call-context.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,wFAAwF"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export type { Message, InputContext, } from "./generated/input-context.js";
+export type { OutputContext, Metadata, } from './generated/output-context.js';
+export type { ToolCallContext, AssistantMessage, } from './generated/tool-call-context.js';
+export type { PolicyDecision, AllowDecision, DenyDecision, RedactDecision, TransformDecision, AuditDecision, Redaction, Transformation, } from './generated/policy-decision.js';
+export type { DSLPolicy, Condition, EqualsCondition, ContainsCondition, NotInCondition, GreaterThanCondition, AlwaysCondition, } from './generated/dsl-policy.js';
+export type { PolicySet as JsonPolicySet, PolicyEntry, } from './generated/policy-set.js';
+export type { InputPolicy, ToolCallPolicy, OutputPolicy } from "./core/policy.js";
+export { PolicyDenialError, PolicyEvaluationError, } from "./core/errors.js";
+export type { AuditRecord, InterceptionPoint } from "./core/errors.js";
+export type { PolicySet, OnErrorBehavior } from "./engine/policy-set.js";
+export { ApsEngine } from "./engine/aps-engine.js";
+export type { ApsEngineOptions, AuditHandler } from "./engine/aps-engine.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,YAAY,EACV,OAAO,EACP,YAAY,GACb,MAAM,8BAA8B,CAAC;AAEtC,YAAY,EACV,aAAa,EACb,QAAQ,GACT,MAAM,+BAA+B,CAAC;AAEvC,YAAY,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,kCAAkC,CAAC;AAE1C,YAAY,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,SAAS,EACT,cAAc,GACf,MAAM,gCAAgC,CAAC;AAExC,YAAY,EACV,SAAS,EACT,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,eAAe,GAChB,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,SAAS,IAAI,aAAa,EAC1B,WAAW,GACZ,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAElF,OAAO,EACL,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGvE,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { PolicyDenialError, PolicyEvaluationError, } from "./core/errors.js";
+export { ApsEngine } from "./engine/aps-engine.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":"AA2CA,OAAO,EACL,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC"}

package/examples/basic-usage.ts

@@ -0,0 +1,89 @@
+import {
+  ApsEngine,
+  type InputPolicy,
+  type InputContext,
+  type PolicyDecision,
+  type ToolCallPolicy,
+  type ToolCallContext,
+  PolicyDenialError,
+} from "../src/index.js";
+
+// ─── Runtime policies ────────────────────────────────────────────────────
+
+class NoSSNInputPolicy implements InputPolicy {
+  readonly id = "no-ssn-input";
+
+  evaluate(context: InputContext): PolicyDecision {
+    const ssnPattern = /\b\d{3}-\d{2}-\d{4}\b/;
+    const found = context.messages.some((m) => ssnPattern.test(m.content));
+    return found
+      ? { decision: "deny", reason: "Message contains a potential SSN." }
+      : { decision: "allow" };
+  }
+}
+
+class ApprovedToolsPolicy implements ToolCallPolicy {
+  readonly id = "approved-tools";
+  private readonly approved = new Set(["web_search", "read_file", "summarize"]);
+
+  evaluate(context: ToolCallContext): PolicyDecision {
+    return this.approved.has(context.tool_name)
+      ? { decision: "allow" }
+      : { decision: "deny", reason: `Tool '${context.tool_name}' is not approved.` };
+  }
+}
+
+// ─── Engine setup ─────────────────────────────────────────────────────────────
+
+const engine = new ApsEngine({
+  policySet: {
+    on_error: "deny",
+    input: [new NoSSNInputPolicy()],
+    tool_call: [new ApprovedToolsPolicy()],
+  },
+  onAudit: (record) => {
+    console.log("[audit]", record.interception_point, record.decision, record.reason ?? "");
+  },
+});
+
+// ─── Example: allowed input ───────────────────────────────────────────────────
+
+const allowedInput: InputContext = {
+  messages: [{ role: "user", content: "What is the weather in Amsterdam?" }],
+  metadata: { agent_id: "agent-1", session_id: "session-1", timestamp: new Date().toISOString() },
+};
+
+await engine.evaluateInput(allowedInput);
+console.log("Input allowed.");
+
+// ─── Example: denied input ────────────────────────────────────────────────────
+
+const deniedInput: InputContext = {
+  messages: [{ role: "user", content: "My SSN is 123-45-6789, can you store it?" }],
+  metadata: { agent_id: "agent-1", session_id: "session-1", timestamp: new Date().toISOString() },
+};
+
+try {
+  await engine.evaluateInput(deniedInput);
+} catch (err) {
+  if (err instanceof PolicyDenialError) {
+    console.log("Input denied:", err.message);
+  }
+}
+
+// ─── Example: denied tool call ────────────────────────────────────────────────
+
+const deniedToolCall: ToolCallContext = {
+  tool_name: "delete_file",
+  arguments: { path: "/workspace/important.txt" },
+  calling_message: { role: "assistant", content: "I will delete the file." },
+  metadata: { agent_id: "agent-1", session_id: "session-1", timestamp: new Date().toISOString() },
+};
+
+try {
+  await engine.evaluateToolCall(deniedToolCall);
+} catch (err) {
+  if (err instanceof PolicyDenialError) {
+    console.log("Tool call denied:", err.message);
+  }
+}

package/jest.config.js

@@ -0,0 +1,20 @@
+export default {
+  preset: "ts-jest/presets/default-esm",
+  testEnvironment: "node",
+  testMatch: ["**/test/**/*.test.ts"],
+  collectCoverage: true,
+  coverageDirectory: "coverage",
+  coverageProvider: "v8",
+  collectCoverageFrom: ["src/**/*.ts", "!src/generated/**"],
+  transform: {
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        useESM: true,
+      },
+    ],
+  },
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agentpolicyspecification/core",
+  "version": "0.1.0",
+  "description": "Core TypeScript implementation of the Agent Policy Specification (APS)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.5.0",
+    "json-schema-to-typescript": "^15.0.0",
+    "ts-jest": "^29.1.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  },
+  "license": "Apache-2.0",
+  "author": "Pascal Wilbrink",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentpolicyspecification/aps-typescript.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/agentpolicyspecification/aps-typescript/issues"
+  },
+  "homepage": "https://github.com/agentpolicyspecification/aps-typescript/tree/main/packages/core#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run generate-types && tsc",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests",
+    "lint": "eslint src --ext .ts",
+    "example": "tsx examples/basic-usage.ts",
+    "generate-types": "node scripts/generate-types.mjs"
+  }
+}

package/scripts/generate-types.mjs

@@ -0,0 +1,24 @@
+import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { compile } from 'json-schema-to-typescript';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const schemasDir = join(__dirname, '../../../schemas');
+const outDir = join(__dirname, '../src/generated');
+
+await mkdir(outDir, { recursive: true });
+
+const files = (await readdir(schemasDir)).filter(f => f.endsWith('.schema.json'));
+
+for (const file of files) {
+  const schema = JSON.parse(await readFile(join(schemasDir, file), 'utf-8'));
+  const ts = await compile(schema, schema.title ?? basename(file, '.schema.json'), {
+    bannerComment: `/* eslint-disable */\n// This file is auto-generated from ${file}. Do not edit manually.`,
+    cwd: schemasDir,
+  });
+
+  const outFile = join(outDir, basename(file, '.schema.json') + '.ts');
+  await writeFile(outFile, ts, 'utf-8');
+  console.log(`Generated ${outFile}`);
+}

package/src/core/errors.ts

@@ -0,0 +1,44 @@
+import type { InputContext, OutputContext, ToolCallContext } from "./types.js";
+
+export type InterceptionPoint = "input" | "tool_call" | "output";
+
+export class PolicyDenialError extends Error {
+  readonly policy_id: string | undefined;
+  readonly interception_point: InterceptionPoint;
+
+  constructor(opts: {
+    policy_id?: string;
+    interception_point: InterceptionPoint;
+    reason?: string;
+  }) {
+    super(opts.reason ?? "Request denied by policy.");
+    this.name = "PolicyDenialError";
+    this.policy_id = opts.policy_id;
+    this.interception_point = opts.interception_point;
+  }
+}
+
+export class PolicyEvaluationError extends Error {
+  readonly policy_id: string;
+  readonly interception_point: InterceptionPoint;
+
+  constructor(opts: {
+    policy_id: string;
+    interception_point: InterceptionPoint;
+    cause: unknown;
+  }) {
+    super(`Policy evaluation failed for '${opts.policy_id}' at '${opts.interception_point}'.`, { cause: opts.cause });
+    this.name = "PolicyEvaluationError";
+    this.policy_id = opts.policy_id;
+    this.interception_point = opts.interception_point;
+  }
+}
+
+export type AuditRecord = {
+  policy_id: string | undefined;
+  decision: string;
+  interception_point: InterceptionPoint;
+  reason: string | undefined;
+  context: InputContext | ToolCallContext | OutputContext;
+  timestamp: string;
+};

package/src/core/policy.ts

@@ -0,0 +1,19 @@
+import type { PolicyDecision } from "../generated/policy-decision.js";
+import type { InputContext } from "../generated/input-context.js";
+import type { OutputContext } from "../generated/output-context.js";
+import type { ToolCallContext } from "../generated/tool-call-context.js";
+
+export interface InputPolicy {
+  readonly id: string;
+  evaluate(context: InputContext): Promise<PolicyDecision> | PolicyDecision;
+}
+
+export interface ToolCallPolicy {
+  readonly id: string;
+  evaluate(context: ToolCallContext): Promise<PolicyDecision> | PolicyDecision;
+}
+
+export interface OutputPolicy {
+  readonly id: string;
+  evaluate(context: OutputContext): Promise<PolicyDecision> | PolicyDecision;
+}

package/src/core/types.ts

@@ -0,0 +1,93 @@
+// ─── Shared ──────────────────────────────────────────────────────────────────
+
+export type MessageRole = "system" | "user" | "assistant";
+
+export interface Message {
+  role: MessageRole;
+  content: string;
+}
+
+export interface Metadata {
+  agent_id: string;
+  session_id: string;
+  timestamp: string;
+  [key: string]: unknown;
+}
+
+// ─── Interception Contexts ────────────────────────────────────────────────────
+
+export interface InputContext {
+  messages: Message[];
+  metadata: Metadata;
+}
+
+export interface ToolCallContext {
+  tool_name: string;
+  arguments: Record<string, unknown>;
+  calling_message: Message & { role: "assistant" };
+  metadata: Metadata;
+}
+
+export interface OutputContext {
+  response: Message & { role: "assistant" };
+  metadata: Metadata;
+}
+
+// ─── Policy Decisions ─────────────────────────────────────────────────────────
+
+export interface AllowDecision {
+  decision: "allow";
+}
+
+export interface DenyDecision {
+  decision: "deny";
+  reason?: string;
+  policy_id?: string;
+}
+
+export interface RedactDecision {
+  decision: "redact";
+  redactions: Redaction[];
+}
+
+export interface TransformDecision {
+  decision: "transform";
+  transformation: Transformation;
+}
+
+export interface AuditDecision {
+  decision: "audit";
+  reason?: string;
+}
+
+export type PolicyDecision =
+  | AllowDecision
+  | DenyDecision
+  | RedactDecision
+  | TransformDecision
+  | AuditDecision;
+
+// ─── Redaction ────────────────────────────────────────────────────────────────
+
+export type RedactionStrategy = "mask" | "remove" | "replace";
+
+export interface Redaction {
+  field: string;
+  strategy: RedactionStrategy;
+  replacement?: string;
+  pattern?: string;
+}
+
+// ─── Transformation ───────────────────────────────────────────────────────────
+
+export type TransformOp = "set" | "prepend" | "append";
+
+export interface TransformOperation {
+  op: TransformOp;
+  field: string;
+  value: unknown;
+}
+
+export interface Transformation {
+  operations: TransformOperation[];
+}