@alveus-ai/std 0.1.0

package/dist/patterns/approval.js

@@ -0,0 +1,183 @@
+/**
+ * Approval Pattern - Human-in-the-Loop Workflows
+ *
+ * Provides utilities for implementing approval workflows where
+ * agents can pause and wait for human decisions.
+ *
+ * Uses the Event capability for durable waiting:
+ * 1. Emit an "approval-needed" event with request details
+ * 2. Wait for an "approval-response" event
+ * 3. Continue based on the approval decision
+ *
+ * @example
+ * ```ts
+ * import { waitForApproval, type ApprovalRequest } from '@alveus-ai/std/patterns';
+ *
+ * const myAgent = agent$(async (state, event, ctx) => {
+ *   // Do some work...
+ *   const result = await performRiskyOperation();
+ *
+ *   // Request human approval before continuing
+ *   const approval = await waitForApproval(ctx, {
+ *     action: 'deploy-to-production',
+ *     details: { version: '1.2.3', environment: 'prod' },
+ *     message: 'Please approve deployment to production',
+ *   });
+ *
+ *   if (!approval.approved) {
+ *     return { status: 'rejected', reason: approval.reason };
+ *   }
+ *
+ *   // Continue with deployment...
+ *   return { status: 'deployed', approvedBy: approval.approvedBy };
+ * });
+ * ```
+ */
+/**
+ * Topics used for approval events
+ */
+export const ApprovalTopics = {
+    /** Topic for approval requests */
+    NEEDED: 'approval.needed',
+    /** Topic for approval responses */
+    RESPONSE: 'approval.response',
+};
+/**
+ * Wait for human approval
+ *
+ * Emits an approval request event and durably waits for a response.
+ * The workflow will pause until an approval response is received.
+ *
+ * @param ctx - The execution context
+ * @param request - The approval request details
+ * @returns The approval response
+ * @throws Error if timeout is reached
+ */
+export async function waitForApproval(ctx, request) {
+    const timeoutMs = request.timeoutMs ?? 24 * 60 * 60 * 1000; // 24 hours default
+    // Emit the approval request
+    await ctx.events.emit(ApprovalTopics.NEEDED, {
+        workflowId: ctx.workflowId,
+        action: request.action,
+        details: request.details,
+        message: request.message,
+        requestedAt: Date.now(),
+    });
+    // Wait for the approval response (durable via Temporal Signals)
+    const response = await ctx.events.waitFor(`${ApprovalTopics.RESPONSE}:${ctx.workflowId}`, timeoutMs);
+    return {
+        approved: response.data?.approved === true,
+        approvedBy: response.data?.approvedBy,
+        reason: response.data?.reason,
+        timestamp: response.timestamp,
+    };
+}
+/**
+ * Send an approval decision
+ *
+ * Use this from an approval UI or API to respond to an approval request.
+ * The response will be delivered to the waiting workflow via the Event Bridge.
+ *
+ * @param ctx - The execution context
+ * @param workflowId - The ID of the workflow waiting for approval
+ * @param approved - Whether to approve or reject
+ * @param options - Additional response options
+ */
+export async function sendApproval(ctx, workflowId, approved, options = {}) {
+    await ctx.events.emit(`${ApprovalTopics.RESPONSE}:${workflowId}`, {
+        approved,
+        approvedBy: options.approvedBy,
+        reason: options.reason,
+        respondedAt: Date.now(),
+    });
+}
+/**
+ * Create an approval-gated operation wrapper
+ *
+ * Wraps an async operation with an approval requirement.
+ * The operation will only execute if approval is granted.
+ *
+ * @param operation - The operation requiring approval
+ * @param getRequest - Function to build the approval request from the input
+ * @returns A function that requests approval before executing
+ *
+ * @example
+ * ```ts
+ * const safeDelete = requireApproval(
+ *   async (ctx, userId: string) => {
+ *     await database.deleteUser(userId);
+ *     return { deleted: userId };
+ *   },
+ *   (userId) => ({
+ *     action: 'delete-user',
+ *     details: { userId },
+ *     message: `Delete user ${userId}?`,
+ *   })
+ * );
+ *
+ * // In agent handler:
+ * const result = await safeDelete(ctx, 'user-123');
+ * if (!result.approved) {
+ *   return { error: 'Deletion rejected' };
+ * }
+ * return result.result;
+ * ```
+ */
+export function requireApproval(operation, getRequest) {
+    return async (ctx, input) => {
+        const request = getRequest(input);
+        const approval = await waitForApproval(ctx, request);
+        if (!approval.approved) {
+            return {
+                approved: false,
+                reason: approval.reason,
+            };
+        }
+        const result = await operation(ctx, input);
+        return {
+            approved: true,
+            result,
+            approvedBy: approval.approvedBy,
+        };
+    };
+}
+/**
+ * Multi-step approval chain
+ *
+ * Requires multiple approvals before proceeding.
+ * Useful for critical operations requiring sign-off from multiple parties.
+ *
+ * @param ctx - The execution context
+ * @param request - The base approval request
+ * @param approvers - List of required approver identifiers
+ * @returns Array of approval responses
+ */
+export async function waitForMultipleApprovals(ctx, request, approvers) {
+    const responses = [];
+    for (const approver of approvers) {
+        // Emit request for this specific approver
+        await ctx.events.emit(ApprovalTopics.NEEDED, {
+            workflowId: ctx.workflowId,
+            action: request.action,
+            details: request.details,
+            message: `${request.message} (Approval ${responses.length + 1}/${approvers.length} from: ${approver})`,
+            requiredApprover: approver,
+            requestedAt: Date.now(),
+        });
+        // Wait for this approver's response
+        const response = await ctx.events.waitFor(`${ApprovalTopics.RESPONSE}:${ctx.workflowId}:${approver}`, request.timeoutMs);
+        const approval = {
+            approved: response.data?.approved === true,
+            approvedBy: response.data?.approvedBy || approver,
+            reason: response.data?.reason,
+            timestamp: response.timestamp,
+        };
+        responses.push(approval);
+        // If any approver rejects, return early
+        if (!approval.approved) {
+            return responses;
+        }
+    }
+    return responses;
+}
+//# sourceMappingURL=approval.js.map

