@spekra.in/agent-os 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/Booker/README.md +41 -0
  2. package/Booker/package.json +11 -0
  3. package/Booker/src/agent.js +15 -0
  4. package/Booker/src/calendar-adapter.js +75 -0
  5. package/Booker/src/index.js +4 -0
  6. package/Booker/src/intake-parser.js +96 -0
  7. package/Booker/src/validation.js +34 -0
  8. package/Booker/test/booker.test.js +35 -0
  9. package/CashHound/README.md +181 -0
  10. package/CashHound/package.json +21 -0
  11. package/CashHound/src/agent.js +621 -0
  12. package/CashHound/src/bank-reconciler.js +66 -0
  13. package/CashHound/src/dunning.js +380 -0
  14. package/CashHound/src/index.js +32 -0
  15. package/CashHound/src/invoice.js +371 -0
  16. package/CashHound/src/mobile.js +35 -0
  17. package/CashHound/src/npv-optimizer.js +259 -0
  18. package/CashHound/test/advanced.test.js +44 -0
  19. package/CashHound/test/cashhound.test.js +530 -0
  20. package/CashHound/test/mobile.test.js +25 -0
  21. package/CashHound/test/security.test.js +35 -0
  22. package/Clerk/README.md +30 -0
  23. package/Clerk/package.json +11 -0
  24. package/Clerk/src/agent.js +18 -0
  25. package/Clerk/src/index.js +2 -0
  26. package/Clerk/src/reconciliation.js +52 -0
  27. package/Clerk/test/clerk.test.js +39 -0
  28. package/LocalRoar/README.md +37 -0
  29. package/LocalRoar/package.json +13 -0
  30. package/LocalRoar/src/agent.js +70 -0
  31. package/LocalRoar/src/booking-router.js +74 -0
  32. package/LocalRoar/src/feedback-interceptor.js +47 -0
  33. package/LocalRoar/src/index.js +7 -0
  34. package/LocalRoar/src/lead-engine.js +52 -0
  35. package/LocalRoar/src/mobile.js +23 -0
  36. package/LocalRoar/src/review-booster.js +24 -0
  37. package/LocalRoar/src/route-density.js +46 -0
  38. package/LocalRoar/test/advanced.test.js +41 -0
  39. package/LocalRoar/test/localroar.test.js +59 -0
  40. package/LocalRoar/test/mobile.test.js +12 -0
  41. package/OmniLife/README.md +39 -0
  42. package/OmniLife/package.json +13 -0
  43. package/OmniLife/src/agent.js +47 -0
  44. package/OmniLife/src/bill-negotiator.js +43 -0
  45. package/OmniLife/src/browser-cancel.js +28 -0
  46. package/OmniLife/src/conflict-engine.js +49 -0
  47. package/OmniLife/src/index.js +6 -0
  48. package/OmniLife/src/mobile.js +18 -0
  49. package/OmniLife/src/subscription-manager.js +66 -0
  50. package/OmniLife/test/advanced.test.js +29 -0
  51. package/OmniLife/test/mobile.test.js +12 -0
  52. package/OmniLife/test/omnilife.test.js +71 -0
  53. package/PulseMD/README.md +42 -0
  54. package/PulseMD/package.json +13 -0
  55. package/PulseMD/src/agent.js +67 -0
  56. package/PulseMD/src/ambient-scribe.js +46 -0
  57. package/PulseMD/src/auth.js +63 -0
  58. package/PulseMD/src/charting.js +54 -0
  59. package/PulseMD/src/index.js +7 -0
  60. package/PulseMD/src/mobile.js +18 -0
  61. package/PulseMD/src/prior-auth.js +39 -0
  62. package/PulseMD/src/safety-guard.js +88 -0
  63. package/PulseMD/test/advanced.test.js +50 -0
  64. package/PulseMD/test/mobile.test.js +12 -0
  65. package/PulseMD/test/pulsemd.test.js +71 -0
  66. package/README.md +203 -2
  67. package/ResolveX/README.md +274 -0
  68. package/ResolveX/package.json +20 -0
  69. package/ResolveX/src/agent.js +679 -0
  70. package/ResolveX/src/carrier-listener.js +405 -0
  71. package/ResolveX/src/diagnosis.js +315 -0
  72. package/ResolveX/src/index.js +36 -0
  73. package/ResolveX/src/mobile.js +31 -0
  74. package/ResolveX/src/policy.js +325 -0
  75. package/ResolveX/src/vision.js +384 -0
  76. package/ResolveX/test/advanced.test.js +445 -0
  77. package/ResolveX/test/mobile.test.js +15 -0
  78. package/ResolveX/test/resolvex.test.js +428 -0
  79. package/SentinelMesh/README.md +51 -0
  80. package/SentinelMesh/package.json +13 -0
  81. package/SentinelMesh/src/governor.js +61 -0
  82. package/SentinelMesh/src/index.js +4 -0
  83. package/SentinelMesh/src/mobile.js +19 -0
  84. package/SentinelMesh/src/policy.js +63 -0
  85. package/SentinelMesh/src/sandbox.js +152 -0
  86. package/SentinelMesh/test/mobile.test.js +12 -0
  87. package/SentinelMesh/test/sentinel.test.js +135 -0
  88. package/Sidekick/README.md +43 -0
  89. package/Sidekick/package.json +11 -0
  90. package/Sidekick/src/agent.js +15 -0
  91. package/Sidekick/src/evidence.js +45 -0
  92. package/Sidekick/src/index.js +3 -0
  93. package/Sidekick/src/validation.js +15 -0
  94. package/Sidekick/test/sidekick.test.js +33 -0
  95. package/agent-os-mobile/README.md +26 -0
  96. package/agent-os-mobile/src/api.js +97 -0
  97. package/agent-os-mobile/src/biometric.js +41 -0
  98. package/agent-os-mobile/src/components/ApprovalStack.js +207 -0
  99. package/agent-os-mobile/src/components/OutcomeCard.js +98 -0
  100. package/agent-os-mobile/src/memory-graph.js +114 -0
  101. package/agent-os-mobile/src/screens/CashHoundMobileScreen.js +111 -0
  102. package/agent-os-mobile/src/screens/LocalRoarMobileScreen.js +183 -0
  103. package/agent-os-mobile/src/screens/OmniLifeMobileScreen.js +111 -0
  104. package/agent-os-mobile/src/screens/PulseMDMobileScreen.js +55 -0
  105. package/agent-os-mobile/src/screens/ResolveXMobileScreen.js +96 -0
  106. package/agent-os-mobile/src/screens/SentinelMeshMobileScreen.js +199 -0
  107. package/agent-os-mobile/src/self-healer.js +104 -0
  108. package/agent-os-mobile/src/speculative-verifier.js +69 -0
  109. package/agent-os-mobile/src/spekra-bridge.js +216 -0
  110. package/agent-os-mobile/src/swarm.js +72 -0
  111. package/agent-os-mobile/src/voice.js +51 -0
  112. package/bin/agentos.js +260 -0
  113. package/package.json +51 -4
  114. package/src/index.js +91 -0
