@agentium/harness 4.0.0

package/dist/watch/types.d.ts

@@ -0,0 +1,147 @@
+import type { DurableActionConnector, DurableJSON, DurableTaskStore } from "@agentium/core";
+export interface WatchIdentity {
+    tenantId: string;
+    actorId: string;
+}
+export interface WatchQuietHours {
+    start: string;
+    end: string;
+}
+export interface WatchLimits {
+    maxOperations: number;
+    maxWakes: number;
+    maxEventsPerWake: number;
+    maxPagesPerWake: number;
+    maxResyncEvents: number;
+    maxPendingEvents: number;
+    maxDecisions: number;
+    maxOutbox: number;
+    maxEventBytes: number;
+    maxStateBytes: number;
+    maxNotificationsPerDay: number;
+}
+export interface WatchDefinition {
+    id: string;
+    version: number;
+    identity: WatchIdentity;
+    sourceId: string;
+    sourceScope: string;
+    destination: string;
+    channel: string;
+    policyRevision: number;
+    grantRefs: string[];
+    timeZone: string;
+    quietHours?: WatchQuietHours;
+    pollIntervalMs: number;
+    renewalIntervalMs: number;
+    cooldownMs: number;
+    limits: WatchLimits;
+}
+export type WatchDefinitionInput = Omit<WatchDefinition, "limits" | "pollIntervalMs" | "renewalIntervalMs" | "cooldownMs"> & {
+    limits?: Partial<WatchLimits>;
+    pollIntervalMs?: number;
+    renewalIntervalMs?: number;
+    cooldownMs?: number;
+};
+export interface WatchEvent {
+    id: string;
+    occurredAt: number;
+    data: DurableJSON;
+}
+export interface WatchSubscription {
+    reference: string;
+    expiresAt: number;
+}
+export interface WatchSourceBatch {
+    cursor: string;
+    events: WatchEvent[];
+    resynced: boolean;
+}
+export interface VerifiedWatchTrigger extends WatchIdentity {
+    sourceId: string;
+    sourceScope: string;
+    eventId: string;
+    cursor: string;
+}
+/** A scoped, host-owned source. Implementations must honor read bounds before returning a cursor. */
+export interface WatchSource {
+    id: string;
+    scope: string;
+    capabilities: {
+        idempotentActivation: true;
+        polling: true;
+        push: boolean;
+    };
+    baseline(signal: AbortSignal): Promise<string>;
+    activate(key: string, signal: AbortSignal): Promise<WatchSubscription>;
+    stop(subscription: WatchSubscription | null, signal: AbortSignal): Promise<void>;
+    read(cursor: string, limits: Pick<WatchLimits, "maxEventsPerWake" | "maxPagesPerWake" | "maxResyncEvents">, signal: AbortSignal): Promise<WatchSourceBatch>;
+    compareCursors(left: string, right: string): number;
+    /** Verify signature/audience and authenticated mailbox ownership before returning a trusted hint. */
+    verifyTrigger?(raw: unknown): Promise<VerifiedWatchTrigger>;
+}
+export type WatchScheduleKind = "poll" | "renew" | "flush";
+export interface WatchSchedule {
+    key: string;
+    identity: WatchIdentity;
+    watchId: string;
+    configVersion: number;
+    kind: WatchScheduleKind;
+    at: number;
+}
+export interface WatchScheduler {
+    capabilities: {
+        durable: boolean;
+        idempotentUpsert: true;
+    };
+    schedule(job: WatchSchedule): Promise<void>;
+    cancel(key: string): Promise<void>;
+}
+export type WatchOperation = "activate" | "update" | "pause" | "resume" | "delete" | "trigger" | "poll" | "renew" | "flush" | "reconcile" | "inspect";
+export interface WatchAuthorization {
+    operation: WatchOperation;
+    definition: Readonly<WatchDefinition>;
+    /** Notification count includes digests; authorization must validate destination/channel and amount. */
+    notifications: number;
+    events: number;
+}
+export interface WatchServices {
+    store: DurableTaskStore;
+    source: WatchSource;
+    scheduler: WatchScheduler;
+    notifications: DurableActionConnector & {
+        channel: string;
+        destination: string;
+    };
+    /** Trusted host authority, including exclusive ownership of a source mailbox where required. */
+    authorize(request: WatchAuthorization): Promise<boolean>;
+    /** Deterministic local classification only; no model/network work in this callback. */
+    filter?(event: Readonly<WatchEvent>): boolean;
+    leaseMs?: number;
+    requireDurability?: boolean;
+}
+export interface WatchOutbox {
+    id: string;
+    eventIds: string[];
+    events: WatchEvent[];
+    state: "pending" | "confirmed";
+    reservedDay: string | null;
+    resultRef: string | null;
+}
+export interface WatchState {
+    status: "inactive" | "activating" | "active" | "paused" | "deleted";
+    cursor: string | null;
+    subscription: WatchSubscription | null;
+    wakes: number;
+    decisions: Record<string, {
+        id: string;
+        decision: "pending" | "ignored" | "resync" | "outbox";
+        at: number;
+    }>;
+    pending: WatchEvent[];
+    outbox: Record<string, WatchOutbox>;
+    daily: Record<string, number>;
+    cooldownUntil: number;
+    schedules: Partial<Record<WatchScheduleKind, number>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/watch/types.d.ts.map

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

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@agentium/harness",
+  "version": "4.0.0",
+  "description": "Composable harness developer kit for Agentium tools, context, middleware and presets",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentiumOS/agentium.git",
+    "directory": "packages/harness"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "harness",
+    "tools",
+    "context",
+    "middleware"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown --config ../../tsdown.config.ts && tsc -p tsconfig.build.json --emitDeclarationOnly --declaration --pretty false",
+    "dev": "tsdown --config ../../tsdown.config.ts --watch",
+    "prepublishOnly": "npm run build",
+    "test:package": "cd ../.. && AGENTIUM_TEST_PACKAGES=1 vitest run packages/harness/src/__tests__/package-consumption.test.ts"
+  },
+  "peerDependencies": {
+    "@agentium/core": "^4.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.1",
+    "typescript": "^5.6.0",
+    "tsdown": "0.23.0"
+  },
+  "homepage": "https://agentium.in",
+  "bugs": {
+    "url": "https://github.com/agentiumOS/agentium/issues"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": "^22.18.0 || ^24.11.0"
+  }
+}