@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,274 @@
1
+ # ResolveX โšก
2
+ ### Autonomous Customer Resolution Agent
3
+
4
+ **ResolveX** is an agentic, policy-governed customer support resolution engine designed to resolve the full customer issueโ€”not merely answer questionsโ€”by authenticating context, verifying entitlements, executing low-risk safe actions autonomously, and escalating high-value or exception cases to human reviewers.
5
+
6
+ ---
7
+
8
+ ## ๐Ÿš€ Key Capabilities
9
+
10
+ - **Root-Cause Incident Diagnosis**: Automatically parses user intents and correlates them with telemetry, transaction histories, tracking APIs, and system outages (`DOUBLE_BILLING`, `SHIPPING_DELAY`, `PRODUCT_DEFECT`, `SERVICE_OUTAGE`, `INCORRECT_ITEM`).
11
+ - **Policy Engine & Guardrails**: Enforces strict financial limits (e.g., autonomous refunds $\le \$100$), return/warranty window verifications, and customer risk scoring.
12
+ - **Loyalty & Severity Multipliers**: Dynamically computes apology credits and vouchers based on customer loyalty tier (`STANDARD`, `BRONZE`, `SILVER`, `GOLD`, `PLATINUM`) and issue severity (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`).
13
+ - **Human-in-the-Loop (HITL) Escalation**: Automatically traps high-value refunds ($> \$100$), expired warranty claims, or suspicious abuse profiles into structured approval tickets with full audit trails.
14
+ - **Auditability & Observability**: Logs every ingestion, diagnosis signal, policy check, autonomous action, and human decision with immutable timestamps.
15
+ - **Zero External Dependencies**: Built with pure modern ES modules using Node.js built-ins (`node:test`, `node:assert`).
16
+
17
+ ---
18
+
19
+ ## ๐Ÿ› Architecture Overview
20
+
21
+ ```
22
+ +-----------------------------+
23
+ | Customer Inbound Issue |
24
+ +--------------+--------------+
25
+ |
26
+ v
27
+ +-----------------------------+
28
+ | Diagnosis Engine |
29
+ | (NLP + Telemetry Evidence) |
30
+ +--------------+--------------+
31
+ |
32
+ v
33
+ +-----------------------------+
34
+ | Policy Engine |
35
+ | (Limits, Risk, Multipliers)|
36
+ +--------------+--------------+
37
+ |
38
+ +-----------------------+-----------------------+
39
+ | |
40
+ [Low-Risk / Safe Action] [High-Risk / Exception]
41
+ (e.g., Refund <= $100) (e.g., Refund > $100)
42
+ | |
43
+ v v
44
+ +-----------------------------+ +-----------------------------+
45
+ | Autonomous Execution | | Approval Ticket Generated |
46
+ | (Refund, Replacement, etc) | | (Pending Supervisor HITL) |
47
+ +--------------+--------------+ +--------------+--------------+
48
+ | |
49
+ | v
50
+ | +-----------------------------+
51
+ | | Human Review: Approve/Reject|
52
+ | +--------------+--------------+
53
+ | |
54
+ +-----------------------+-----------------------+
55
+ |
56
+ v
57
+ +-----------------------------+
58
+ | Immutable Audit Trail Log |
59
+ +-----------------------------+
60
+ ```
61
+
62
+ ---
63
+
64
+ ## ๐Ÿ“ฆ Installation & Setup
65
+
66
+ ResolveX requires **Node.js v18+** with native ES modules support. No external `npm install` packages required.
67
+
68
+ ```bash
69
+ git clone <repo-url> ResolveX
70
+ cd ResolveX
71
+ ```
72
+
73
+ Run automated tests:
74
+ ```bash
75
+ npm test
76
+ ```
77
+
78
+ ---
79
+
80
+ ## ๐Ÿ’ก Usage Examples
81
+
82
+ ### 1. Autonomous Resolution (Double Billing < $100)
83
+
84
+ ```javascript
85
+ import { ResolveXAgent, CustomerTier } from 'resolvex';
86
+
87
+ const agent = new ResolveXAgent();
88
+
89
+ const customer = {
90
+ id: 'CUST-1001',
91
+ name: 'Alice Johnson',
92
+ tier: CustomerTier.SILVER,
93
+ accountAgeDays: 180,
94
+ };
95
+
96
+ const order = {
97
+ orderId: 'ORD-5501',
98
+ total: 80.0,
99
+ transactions: [
100
+ { id: 'tx-001', amount: 40.0, timestamp: '2026-11-18T08:00:00Z' },
101
+ { id: 'tx-002', amount: 40.0, timestamp: '2026-11-18T08:01:00Z' },
102
+ ],
103
+ };
104
+
105
+ const issue = {
106
+ description: 'I was charged twice $40 for the monthly plan.',
107
+ amount: 40.0,
108
+ };
109
+
110
+ const resolution = await agent.resolveIssue({ customer, order, issue });
111
+ console.log(resolution.status);
112
+ // => "RESOLVED_AUTONOMOUSLY"
113
+ // => Executes $40 refund + $31.25 Silver apology credit
114
+ ```
115
+
116
+ ---
117
+
118
+ ### 2. Human-in-the-Loop Escalation (High-Value Refund > $100)
119
+
120
+ ```javascript
121
+ import { ResolveXAgent, CustomerTier } from 'resolvex';
122
+
123
+ const agent = new ResolveXAgent();
124
+
125
+ const customer = {
126
+ id: 'CUST-4004',
127
+ name: 'David Miller',
128
+ tier: CustomerTier.STANDARD,
129
+ };
130
+
131
+ const order = {
132
+ orderId: 'ORD-9904',
133
+ total: 500.0,
134
+ transactions: [
135
+ { id: 'tx-A', amount: 250.0, timestamp: '2026-11-15T12:00:00Z' },
136
+ { id: 'tx-B', amount: 250.0, timestamp: '2026-11-15T12:02:00Z' },
137
+ ],
138
+ };
139
+
140
+ const issue = {
141
+ description: 'Charged twice $250 each for the annual subscription.',
142
+ amount: 250.0,
143
+ };
144
+
145
+ // 1. Agent detects refund exceeds $100 threshold and triggers HITL ticket
146
+ const resolution = await agent.resolveIssue({ customer, order, issue });
147
+ console.log(resolution.status);
148
+ // => "REQUIRES_APPROVAL"
149
+ console.log(resolution.ticketId);
150
+ // => "TICK-XXXX-YYYY"
151
+
152
+ // 2. Supervisor inspects pending queue and approves
153
+ const approval = await agent.approveTicket(resolution.ticketId, {
154
+ reviewerId: 'SUPERVISOR_SARAH',
155
+ notes: 'Confirmed Stripe duplicate payment error; approved refund.',
156
+ });
157
+
158
+ console.log(approval.status);
159
+ // => "RESOLVED_BY_APPROVAL"
160
+ ```
161
+
162
+ ---
163
+
164
+ ### 3. Supervisor Rejection with Courtesy Alternative
165
+
166
+ ```javascript
167
+ // Supervisor can decline full refund on out-of-warranty claims,
168
+ // but optionally offer a courtesy store voucher
169
+ const rejection = await agent.rejectTicket(ticketId, {
170
+ reviewerId: 'SUPERVISOR_MIKE',
171
+ reason: 'Item purchased over 1 year ago (out of warranty)',
172
+ alternativeAction: {
173
+ type: 'APOLOGY_CREDIT',
174
+ amount: 50.0,
175
+ currency: 'USD',
176
+ breakdown: 'Courtesy store credit',
177
+ },
178
+ });
179
+ ```
180
+
181
+ ---
182
+
183
+ ### 4. Querying the Immutable Audit Trail
184
+
185
+ ```javascript
186
+ const auditTrail = agent.getAuditLog({ caseId: resolution.caseId });
187
+ console.log(auditTrail);
188
+ /*
189
+ [
190
+ { id: 'AUD-...', stage: 'INGESTION', action: 'ISSUE_INGESTED', ... },
191
+ { id: 'AUD-...', stage: 'DIAGNOSIS', action: 'DIAGNOSIS_COMPLETED', ... },
192
+ { id: 'AUD-...', stage: 'POLICY_EVALUATION', action: 'PLAN_PROPOSED', ... },
193
+ { id: 'AUD-...', stage: 'ESCALATION', action: 'HUMAN_APPROVAL_REQUESTED', ... },
194
+ { id: 'AUD-...', stage: 'HUMAN_IN_THE_LOOP', action: 'TICKET_APPROVED_AND_EXECUTED', ... }
195
+ ]
196
+ */
197
+ ```
198
+
199
+ ---
200
+
201
+ ### 5. Computer Vision Damage Assessment (`DamageVerifier`)
202
+
203
+ Autonomously verifies photo evidence metadata, clarity, and physical damage types (`CRACKED_SCREEN`, `WATER_DAMAGE`, `SHATTERED_CASING`, `PHYSICAL_DEFORMATION`), detecting fraud and generating expedited replacement authorizations:
204
+
205
+ ```javascript
206
+ import { DamageVerifier, DamageType } from 'resolvex';
207
+
208
+ const verifier = new DamageVerifier();
209
+ const evaluation = verifier.evaluatePhoto({
210
+ photoId: 'PHOTO-101',
211
+ width: 1920,
212
+ height: 1080,
213
+ clarityScore: 0.94,
214
+ detectedDamageTypes: [DamageType.CRACKED_SCREEN],
215
+ exif: { deviceModel: 'iPhone 15 Pro', timestamp: '2026-11-18T10:00:00Z' }
216
+ });
217
+
218
+ if (evaluation.valid) {
219
+ const authorization = verifier.generateReplacementAuthorization({
220
+ evaluation,
221
+ claim: { id: 'CLM-101' },
222
+ customer: { id: 'CUST-202' },
223
+ item: { sku: 'PROD-PHONE-01', serialNumber: 'SN-12345' }
224
+ });
225
+ console.log(authorization.authorizationCode); // AUTH-REPL-...
226
+ }
227
+ ```
228
+
229
+ ---
230
+
231
+ ### 6. Proactive Carrier Tracking & Auto-Remediation (`CarrierWebhookListener`)
232
+
233
+ Ingests FedEx, UPS, and DHL webhooks, detects critical transit exceptions (`WEATHER_EXCEPTION`, `TRANSIT_STALL_48H`, `CUSTOMS_HOLD`), and dispatches priority traces and loyalty apology credits before the customer ever files a ticket:
234
+
235
+ ```javascript
236
+ import { CarrierWebhookListener, CarrierExceptionType } from 'resolvex';
237
+
238
+ const listener = new CarrierWebhookListener();
239
+
240
+ // Ingest webhook event from FedEx, UPS, or DHL
241
+ const outcome = listener.ingestWebhook({
242
+ carrier: 'FedEx',
243
+ trackingNumber: 'FX-9876543210',
244
+ customerId: 'CUST-1001',
245
+ eventType: 'EXCEPTION',
246
+ exceptionCode: 'WEATHER_DELAY',
247
+ statusDescription: 'Severe blizzard in central sorting hub'
248
+ });
249
+
250
+ console.log(outcome.proactiveActionTaken); // true
251
+ console.log(outcome.dispatchedActions); // [PRIORITY_CARRIER_TRACE, PROACTIVE_LOYALTY_CREDIT]
252
+ ```
253
+
254
+ ---
255
+
256
+ ## ๐Ÿงช Testing
257
+
258
+ Run the test suite using Node's native test runner:
259
+
260
+ ```bash
261
+ npm test
262
+ ```
263
+
264
+ Tests cover:
265
+ - Policy engine limits, warranty boundaries, loyalty calculations, and fraud detection.
266
+ - Natural language intent classification and multi-signal telemetry verification.
267
+ - Autonomous resolutions for billing, delivery delays, and defective products.
268
+ - Human-in-the-loop supervisor approvals, rejections, and alternate remedies.
269
+ - Audit trail completeness and tamper-evident structure.
270
+
271
+ ---
272
+
273
+ ## ๐Ÿ“œ License
274
+ MIT
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "resolvex",
3
+ "version": "1.0.0",
4
+ "description": "Autonomous Customer Resolution Agent with progressive autonomy, policy engine, and human-in-the-loop escalation",
5
+ "type": "module",
6
+ "main": "src/index.js",
7
+ "scripts": {
8
+ "test": "node --test test/*.test.js"
9
+ },
10
+ "keywords": [
11
+ "agentic-ai",
12
+ "customer-resolution",
13
+ "policy-engine",
14
+ "human-in-the-loop",
15
+ "autonomous-agent",
16
+ "support-automation"
17
+ ],
18
+ "author": "Antigravity",
19
+ "license": "MIT"
20
+ }