@@ -0,0 +1,405 @@
1
+ /**
2
+ * ResolveX Carrier Webhook Listener & Proactive Resolution Engine
3
+ * Ingests real-time carrier tracking webhooks (FedEx, UPS, DHL),
4
+ * identifies transit exceptions (weather, stall >= 48h, customs hold),
5
+ * and pre-emptively dispatches priority traces and apology loyalty credits
6
+ * before the customer ever encounters a delivery failure or files a support ticket.
7
+ */
8
+
9
+ export const CarrierExceptionType = Object.freeze({
10
+ WEATHER_EXCEPTION: 'WEATHER_EXCEPTION',
11
+ TRANSIT_STALL_48H: 'TRANSIT_STALL_48H',
12
+ CUSTOMS_HOLD: 'CUSTOMS_HOLD',
13
+ });
14
+
15
+ const DEFAULT_BASE_CREDITS = Object.freeze({
16
+ [CarrierExceptionType.WEATHER_EXCEPTION]: 15.0,
17
+ [CarrierExceptionType.TRANSIT_STALL_48H]: 25.0,
18
+ [CarrierExceptionType.CUSTOMS_HOLD]: 30.0,
19
+ });
20
+
21
+ const TIER_MULTIPLIERS = Object.freeze({
22
+ STANDARD: 1.0,
23
+ BRONZE: 1.1,
24
+ SILVER: 1.25,
25
+ GOLD: 1.5,
26
+ PLATINUM: 2.0,
27
+ });
28
+
29
+ let traceCounter = 1;
30
+ function generateTraceId(carrier = 'CARRIER') {
31
+ const ts = Date.now().toString(36).toUpperCase();
32
+ const seq = (traceCounter++).toString().padStart(4, '0');
33
+ return `TRACE-${carrier.toUpperCase()}-${ts}-${seq}`;
34
+ }
35
+
36
+ let incidentCounter = 1;
37
+ function generateProactiveIncidentId() {
38
+ const ts = Date.now().toString(36).toUpperCase();
39
+ const seq = (incidentCounter++).toString().padStart(4, '0');
40
+ return `PROACTIVE-${ts}-${seq}`;
41
+ }
42
+
43
+ export class CarrierWebhookListener {
44
+ /**
45
+ * @param {Object} options
46
+ * @param {Object} [options.agent] - Optional ResolveXAgent instance
47
+ * @param {Object} [options.policyEngine] - Optional PolicyEngine instance
48
+ * @param {Object} [options.baseCredits] - Custom base credits by exception type
49
+ * @param {Function} [options.onProactiveDispatch] - Custom callback when proactive action fires
50
+ */
51
+ constructor(options = {}) {
52
+ this.agent = options.agent || null;
53
+ this.policyEngine = options.policyEngine || null;
54
+ this.baseCredits = { ...DEFAULT_BASE_CREDITS, ...(options.baseCredits || {}) };
55
+ this.onProactiveDispatch = options.onProactiveDispatch || null;
56
+
57
+ // Idempotency cache: Set of `${carrier}:${trackingNumber}:${exceptionType}`
58
+ this.processedExceptions = new Map();
59
+ // Audit & telemetry logs
60
+ this.webhookLog = [];
61
+ this.dispatchedActions = [];
62
+ this.proactiveIncidents = [];
63
+ }
64
+
65
+ /**
66
+ * Ingests a raw webhook event from FedEx, UPS, or DHL.
67
+ * Detects exceptions and executes proactive resolution if warranted.
68
+ * @param {Object} rawPayload - Webhook payload from carrier
69
+ * @returns {Object} Ingestion and proactive resolution outcome
70
+ */
71
+ ingestWebhook(rawPayload = {}) {
72
+ const event = this._normalizePayload(rawPayload);
73
+ this.webhookLog.push({
74
+ receivedAt: new Date().toISOString(),
75
+ raw: rawPayload,
76
+ normalized: event,
77
+ });
78
+
79
+ // Check if exception detected
80
+ const detection = this.detectException(event);
81
+ if (!detection.detected) {
82
+ return {
83
+ status: 'IGNORED_NO_EXCEPTION',
84
+ carrier: event.carrier,
85
+ trackingNumber: event.trackingNumber,
86
+ exceptionDetected: false,
87
+ proactiveActionTaken: false,
88
+ message: 'Normal transit event processed; no exception detected.',
89
+ };
90
+ }
91
+
92
+ const { exceptionType, details } = detection;
93
+ const idempotencyKey = `${event.carrier}:${event.trackingNumber}:${exceptionType}`;
94
+
95
+ // Check if we already took proactive action for this exception on this tracking number
96
+ if (this.processedExceptions.has(idempotencyKey)) {
97
+ return {
98
+ status: 'DUPLICATE_SUPPRESSED',
99
+ carrier: event.carrier,
100
+ trackingNumber: event.trackingNumber,
101
+ exceptionDetected: true,
102
+ exceptionType,
103
+ proactiveActionTaken: false,
104
+ message: `Proactive action was already dispatched for ${exceptionType} on tracking ${event.trackingNumber}.`,
105
+ };
106
+ }
107
+
108
+ // Execute proactive remediation before customer files a ticket
109
+ const proactiveResult = this.dispatchProactiveRemediation({
110
+ carrier: event.carrier,
111
+ trackingNumber: event.trackingNumber,
112
+ customerId: event.customerId,
113
+ orderId: event.orderId,
114
+ customerTier: event.customerTier,
115
+ exceptionType,
116
+ details,
117
+ });
118
+
119
+ this.processedExceptions.set(idempotencyKey, {
120
+ dispatchedAt: Date.now(),
121
+ incidentId: proactiveResult.proactiveIncident.id,
122
+ });
123
+
124
+ return proactiveResult;
125
+ }
126
+
127
+ /**
128
+ * Detects if an event qualifies as WEATHER_EXCEPTION, TRANSIT_STALL_48H, or CUSTOMS_HOLD.
129
+ * @param {Object} event - Normalized event
130
+ * @returns {Object} Detection result
131
+ */
132
+ detectException(event = {}) {
133
+ const textBlob = [
134
+ event.eventCode,
135
+ event.eventType,
136
+ event.status,
137
+ event.statusDescription,
138
+ event.details,
139
+ event.remarks,
140
+ ].filter(Boolean).join(' ').toLowerCase();
141
+
142
+ // 1. WEATHER_EXCEPTION detection
143
+ const isWeatherCode = [
144
+ 'WEATHER_EXCEPTION',
145
+ 'WEATHER_DELAY',
146
+ 'SEVERE_WEATHER',
147
+ 'NATURAL_DISASTER',
148
+ 'ACT_OF_GOD',
149
+ 'SNOW_STORM_DELAY',
150
+ ].includes(event.eventCode?.toUpperCase()) || [
151
+ 'WEATHER_EXCEPTION',
152
+ 'WEATHER_DELAY',
153
+ ].includes(event.eventType?.toUpperCase());
154
+
155
+ const isWeatherText = /weather|snow|blizzard|typhoon|hurricane|storm|tornado|flood|cyclone|freeze/i.test(textBlob);
156
+
157
+ if (isWeatherCode || isWeatherText) {
158
+ return {
159
+ detected: true,
160
+ exceptionType: CarrierExceptionType.WEATHER_EXCEPTION,
161
+ confidence: 0.95,
162
+ details: event.details || event.statusDescription || 'Severe weather transit disruption detected',
163
+ };
164
+ }
165
+
166
+ // 2. TRANSIT_STALL_48H detection
167
+ const isStallCode = [
168
+ 'TRANSIT_STALL_48H',
169
+ 'TRANSIT_STALL',
170
+ 'STALL_48H',
171
+ 'STATIONARY_DELAY',
172
+ 'NO_MOVEMENT_48H',
173
+ ].includes(event.eventCode?.toUpperCase()) || [
174
+ 'TRANSIT_STALL_48H',
175
+ 'TRANSIT_STALL',
176
+ ].includes(event.eventType?.toUpperCase());
177
+
178
+ const stallHours = event.stallHours || event.hoursStalled || event.hoursSinceLastScan || 0;
179
+ const hasStallTimestamp = this._calculateStallHours(event) >= 48;
180
+ const isStallText = /transit.*stall|stall.*48|no movement.*48|stuck in transit.*(48|two days|2 days)/i.test(textBlob);
181
+
182
+ if (isStallCode || stallHours >= 48 || hasStallTimestamp || isStallText) {
183
+ return {
184
+ detected: true,
185
+ exceptionType: CarrierExceptionType.TRANSIT_STALL_48H,
186
+ confidence: 0.95,
187
+ stallHours: Math.max(stallHours, hasStallTimestamp ? this._calculateStallHours(event) : 48),
188
+ details: event.details || event.statusDescription || `Shipment stationary for over 48 hours without hub progression`,
189
+ };
190
+ }
191
+
192
+ // 3. CUSTOMS_HOLD detection
193
+ const isCustomsCode = [
194
+ 'CUSTOMS_HOLD',
195
+ 'CUSTOMS_CLEARANCE_DELAY',
196
+ 'REGULATORY_HOLD',
197
+ 'BORDER_INSPECTION',
198
+ 'IMPORT_CUSTOMS_DELAY',
199
+ ].includes(event.eventCode?.toUpperCase()) || [
200
+ 'CUSTOMS_HOLD',
201
+ 'CUSTOMS_CLEARANCE_DELAY',
202
+ ].includes(event.eventType?.toUpperCase());
203
+
204
+ const isCustomsText = /customs.*(hold|delay|inspect|clearance|duty|doc)|border.*(hold|inspect)/i.test(textBlob);
205
+
206
+ if (isCustomsCode || isCustomsText) {
207
+ return {
208
+ detected: true,
209
+ exceptionType: CarrierExceptionType.CUSTOMS_HOLD,
210
+ confidence: 0.95,
211
+ details: event.details || event.statusDescription || 'Shipment held at customs / regulatory border clearance',
212
+ };
213
+ }
214
+
215
+ return {
216
+ detected: false,
217
+ exceptionType: null,
218
+ confidence: 0,
219
+ details: null,
220
+ };
221
+ }
222
+
223
+ /**
224
+ * Proactively dispatches priority trace and loyalty apology credit.
225
+ */
226
+ dispatchProactiveRemediation({
227
+ carrier,
228
+ trackingNumber,
229
+ customerId = 'CUST-PROACTIVE',
230
+ orderId = null,
231
+ customerTier = 'STANDARD',
232
+ exceptionType,
233
+ details,
234
+ }) {
235
+ const proactiveTicketId = generateProactiveIncidentId();
236
+ const traceId = generateTraceId(carrier);
237
+
238
+ // Compute loyalty credit with tier multiplier
239
+ const baseCredit = this.baseCredits[exceptionType] || 20.0;
240
+ const tierMultiplier = TIER_MULTIPLIERS[customerTier.toUpperCase()] || 1.0;
241
+ const creditAmount = Number((baseCredit * tierMultiplier).toFixed(2));
242
+
243
+ // 1. Priority Carrier Trace Action
244
+ const traceAction = {
245
+ actionType: 'PRIORITY_CARRIER_TRACE',
246
+ carrier: carrier.toUpperCase(),
247
+ trackingNumber,
248
+ priority: 'EXPEDITED_CRITICAL',
249
+ traceTicketId: traceId,
250
+ dispatchedAt: new Date().toISOString(),
251
+ status: 'DISPATCHED',
252
+ details: `Priority escalation inquiry filed with ${carrier} due to ${exceptionType}: ${details}`,
253
+ };
254
+
255
+ // 2. Proactive Apology Loyalty Credit Action
256
+ const creditAction = {
257
+ actionType: 'PROACTIVE_LOYALTY_CREDIT',
258
+ customerId,
259
+ amount: creditAmount,
260
+ currency: 'USD',
261
+ customerTier,
262
+ reason: `Proactive apology credit for ${exceptionType} delay`,
263
+ creditReference: `CRED-${Date.now().toString(36).toUpperCase()}`,
264
+ dispatchedAt: new Date().toISOString(),
265
+ status: 'ISSUED',
266
+ breakdown: {
267
+ baseCredit,
268
+ tierMultiplier,
269
+ finalCredit: creditAmount,
270
+ },
271
+ };
272
+
273
+ // 3. Proactive Customer Incident Record
274
+ const proactiveIncident = {
275
+ id: proactiveTicketId,
276
+ carrier: carrier.toUpperCase(),
277
+ trackingNumber,
278
+ customerId,
279
+ orderId,
280
+ exceptionType,
281
+ beforeCustomerTicketFiled: true,
282
+ createdAt: new Date().toISOString(),
283
+ actionsDispatched: [traceAction, creditAction],
284
+ customerNotification: {
285
+ channel: 'SMS_AND_EMAIL',
286
+ subject: `Proactive Update: We're taking care of your ${carrier} shipment`,
287
+ message: `We noticed an unexpected ${exceptionType} with your shipment (${trackingNumber}). Before you needed to reach out, we've already opened an expedited priority trace with ${carrier} and credited $${creditAmount.toFixed(2)} to your account as an apology.`,
288
+ },
289
+ };
290
+
291
+ this.dispatchedActions.push(traceAction, creditAction);
292
+ this.proactiveIncidents.push(proactiveIncident);
293
+
294
+ // If external listener/callback registered, trigger it
295
+ if (typeof this.onProactiveDispatch === 'function') {
296
+ try {
297
+ this.onProactiveDispatch(proactiveIncident);
298
+ } catch (err) {
299
+ // preserve execution
300
+ }
301
+ }
302
+
303
+ return {
304
+ status: 'PROACTIVE_RESOLUTION_DISPATCHED',
305
+ proactiveActionTaken: true,
306
+ exceptionDetected: true,
307
+ exceptionType,
308
+ trackingNumber,
309
+ carrier: carrier.toUpperCase(),
310
+ customerId,
311
+ dispatchedActions: [traceAction, creditAction],
312
+ proactiveIncident,
313
+ };
314
+ }
315
+
316
+ _normalizePayload(payload = {}) {
317
+ // Carrier identification
318
+ const rawCarrier = payload.carrier || payload.shippingCarrier || payload.carrierCode ||
319
+ (payload.trackingNumber?.startsWith('1Z') ? 'UPS' :
320
+ payload.trackingNumber?.startsWith('FX') ? 'FEDEX' :
321
+ payload.shipmentTrackingNumber ? 'DHL' : 'UNKNOWN');
322
+
323
+ const carrier = rawCarrier.toUpperCase();
324
+
325
+ // Tracking Number
326
+ const trackingNumber = payload.trackingNumber ||
327
+ payload.tracking_number ||
328
+ payload.shipmentTrackingNumber ||
329
+ payload.waybillNumber ||
330
+ payload.packageId ||
331
+ 'UNKNOWN_TRACKING';
332
+
333
+ // Customer & Order
334
+ const customerId = payload.customerId || payload.customer?.id || payload.recipientId || 'CUST-PROACTIVE';
335
+ const orderId = payload.orderId || payload.orderNumber || payload.referenceId || null;
336
+ const customerTier = payload.customerTier || payload.customer?.tier || 'STANDARD';
337
+
338
+ // Event codes & details across FedEx, UPS, DHL conventions
339
+ const eventCode = payload.eventCode ||
340
+ payload.exceptionCode ||
341
+ payload.activity?.code ||
342
+ payload.details?.statusCode ||
343
+ payload.exception?.code ||
344
+ null;
345
+
346
+ const eventType = payload.eventType || payload.event || payload.type || null;
347
+
348
+ const status = payload.status ||
349
+ payload.activity?.status ||
350
+ payload.details?.status ||
351
+ null;
352
+
353
+ const statusDescription = payload.statusDescription ||
354
+ payload.description ||
355
+ payload.details?.remarks ||
356
+ payload.activity?.description ||
357
+ payload.exception?.description ||
358
+ null;
359
+
360
+ const details = payload.details?.description || payload.message || payload.remarks || statusDescription;
361
+
362
+ const stallHours = payload.stallHours ||
363
+ payload.hoursStalled ||
364
+ payload.hoursSinceLastScan ||
365
+ payload.activity?.hoursStalled ||
366
+ 0;
367
+
368
+ const lastScanTime = payload.lastScanTime ||
369
+ payload.activity?.lastScanTime ||
370
+ payload.lastScanTimestamp ||
371
+ null;
372
+
373
+ const currentScanTime = payload.currentScanTime ||
374
+ payload.timestamp ||
375
+ null;
376
+
377
+ return {
378
+ carrier,
379
+ trackingNumber,
380
+ customerId,
381
+ orderId,
382
+ customerTier,
383
+ eventCode,
384
+ eventType,
385
+ status,
386
+ statusDescription,
387
+ details,
388
+ stallHours,
389
+ lastScanTime,
390
+ currentScanTime,
391
+ raw: payload,
392
+ };
393
+ }
394
+
395
+ _calculateStallHours(event) {
396
+ if (event.lastScanTime && event.currentScanTime) {
397
+ const last = new Date(event.lastScanTime).getTime();
398
+ const curr = new Date(event.currentScanTime).getTime();
399
+ if (!isNaN(last) && !isNaN(curr) && curr > last) {
400
+ return (curr - last) / (1000 * 60 * 60);
401
+ }
402
+ }
403
+ return 0;
404
+ }
405
+ }