@spekra.in/agent-os 0.0.0-stage โ†’ 1.1.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 (115) 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 +208 -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 +338 -0
  113. package/package.json +52 -4
  114. package/src/index.js +95 -0
  115. package/src/llm-gateway.js +226 -0
@@ -0,0 +1,41 @@
1
+ # Booker โ€” Intake & Dispatch Agent
2
+
3
+ **Booker** is the customer inquiry intake, validation, and technician scheduling agent for field service operations.
4
+
5
+ ## Capabilities
6
+
7
+ 1. **Unstructured Inquiry Parsing:** Converts freeform text, chat messages, or call notes into normalized intake records.
8
+ 2. **Strict Validation & Schema Enforcement:** Enforces customer, address, supported appliance category, and canonical ISO UTC timestamps.
9
+ 3. **Currency Conversion:** Automatically converts INR values (`โ‚น1,500`, `Rs. 1,500`) into integer paise (`150000`).
10
+ 4. **Duration-Aware Scheduling:** Prevents appointment overlaps within a configurable duration window (default 90 min) with read-back verification.
11
+ 5. **Authorization Gate:** Demands explicit owner approval before locking technician calendar slots.
12
+
13
+ ## Usage
14
+
15
+ ```javascript
16
+ import { parseIntake, CalendarAdapter, bookingAgent } from 'booker-agent';
17
+
18
+ // 1. Parse inquiry
19
+ const inquiry = `
20
+ Customer: Rajesh Kumar
21
+ Address: 42 Palm Grove Road, Bangalore
22
+ Appliance: Samsung front loader washing machine
23
+ Slot: 2026-12-01T10:00:00+05:30
24
+ Estimated charge: โ‚น1,500
25
+ Technician: tech-101
26
+ `;
27
+ const result = parseIntake(inquiry);
28
+
29
+ // 2. Reserve schedule
30
+ const calendar = new CalendarAdapter(90);
31
+ const reservation = calendar.reserve('tenant-1', 'tech-101', result.candidate.slot, 'job-001');
32
+
33
+ // 3. Evaluate Agent Decision
34
+ const nextStep = bookingAgent.next({ input: result.candidate });
35
+ ```
36
+
37
+ ## Testing
38
+
39
+ ```sh
40
+ npm test
41
+ ```
@@ -0,0 +1,11 @@
1
+ {
2
+ "name": "booker-agent",
3
+ "version": "0.1.0",
4
+ "description": "Booker - Intake & Dispatch Agent for Service Workflows",
5
+ "private": true,
6
+ "type": "module",
7
+ "engines": { "node": ">=24" },
8
+ "scripts": {
9
+ "test": "node --test"
10
+ }
11
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Booker: Booking and Dispatch Agent
3
+ * Turns customer requests into confirmed, properly scoped technician appointments.
4
+ */
5
+ export const bookingAgent = {
6
+ name: 'booker',
7
+ next(job) {
8
+ const missing = ['customer', 'address', 'appliance', 'technician', 'slot'].filter(k => !job.input[k]);
9
+ if (missing.length) return { wait: 'needs_information', reason: `Provide: ${missing.join(', ')}` };
10
+ if (job.input.appliance !== 'washing-machine') return { wait: 'blocked', reason: 'Only washing-machine service is supported in this pilot' };
11
+ if (!Number.isSafeInteger(job.input.amount) || job.input.amount <= 0) return { wait: 'needs_information', reason: 'Provide a positive estimate in minor currency units' };
12
+ if (!job.booking) return { tool: 'book', permission: 'booking', reason: 'Reserve the requested technician slot' };
13
+ return { transition: 'booked' };
14
+ }
15
+ };
@@ -0,0 +1,75 @@
1
+ import { randomUUID } from 'node:crypto';
2
+
3
+ /**
4
+ * Booker Calendar Adapter
5
+ * Enforces duration-aware overlap detection, idempotent reservations, and read-back verification.
6
+ */
7
+ export class CalendarAdapter {
8
+ constructor(defaultDurationMinutes = 90) {
9
+ this.defaultDurationMinutes = defaultDurationMinutes;
10
+ this.reservations = new Map();
11
+ }
12
+
13
+ #key(tenant, technician) {
14
+ return `${tenant}:${technician}`;
15
+ }
16
+
17
+ reserve(tenant, technician, slotIso, jobId, durationMinutes = this.defaultDurationMinutes) {
18
+ const startMs = Date.parse(slotIso);
19
+ if (!Number.isFinite(startMs)) throw new Error('Invalid slot timestamp for calendar adapter');
20
+ const endMs = startMs + durationMinutes * 60 * 1000;
21
+ const key = this.#key(tenant, technician);
22
+
23
+ const list = this.reservations.get(key) ?? [];
24
+
25
+ const existingForJob = list.find(r => r.jobId === jobId);
26
+ if (existingForJob) {
27
+ if (existingForJob.startMs === startMs && existingForJob.endMs === endMs) {
28
+ return { id: existingForJob.id, verified: true, slot: slotIso, startMs, endMs };
29
+ }
30
+ throw new Error('Job already has an active conflicting reservation at another time');
31
+ }
32
+
33
+ const overlap = list.find(r => startMs < r.endMs && endMs > r.startMs);
34
+ if (overlap) {
35
+ throw new Error(`Technician ${technician} has a schedule conflict with job ${overlap.jobId} until ${new Date(overlap.endMs).toISOString()}`);
36
+ }
37
+
38
+ const reservation = {
39
+ id: randomUUID(),
40
+ jobId,
41
+ slotIso,
42
+ startMs,
43
+ endMs,
44
+ verified: true,
45
+ simulated: true
46
+ };
47
+
48
+ list.push(reservation);
49
+ this.reservations.set(key, list);
50
+
51
+ const verified = this.reservations.get(key)?.find(r => r.id === reservation.id);
52
+ if (!verified) throw new Error('Calendar write failed read-back verification');
53
+
54
+ return { id: reservation.id, verified: true, slot: slotIso, startMs, endMs };
55
+ }
56
+
57
+ release(tenant, technician, jobId) {
58
+ const key = this.#key(tenant, technician);
59
+ const list = this.reservations.get(key);
60
+ if (!list) return false;
61
+ const initialLen = list.length;
62
+ const filtered = list.filter(r => r.jobId !== jobId);
63
+ this.reservations.set(key, filtered);
64
+ return filtered.length < initialLen;
65
+ }
66
+
67
+ isAvailable(tenant, technician, slotIso, durationMinutes = this.defaultDurationMinutes) {
68
+ const startMs = Date.parse(slotIso);
69
+ if (!Number.isFinite(startMs)) return false;
70
+ const endMs = startMs + durationMinutes * 60 * 1000;
71
+ const key = this.#key(tenant, technician);
72
+ const list = this.reservations.get(key) ?? [];
73
+ return !list.some(r => startMs < r.endMs && endMs > r.startMs);
74
+ }
75
+ }
@@ -0,0 +1,4 @@
1
+ export { bookingAgent } from './agent.js';
2
+ export { parseIntake } from './intake-parser.js';
3
+ export { CalendarAdapter } from './calendar-adapter.js';
4
+ export { intake, text, object } from './validation.js';
@@ -0,0 +1,96 @@
1
+ import { intake } from './validation.js';
2
+
3
+ /**
4
+ * Booker Intake Parser: Parses unstructured customer inquiry text or notes
5
+ * into a validated intake candidate with INR/paise normalization.
6
+ */
7
+ export function parseIntake(rawText, options = {}) {
8
+ if (typeof rawText !== 'string' || !rawText.trim()) {
9
+ return { success: false, errors: ['Input text must be a non-empty string'], missing: ['customer', 'address', 'appliance', 'technician', 'slot', 'amount'] };
10
+ }
11
+ if (rawText.length > 4096) {
12
+ return { success: false, errors: ['Input text exceeds 4096 character limit'], missing: [] };
13
+ }
14
+
15
+ const text = rawText.replace(/\r\n/g, '\n');
16
+ const candidate = {};
17
+ const errors = [];
18
+ const warnings = [];
19
+
20
+ // 1. Appliance detection
21
+ if (/\b(washing[-\s]*machine|washer|front\s*loader|top\s*loader)\b/i.test(text)) {
22
+ candidate.appliance = 'washing-machine';
23
+ } else if (/\b(refrigerator|fridge|microwave|dishwasher|dryer|oven|ac|air\s*conditioner)\b/i.test(text)) {
24
+ const match = text.match(/\b(refrigerator|fridge|microwave|dishwasher|dryer|oven|ac|air\s*conditioner)\b/i);
25
+ errors.push(`Unsupported appliance detected: "${match[0]}". Pilot only supports washing-machine.`);
26
+ }
27
+
28
+ // 2. Customer Name extraction
29
+ const nameMatch = text.match(/(?:(?:customer|client|name)\s*[:=-]\s*|my\s+name\s+is\s+|i\s+am\s+)([A-Z][a-zA-Z\s]{1,50})(?:\n|,|\.|$)/i);
30
+ if (nameMatch) {
31
+ candidate.customer = nameMatch[1].trim();
32
+ }
33
+
34
+ // 3. Address extraction
35
+ const addrMatch = text.match(/(?:(?:address|location|at)\s*[:=-]\s*)([^\n]+)/i);
36
+ if (addrMatch) {
37
+ candidate.address = addrMatch[1].trim();
38
+ }
39
+
40
+ // 4. Amount / Estimate extraction (INR / Paise)
41
+ const paiseMatch = text.match(/(\d+)\s*paise\b/i);
42
+ const inrMatch = text.match(/(?:โ‚น|rs\.?|inr)\s*([\d,]+(?:\.\d{1,2})?)|([\d,]+(?:\.\d{1,2})?)\s*(?:rupees|inr)/i);
43
+ if (paiseMatch) {
44
+ candidate.amount = parseInt(paiseMatch[1], 10);
45
+ } else if (inrMatch) {
46
+ const numStr = (inrMatch[1] || inrMatch[2]).replace(/,/g, '');
47
+ const inr = parseFloat(numStr);
48
+ if (!isNaN(inr) && inr > 0) {
49
+ candidate.amount = Math.round(inr * 100);
50
+ }
51
+ }
52
+
53
+ // 5. Slot / Timestamp extraction
54
+ const slotMatch = text.match(/\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?(?:Z|[+-]\d{2}:\d{2})\b/);
55
+ if (slotMatch) {
56
+ candidate.slot = slotMatch[0];
57
+ }
58
+
59
+ // 6. Technician extraction
60
+ const techMatch = text.match(/(?:technician|tech|assigned\s+to)\s*[:=-]\s*([a-zA-Z0-9_-]+)/i);
61
+ if (techMatch) {
62
+ candidate.technician = techMatch[1].trim();
63
+ }
64
+
65
+ // Apply explicit overrides/defaults from options
66
+ if (options.defaults) {
67
+ for (const [k, v] of Object.entries(options.defaults)) {
68
+ if (candidate[k] === undefined && v !== undefined) {
69
+ candidate[k] = v;
70
+ }
71
+ }
72
+ }
73
+
74
+ const required = ['customer', 'address', 'appliance', 'technician', 'slot', 'amount'];
75
+ const missing = required.filter(k => candidate[k] === undefined);
76
+
77
+ try {
78
+ const validated = intake(candidate);
79
+ return {
80
+ success: missing.length === 0 && errors.length === 0,
81
+ candidate: validated,
82
+ missing,
83
+ errors,
84
+ warnings
85
+ };
86
+ } catch (err) {
87
+ errors.push(err.message);
88
+ return {
89
+ success: false,
90
+ candidate,
91
+ missing,
92
+ errors,
93
+ warnings
94
+ };
95
+ }
96
+ }
@@ -0,0 +1,34 @@
1
+ export function text(value, name, max = 256) {
2
+ if (typeof value !== 'string' || !value.trim() || value.length > max || /[\x00-\x1f]/.test(value)) throw new Error(`Invalid ${name}`);
3
+ return value;
4
+ }
5
+
6
+ export function object(value, keys) {
7
+ if (!value || Object.getPrototypeOf(value) !== Object.prototype || JSON.stringify(value).length > 16384 || Object.keys(value).some(k => !keys.includes(k))) {
8
+ throw new Error('Invalid or oversized payload');
9
+ }
10
+ }
11
+
12
+ export function intake(value) {
13
+ object(value, ['customer','address','appliance','technician','slot','amount']);
14
+ const result = { ...value };
15
+ for (const k of ['customer','address','appliance','technician','slot']) {
16
+ if (k in result) text(result[k], k, k === 'address' ? 1024 : 256);
17
+ }
18
+ if ('appliance' in result && result.appliance !== 'washing-machine') throw new Error('Unsupported appliance');
19
+ if ('slot' in result) {
20
+ if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?(?:Z|[+-]\d{2}:\d{2})$/.test(result.slot) || !Number.isFinite(Date.parse(result.slot))) {
21
+ throw new Error('Invalid slot timestamp');
22
+ }
23
+ const zone = result.slot.endsWith('Z') ? null : result.slot.slice(-6);
24
+ const offset = zone ? (Number(zone.slice(1,3)) * 60 + Number(zone.slice(4))) * (zone[0] === '+' ? 1 : -1) : 0;
25
+ if (new Date(Date.parse(result.slot) + offset * 60000).toISOString().slice(0,19) !== result.slot.slice(0,19)) {
26
+ throw new Error('Invalid calendar timestamp');
27
+ }
28
+ result.slot = new Date(result.slot).toISOString();
29
+ }
30
+ if ('amount' in result && (!Number.isSafeInteger(result.amount) || result.amount < 1 || result.amount > 100000000)) {
31
+ throw new Error('Invalid amount');
32
+ }
33
+ return result;
34
+ }
@@ -0,0 +1,35 @@
1
+ import test from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { bookingAgent, parseIntake, CalendarAdapter } from '../src/index.js';
4
+
5
+ test('Booker: parses text and evaluates booking policy', () => {
6
+ const note = `
7
+ Customer: Rajesh Kumar
8
+ Address: 42 Palm Grove Road, Bangalore
9
+ Appliance: washing machine
10
+ Slot: 2026-12-01T10:00:00+05:30
11
+ Estimated charge: โ‚น1,500
12
+ Technician: tech-101
13
+ `;
14
+ const parsed = parseIntake(note);
15
+ assert.equal(parsed.success, true);
16
+
17
+ const decision = bookingAgent.next({ input: parsed.candidate });
18
+ assert.equal(decision.tool, 'book');
19
+ assert.equal(decision.permission, 'booking');
20
+
21
+ const afterBooking = bookingAgent.next({ input: parsed.candidate, booking: { id: 'b-1' } });
22
+ assert.equal(afterBooking.transition, 'booked');
23
+ });
24
+
25
+ test('Booker: calendar adapter prevents conflicting appointment overlaps', () => {
26
+ const calendar = new CalendarAdapter(90);
27
+ const slot = '2026-12-01T10:00:00.000Z';
28
+ const res1 = calendar.reserve('t1', 'tech-1', slot, 'job-1');
29
+ assert.ok(res1.id);
30
+
31
+ assert.throws(
32
+ () => calendar.reserve('t1', 'tech-1', '2026-12-01T10:30:00.000Z', 'job-2'),
33
+ /schedule conflict/
34
+ );
35
+ });
@@ -0,0 +1,181 @@
1
+ # CashHound ๐Ÿ•๐Ÿ’ฐ
2
+ ### Autonomous SMB Revenue Recovery Agent
3
+
4
+ CashHound is a specialized, zero-dependency autonomous accounts receivable agent designed for small-to-medium businesses (SMBs). It identifies unpaid invoices, calculates recovery priorities, generates polite-to-firm communications with tone controls, enforces human approval guardrails for high-value and legal accounts, and reconciles payments in real time.
5
+
6
+ ---
7
+
8
+ ## ๐ŸŒŸ Key Capabilities
9
+
10
+ 1. **Intelligent Aging & Dynamic Priority Scoring:**
11
+ - Categorizes receivables across aging brackets: `current` (<= 0 days), `30+` (1-30 days), `60+` (31-60 days), and `90+` (61+ days).
12
+ - Priority scoring engine evaluates overdue days, exposure balance, customer relationship tier (`standard`, `vip`, `at_risk`), and active disputes.
13
+
14
+ 2. **Tiered Polite-to-Firm Dunning Engine:**
15
+ - **Tier 1 (1โ€“14 days):** Friendly courtesy check-in and subtle reminder.
16
+ - **Tier 2 (15โ€“30 days):** Professional follow-up inquiry with clear payment links.
17
+ - **Tier 3 (31โ€“60 days):** Firm notice with pre-approved installment plan schedules.
18
+ - **Tier 4 (61+ days):** Formal final demand with lump-sum settlement discount options.
19
+ - **Tone Controls:** Automatically adapts tone (`friendly`, `professional`, `urgent`, `formal`, `empathetic`), preserving VIP customer relationships with concierge care.
20
+
21
+ 3. **Financial Calculators:**
22
+ - **Installment Payment Plan Generator:** Computes split payment schedules (weekly, bi-weekly, monthly) with transparent milestone breakdowns.
23
+ - **Lump-Sum Settlement Offer Calculator:** Computes time-bounded settlement discounts (e.g. 15% off for payment within 7 days) to recover cash immediately.
24
+
25
+ 4. **Safety & Governance Guardrails (Human-in-the-Loop):**
26
+ - **High-Value Account Gate:** Any invoice balance $\ge$ $5,000 is automatically held in a pending approvals queue for human sign-off before sending.
27
+ - **Legal Dispute Hold:** Invoices flagged with legal action or attorney involvement halt automated dunning and escalate directly to human legal review.
28
+ - **Commercial Dispute Routing:** Pauses collection efforts while customer billing disputes are under investigation.
29
+ - **Anti-Spam Cooldown:** Configurable cooldown period (default 7 days) prevents over-contacting clients.
30
+ - **Autonomous Safe Execution:** Invoices below the high-value threshold without active disputes are automatically drafted and sent.
31
+
32
+ 5. **Instant Payment Reconciliation:**
33
+ - Automatically applies incoming payments (ACH, card, wire, check).
34
+ - Updates invoice balance and status (`paid`, `partially_paid`).
35
+ - Cancels pending dunning actions automatically.
36
+ - Emits a branded, polite payment receipt acknowledgment.
37
+
38
+ 6. **Auditable Decision Log:**
39
+ - Chronological, tamper-evident audit trail of every automated decision, approval, rejection, and payment event.
40
+
41
+ ---
42
+
43
+ ## ๐Ÿ—๏ธ Architecture & Decision Flow
44
+
45
+ ```mermaid
46
+ flowchart TD
47
+ A["New / Overdue Invoice"] --> B["Evaluate Invoice"]
48
+ B --> C{"Balance <= 0 or Current?"}
49
+ C -- Yes --> D["NO_ACTION (No dunning required)"]
50
+ C -- No --> E{"Active Legal Dispute?"}
51
+ E -- Yes --> F["REQUIRE_APPROVAL (Legal Hold Gate)"]
52
+ E -- No --> G{"Commercial Dispute Open?"}
53
+ G -- Yes --> H["DISPUTE_REVIEW (Pause Dunning)"]
54
+ G -- No --> I{"Within Cooldown Window?"}
55
+ I -- Yes --> J["NO_ACTION (Cooldown active)"]
56
+ I -- No --> K{"Balance >= $5,000 OR Tier 4 Final Demand?"}
57
+ K -- Yes --> L["PENDING_APPROVAL (Operator Review Queue)"]
58
+ K -- No --> M["AUTO_EXECUTED (Safe Dunning Dispatch)"]
59
+
60
+ L --> N{"Human Decision"}
61
+ N -- Approve --> O["Execute Reminder & Record Communication"]
62
+ N -- Reject --> P["Action Rejected & Log Reason"]
63
+
64
+ Q["Payment Received"] --> R["Record Payment & Update Balance"]
65
+ R --> S["Cancel Pending Dunning Actions"]
66
+ R --> T["Issue Receipt Acknowledgment"]
67
+ ```
68
+
69
+ ---
70
+
71
+ ## ๐Ÿš€ Quick Start
72
+
73
+ ### Installation
74
+
75
+ CashHound is built with pure Node.js ES modules and has **zero external runtime dependencies**:
76
+
77
+ ```bash
78
+ cd CashHound
79
+ npm test
80
+ ```
81
+
82
+ ### Usage Example
83
+
84
+ ```javascript
85
+ import {
86
+ Invoice,
87
+ CashHoundAgent,
88
+ CustomerTier,
89
+ DunningTier,
90
+ generateDunningMessage,
91
+ calculateInstallmentPlan,
92
+ } from './src/index.js';
93
+
94
+ // 1. Initialize CashHound Agent with governance policies
95
+ const agent = new CashHoundAgent({
96
+ highValueThreshold: 5000, // Accounts >= $5,000 require human review
97
+ cooldownDays: 7, // 7-day cooldown between communications
98
+ autoSendSafeReminders: true,
99
+ });
100
+
101
+ // 2. Register Invoices
102
+ const invoice1 = new Invoice({
103
+ id: 'INV-2024-001',
104
+ customer: {
105
+ name: 'Acme Hardware',
106
+ email: 'accounts@acmehardware.com',
107
+ tier: CustomerTier.STANDARD,
108
+ },
109
+ amount: 1250.00,
110
+ dueDate: '2026-10-15', // Overdue
111
+ });
112
+
113
+ const highValueInvoice = new Invoice({
114
+ id: 'INV-2024-002',
115
+ customer: {
116
+ name: 'Global Tech Industries',
117
+ email: 'finance@globaltech.com',
118
+ tier: CustomerTier.VIP,
119
+ },
120
+ amount: 8500.00,
121
+ dueDate: '2026-10-10', // Overdue high-value
122
+ });
123
+
124
+ agent.registerInvoice(invoice1);
125
+ agent.registerInvoice(highValueInvoice);
126
+
127
+ // 3. Process Invoices
128
+ // Safe invoice (< $5,000) is automatically executed:
129
+ const action1 = agent.processInvoice(invoice1);
130
+ console.log(action1.status); // 'AUTO_EXECUTED'
131
+
132
+ // High-value invoice (>= $5,000) is held for approval:
133
+ const action2 = agent.processInvoice(highValueInvoice);
134
+ console.log(action2.status); // 'PENDING_APPROVAL'
135
+ console.log(action2.approvalReasons);
136
+ // ['High-value invoice balance ($8,500 >= $5,000)']
137
+
138
+ // 4. Human-in-the-Loop Review
139
+ const pendingList = agent.getPendingApprovals();
140
+ console.log(`Pending approvals: ${pendingList.length}`);
141
+
142
+ // Approve action:
143
+ agent.approveAction(action2.id, {
144
+ name: 'Jane Doe',
145
+ notes: 'Spoke with CFO; verified terms. Approved to send.',
146
+ });
147
+
148
+ // 5. Payment Reconciliation
149
+ agent.recordPayment('INV-2024-001', {
150
+ amount: 1250.00,
151
+ method: 'ach',
152
+ reference: 'ACH-789123',
153
+ });
154
+
155
+ console.log(invoice1.status); // 'paid'
156
+ console.log(invoice1.balance); // 0
157
+ ```
158
+
159
+ ---
160
+
161
+ ## ๐Ÿงช Testing
162
+
163
+ CashHound uses the native Node.js test runner (`node:test`) and strict assertions (`node:assert`):
164
+
165
+ ```bash
166
+ npm test
167
+ ```
168
+
169
+ ### Test Coverage Highlights:
170
+ - **Aging Engine:** Strict verification of `current`, `30+`, `60+`, and `90+` day brackets.
171
+ - **Tone & Dunning:** Courtesy, reminder, urgent notices, VIP preservation, installment schedules, and settlement calculations.
172
+ - **Safety Gates:** Validation of $\ge \$5,000$ high-value threshold and legal dispute isolation.
173
+ - **State Machine:** Automated approval workflows, action rejections, cooldown enforcement.
174
+ - **Reconciliation:** Partial and full payments, auto-cancellation of pending actions, and receipt generation.
175
+ - **Batch Processing:** Complete multi-account portfolio cycle evaluation.
176
+
177
+ ---
178
+
179
+ ## ๐Ÿ“„ License
180
+
181
+ MIT
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "cashhound",
3
+ "version": "1.0.0",
4
+ "description": "Autonomous SMB Revenue Recovery Agent - accounts receivable recovery, intelligent dunning, and risk-managed approval workflows",
5
+ "main": "src/index.js",
6
+ "type": "module",
7
+ "scripts": {
8
+ "test": "node --test test/**/*.test.js"
9
+ },
10
+ "keywords": [
11
+ "revenue-recovery",
12
+ "accounts-receivable",
13
+ "dunning",
14
+ "agentic-ai",
15
+ "smb",
16
+ "cashflow",
17
+ "invoicing"
18
+ ],
19
+ "author": "Antigravity",
20
+ "license": "MIT"
21
+ }