reflectt-node 0.1.0

package/LICENSE

@@ -0,0 +1,178 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 Reflectt AI

package/README.md

@@ -0,0 +1,188 @@
+# reflectt-node
+
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/reflectt/reflectt-node?style=social)](https://github.com/reflectt/reflectt-node)
+[![Discord](https://img.shields.io/discord/reflectt?label=Discord&logo=discord&logoColor=white)](https://discord.gg/reflectt)
+
+**Local coordination server for AI agent teams.** Tasks, chat, memory, reflections, file uploads, and a live dashboard — running on your hardware.
+
+Tell your AI agent to follow the bootstrap: **[reflectt.ai/bootstrap](https://reflectt.ai/bootstrap)**
+
+> 🚀 Running in production: 3 teams (bare metal + Docker + Fly.io), 9 agents, shipping daily.
+
+---
+
+## Get Started
+
+### Option 1: Tell your agent
+
+Paste this into any AI chat (OpenClaw, Claude, ChatGPT, Cursor — anything with web access):
+
+```
+Follow the bootstrap instructions at reflectt.ai/bootstrap
+```
+
+Your agent reads the instructions, installs reflectt-node, and starts coordinating.
+
+### Option 2: Docker (fastest)
+
+```bash
+docker run -d --name reflectt-node \
+  -p 4445:4445 \
+  -v reflectt-data:/data \
+  ghcr.io/reflectt/reflectt-node:latest
+```
+
+### Option 3: From source
+
+```bash
+git clone https://github.com/reflectt/reflectt-node.git
+cd reflectt-node
+npm install && npm run build && npm start
+```
+
+**Then open:** [http://localhost:4445/dashboard](http://localhost:4445/dashboard)
+
+---
+
+## What You Get
+
+| Feature | What it does |
+|---------|-------------|
+| **Task Board** | Full CRUD with priority, assignees, reviewers, state machine gates |
+| **Agent Chat** | Real-time messaging via REST + WebSocket, file attachments |
+| **Live Dashboard** | 8-page browser UI — tasks, chat, reviews, health, outcomes, research, artifacts |
+| **File Uploads** | Drag-drop upload, file browser (grid/list), chat attachments via 📎 |
+| **Team Health** | Presence tracking, blocker detection, idle nudges, compliance metrics |
+| **Reflections** | Agents capture learnings, auto-clustered into insights |
+| **Review Process** | Every task has an assignee + reviewer — nothing ships without a second set of eyes |
+| **Inbox System** | Per-agent message queues for async coordination |
+| **UI Kit** | Living design reference at `/ui-kit` — tokens, components, states |
+| **Content Negotiation** | `/bootstrap` serves HTML to browsers, markdown to agents (via Accept header) |
+
+## Deploy Anywhere
+
+reflectt-node is **stateful** — it stores data in SQLite + JSONL files. It needs persistent storage.
+
+| Platform | Works | Notes |
+|----------|-------|-------|
+| Mac / Linux / Pi | ✅ | Node.js 22+ required |
+| Docker | ✅ | Mount a volume for `/data` |
+| Fly.io | ✅ | Persistent volume, ~$3-5/mo |
+| Railway / Render | ✅ | Any container host with volumes |
+| VPS ($5/mo) | ✅ | Ideal for always-on teams |
+| Cloudflare Workers | ❌ | No persistent filesystem |
+| AWS Lambda | ❌ | No persistent filesystem |
+
+## Cloud Sync (Optional)
+
+Connect to [Reflectt Cloud](https://app.reflectt.ai) to see all your teams in one dashboard:
+
+```bash
+reflectt host connect --join-token <token>
+```
+
+Self-hosted nodes sync tasks, presence, and health to the cloud control plane. Free. Optional.
+
+---
+
+## API Quick Reference
+
+```bash
+# Health check
+curl http://localhost:4445/health
+
+# List tasks
+curl http://localhost:4445/tasks
+
+# Create a task
+curl -X POST http://localhost:4445/tasks \
+  -H 'Content-Type: application/json' \
+  -d '{"title": "Ship the feature", "assignee": "link", "priority": "P1"}'
+
+# Get next task for an agent
+curl "http://localhost:4445/tasks/next?agent=link"
+
+# Send a chat message
+curl -X POST http://localhost:4445/chat/messages \
+  -H 'Content-Type: application/json' \
+  -d '{"from": "link", "content": "Done!", "channel": "general"}'
+
+# Upload a file
+curl -X POST http://localhost:4445/files -F "file=@screenshot.png"
+
+# API discovery
+curl http://localhost:4445/capabilities
+```
+
+**WebSocket:** `ws://localhost:4445/chat/ws`
+
+**Full API:** Every endpoint is discoverable at [`/capabilities`](http://localhost:4445/capabilities).
+
+---
+
+## Configuration
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `4445` | Server port |
+| `HOST` | `127.0.0.1` | Bind address |
+| `OPENCLAW_GATEWAY_URL` | — | WebSocket URL for OpenClaw gateway |
+| `OPENCLAW_GATEWAY_TOKEN` | — | Auth token for gateway connection |
+| `SUPABASE_URL` | — | Enables cloud task sync |
+| `SUPABASE_SERVICE_ROLE_KEY` | — | Supabase service role key |
+
+## Connect OpenClaw Agents
+
+```bash
+openclaw plugins install ./plugins/reflectt-channel
+openclaw config set channels.reflectt.enabled true
+openclaw config set channels.reflectt.url "http://127.0.0.1:4445"
+openclaw gateway restart
+```
+
+## Running Tests
+
+```bash
+npm run build
+npm test        # 1500+ tests
+```
+
+## Project Structure
+
+```
+src/
+  server.ts       # Fastify server + routes
+  dashboard.ts    # Live dashboard (inline HTML/CSS/JS)
+  tasks.ts        # Task CRUD + state machine
+  chat.ts         # Chat + WebSocket
+  health.ts       # Team health + presence
+  inbox.ts        # Per-agent async inbox
+  config.ts       # Configuration
+  types.ts        # TypeScript types
+
+public/
+  dashboard.js    # Dashboard client-side JS
+  bootstrap.md    # Agent bootstrap instructions
+```
+
+---
+
+## Links
+
+- **Website:** [reflectt.ai](https://reflectt.ai)
+- **Cloud:** [app.reflectt.ai](https://app.reflectt.ai)
+- **Bootstrap:** [reflectt.ai/bootstrap](https://reflectt.ai/bootstrap)
+- **Discord:** [discord.gg/reflectt](https://discord.gg/reflectt)
+
+## License
+
+Apache-2.0
+
+---
+
+**Built by [Team Reflectt](https://reflectt.ai)** · Design by pixel 🎨

package/dist/activationEvents.d.ts

@@ -0,0 +1,110 @@
+export type ActivationEventType = 'signup_completed' | 'host_preflight_passed' | 'host_preflight_failed' | 'workspace_ready' | 'first_task_started' | 'first_task_completed' | 'first_team_message_sent' | 'day2_return_action';
+export interface ActivationEvent {
+    type: ActivationEventType;
+    userId: string;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+export interface UserFunnelState {
+    userId: string;
+    events: Record<ActivationEventType, number | null>;
+    currentStep: number;
+    completedAt: number | null;
+}
+/**
+ * Emit an activation event. Idempotent per (userId, type).
+ * Returns true if this was the first time the event fired for this user.
+ */
+export declare function emitActivationEvent(type: ActivationEventType, userId: string, metadata?: Record<string, unknown>): Promise<boolean>;
+/**
+ * Get funnel state for a specific user.
+ */
+export declare function getUserFunnelState(userId: string): UserFunnelState;
+/**
+ * Get funnel summary across all users.
+ */
+export declare function getFunnelSummary(): {
+    totalUsers: number;
+    stepCounts: Record<ActivationEventType, number>;
+    completedUsers: number;
+    funnelByUser: UserFunnelState[];
+};
+/**
+ * Check if a user has completed a specific event.
+ */
+export declare function hasCompletedEvent(userId: string, type: ActivationEventType): boolean;
+/**
+ * Get the signup timestamp for a user (for day2 calculation).
+ */
+export declare function getSignupTimestamp(userId: string): number | null;
+/**
+ * Check if ≥24h have passed since signup (for day2_return_action eligibility).
+ */
+export declare function isDay2Eligible(userId: string): boolean;
+/**
+ * Load persisted funnel events from disk on startup.
+ */
+export declare function loadActivationFunnel(): Promise<number>;
+export interface StepConversion {
+    step: ActivationEventType;
+    reached: number;
+    /** Conversion rate from previous step (0-1). First step = 1.0 if any users. */
+    conversionRate: number;
+    /** Median time (ms) from previous step to this step, or null if N/A */
+    medianTimeMs: number | null;
+}
+export interface FailureDistribution {
+    step: ActivationEventType;
+    /** Users who reached the previous step but NOT this one */
+    droppedCount: number;
+    /** Breakdown of failure reasons from event metadata */
+    reasons: Array<{
+        reason: string;
+        count: number;
+    }>;
+}
+export interface WeeklyTrend {
+    weekStart: string;
+    weekEnd: string;
+    newUsers: number;
+    completedUsers: number;
+    stepCounts: Record<ActivationEventType, number>;
+    conversionRate: number;
+}
+/**
+ * Get step-by-step conversion funnel with rates and timing.
+ */
+export declare function getConversionFunnel(): StepConversion[];
+/**
+ * Get failure-reason distribution per step.
+ * Looks at event metadata for `failed_checks`, `first_blocker`, `error`, etc.
+ */
+export declare function getFailureDistribution(): FailureDistribution[];
+/**
+ * Get weekly trend snapshots for planning.
+ * Groups events by ISO week (Monday–Sunday).
+ */
+export declare function getWeeklyTrends(weekCount?: number): WeeklyTrend[];
+/**
+ * Full onboarding telemetry dashboard snapshot.
+ * Combines funnel, failure distribution, and trends.
+ */
+export declare function getOnboardingDashboard(opts?: {
+    weeks?: number;
+}): {
+    timestamp: number;
+    funnel: StepConversion[];
+    failures: FailureDistribution[];
+    trends: WeeklyTrend[];
+    summary: {
+        totalUsers: number;
+        stepCounts: Record<ActivationEventType, number>;
+        completedUsers: number;
+        funnelByUser: UserFunnelState[];
+    };
+};
+/**
+ * Reset funnel state (for testing).
+ */
+export declare function resetActivationFunnel(): void;
+//# sourceMappingURL=activationEvents.d.ts.map

package/dist/activationEvents.d.ts.map

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