package/dist/patterns/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../src/patterns/approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAsCH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,kCAAkC;IAClC,MAAM,EAAE,iBAAiB;IAEzB,mCAAmC;IACnC,QAAQ,EAAE,mBAAmB;CACrB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAqB,EACrB,OAAwB;IAExB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,mBAAmB;IAE/E,4BAA4B;IAC5B,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE;QAC3C,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;KACxB,CAAC,CAAC;IAEH,gEAAgE;IAChE,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,CACvC,GAAG,cAAc,CAAC,QAAQ,IAAI,GAAG,CAAC,UAAU,EAAE,EAC9C,SAAS,CACV,CAAC;IAEF,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI;QAC1C,UAAU,EAAE,QAAQ,CAAC,IAAI,EAAE,UAAU;QACrC,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM;QAC7B,SAAS,EAAE,QAAQ,CAAC,SAAS;KAC9B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAqB,EACrB,UAAkB,EAClB,QAAiB,EACjB,UAGI,EAAE;IAEN,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,QAAQ,IAAI,UAAU,EAAE,EAAE;QAChE,QAAQ;QACR,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;KACxB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAqE,EACrE,UAA8C;IAO9C,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QAC1B,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAErD,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACvB,OAAO;gBACL,QAAQ,EAAE,KAAK;gBACf,MAAM,EAAE,QAAQ,CAAC,MAAM;aACxB,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC3C,OAAO;YACL,QAAQ,EAAE,IAAI;YACd,MAAM;YACN,UAAU,EAAE,QAAQ,CAAC,UAAU;SAChC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,GAAqB,EACrB,OAAwB,EACxB,SAAmB;IAEnB,MAAM,SAAS,GAAuB,EAAE,CAAC;IAEzC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,0CAA0C;QAC1C,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE;YAC3C,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,cAAc,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,CAAC,MAAM,UAAU,QAAQ,GAAG;YACtG,gBAAgB,EAAE,QAAQ;YAC1B,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;SACxB,CAAC,CAAC;QAEH,oCAAoC;QACpC,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,CACvC,GAAG,cAAc,CAAC,QAAQ,IAAI,GAAG,CAAC,UAAU,IAAI,QAAQ,EAAE,EAC1D,OAAO,CAAC,SAAS,CAClB,CAAC;QAEF,MAAM,QAAQ,GAAqB;YACjC,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI;YAC1C,UAAU,EAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,IAAI,QAAQ;YACjD,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM;YAC7B,SAAS,EAAE,QAAQ,CAAC,SAAS;SAC9B,CAAC;QAEF,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAEzB,wCAAwC;QACxC,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/patterns/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Standard Patterns
+ *
+ * Common workflow patterns for agent development.
+ */
+export { waitForApproval, sendApproval, requireApproval, waitForMultipleApprovals, ApprovalTopics, type ApprovalRequest, type ApprovalResponse, } from './approval.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/patterns/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,YAAY,EACZ,eAAe,EACf,wBAAwB,EACxB,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC"}

package/dist/patterns/index.js

@@ -0,0 +1,7 @@
+/**
+ * Standard Patterns
+ *
+ * Common workflow patterns for agent development.
+ */
+export { waitForApproval, sendApproval, requireApproval, waitForMultipleApprovals, ApprovalTopics, } from './approval.js';
+//# sourceMappingURL=index.js.map

package/dist/patterns/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,YAAY,EACZ,eAAe,EACf,wBAAwB,EACxB,cAAc,GAGf,MAAM,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@alveus-ai/std",
+  "version": "0.1.0",
+  "description": "Standard library of reusable agents and utilities for Alveus",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./agents": {
+      "types": "./dist/agents/index.d.ts",
+      "import": "./dist/agents/index.js"
+    },
+    "./memory": {
+      "types": "./dist/memory/index.d.ts",
+      "import": "./dist/memory/index.js"
+    },
+    "./patterns": {
+      "types": "./dist/patterns/index.d.ts",
+      "import": "./dist/patterns/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist .alveus"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@alveus-ai/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@alveus-ai/core": "workspace:*",
+    "typescript": "^5.3.0"
+  }
+}