@photon-ai/flux 0.3.7 → 0.3.8

package/README.md

@@ -1,80 +1,101 @@
 <div align="center">
 
-![Banner](./assets/banner.png)
-
 # @photon-ai/flux
 
-> A new way to build and deploy your iMessage agents at the speed of light
+> An open-source CLI for deploying LangChain agents to iMessage in seconds
 
 </div>
 
 [![npm version](https://img.shields.io/npm/v/@photon-ai/flux.svg)](https://www.npmjs.com/package/@photon-ai/flux)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
-[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![Discord](https://img.shields.io/badge/Discord-Join-5865F2.svg?logo=discord&logoColor=white)](https://discord.gg/bZd4CMd2H5)
 
 Flux is an open-sourced CLI tool that lets developers build and deploy LangChain agents that connect to iMessage at no cost and under 5 seconds. 
 
-<!-- --- -->
+## Features 
 
-## Features
 
-- **Deploy with a single command**: Export a LangChain agent and deploy it to iMessage with a single command. 
-- **Text your agent from your phone**: Send an iMessage to the Flux number and get responses from your running agent. 
-- **Testing mode**: Test your agent through your terminal before connecting to the iMessage brigde. 
-- **Phone Number Authentication**: Log in with just your phone number and iMessage. 
-- **Agent Validation**: Automatically validate your LangChain agent in the CLI. 
+- **Deploy with a single command**: Export a LangChain agent and deploy it to iMessage with one command
+- **Text your agent from your phone**: Send an iMessage to the Flux number and get responses from your running agent
+- **Testing mode**: Test your agent through your terminal before connecting to the iMessage bridge
+- **Phone Number Authentication**: Log in with just your phone number and iMessage
+- **Agent Validation**: Automatically validate your LangChain agent in the CLI
 
-<!-- --- -->
+## Quick Start
 
-## Installation
 
-### 
-```
-npm install @photon-ai/flux
-#or
-bun add @photon-ai/flux
-```
+Get started with Flux in seconds:
 
-<!-- --- -->
+```bash
+# No installation needed - use npx directly
+npx @photon-ai/flux login
 
-## CLI Commands
+# Create your agent file
+echo 'export default {
+  async invoke({ message }: { message: string }) {
+    return `You said: ${message}`;
+  }
+};' > agent.ts
 
-| Command | Description |
-|---------|-------------|
-| `npx @photon-ai/flux` | Show help |
-| `npx @photon-ai/flux whoami` | Check account |
-| `npx @photon-ai/flux login` | Login and signup|
-| `npx @photon-ai/flux logout` | Logout |
-| `npx @photon-ai/flux run --local` | Start the development server (local mode) |
-| `npx @photon-ai/flux run --prod` | Start with live iMessage bridge |
-| `npx @photon-ai/flux validate` | Check your code for errors |
+# Test locally
+npx @photon-ai/flux run --local
 
-<!-- --- -->
+# Deploy to production
+npx @photon-ai/flux run --prod
+```
+
+## 📦 Installation
 
-## Flux Number
+### Recommended: Global Installation
+
+For the best experience, install Flux globally:
+
+```bash
+npm install -g @photon-ai/flux
+# or
+bun add -g @photon-ai/flux
+```
 
-Message `+16286298650` with you phone number to text the LangChain agent that you built. 
+Then run commands directly:
 
-<!-- --- -->
+```bash
+flux login
+flux run --local
+flux run --prod
+```
 
-## Log in
+### Alternative: Use npx (No Installation Required)
 
-Authentication is based on iMessage: 
-- The user (client) sends a code to the Flux number to prove phone ownership. 
-- The server generates a UUID per login attempt. It then waits for the iMessage text from the client with the UUID. Once verified, it will issue a token. 
-- Credentials (token, phone, timestamp) are saved to credentials.json. This way, the user only has to log in once. 
+You can use Flux without installing it by using `npx` or `bunx`:
 
-<!-- --- -->
+```bash
+npx @photon-ai/flux login
+npx @photon-ai/flux run --local
+// or
+bunx @photon-ai/flux login
+bunx @photon-ai/flux run --local
+```
 
-## Usage 
+> **Note:** When using `npx` or `bunx`, there's no need to install the package first. `npx` or `bunx` will download and execute it automatically.
 
-### Step 1: Create LangChain Agent
+### Local Installation (For Development)
 
-Create an `agent.ts` file with your LangChain agent. Make sure to have `export default agent`. Below is one simple example:
+If you're integrating Flux into a project:
 
+```bash
+npm install @photon-ai/flux
+# or
+bun add @photon-ai/flux
 ```
+
+## 📖 Usage Guide
+
+### Step 1: Create Your LangChain Agent
+
+Create an `agent.ts` file with your LangChain agent. Make sure to have `export default agent`. Here's a simple example:
+
+```typescript
 // agent.ts
 export default {
   async invoke({ message }: { message: string }) {
@@ -83,13 +104,19 @@ export default {
 };
 ```
 
-### Step 2: Login
+### Step 2: Authenticate with iMessage
 
-Authenticate with your phone number and iMessage: 
+Authenticate with your phone number and iMessage:
 
-```
+```bash
+flux login
+# or
 npx @photon-ai/flux login
+```
 
+**Example session:**
+
+```
 Enter your phone number (e.g. +15551234567): +1234567890
 [FLUX] Requesting verification code...
 [FLUX] Verification code: d33gwu
@@ -99,40 +126,52 @@ Enter your phone number (e.g. +15551234567): +1234567890
 [FLUX] Successfully logged in as +1234567890
 ```
 
-If already logged in: 
+If already logged in:
 
 ```
-npx @photon-ai/flux login
-
 [FLUX] Already logged in as +1234567890
 ```
 
-Log out: 
+To log out:
 
+```bash
+flux logout
 ```
-npx @photon-ai/flux logout
 
+```
 [FLUX] Logged out.
 ```
 
-### Step 3: Validate
+### Step 3: Validate Your Agent
 
-Validate that your agent works and exports correctly: 
+Validate that your agent works and exports correctly:
 
-```
+```bash
+flux validate
+# or
 npx @photon-ai/flux validate
+```
+
+**Output:**
 
+```
 [FLUX] Validating agent.ts...
 [FLUX] Agent is valid!
 ```
 
-### Step 4: Testing Mode
+### Step 4: Test Locally (Development Mode)
 
-Test your agent through your terminal (no iMessage connection): 
+Test your agent through your terminal (no iMessage connection):
 
-```
+```bash
+flux run --local
+# or
 npx @photon-ai/flux run --local
+```
+
+**Interactive session:**
 
+```
 [FLUX] Welcome to Flux! Your agent is loaded.
 [FLUX] Type a message to test it. Press Ctrl+C to exit.
 
@@ -141,122 +180,191 @@ You: Hello!
 Agent: Hello! How can I assist you today?
 ```
 
-### Step 5: Live Connection
+### Step 5: Deploy to Production (Live iMessage)
 
-Run your agent locally and connect it to the iMessage bridge. When you message the FLUX number with your phone number, you will receive the output of your LangChain agent: 
+Run your agent locally and connect it to the iMessage bridge. When you message the Flux number (`+16286298650`) from your registered phone, you'll receive responses from your LangChain agent:
 
-```
+```bash
+flux run --prod
+# or
 npx @photon-ai/flux run --prod
+```
 
+**Output:**
+
+```
 [FLUX] Loading agent from agent.ts...
 [FLUX] Agent loaded successfully!
 [FLUX] Connected to server at fluxy.photon.codes:443
 [FLUX] Registered agent for +1234567890
 [FLUX] Agent running in production mode. Press Ctrl+C to stop.
 [FLUX] Messages to +1234567890 will be processed by your agent.
-
 ```
 
-<!-- --- -->
+Now text **`+16286298650`** from your phone to interact with your agent!
 
-## Why Flux
+## 🛠️ CLI Commands
 
-Right now, connecting agents to messaging platforms involves complex processes such as setting up servers, configuring webhooks, and dealing with platform APIs. Furthermore, most current options use SMS or WhatsApp, which is unintuitive for many users. 
+| Command | Description |
+|---------|-------------|
+| `flux` or `npx @photon-ai/flux` | Show help |
+| `flux whoami` | Check currently logged-in account |
+| `flux login` | Login and signup with phone number |
+| `flux logout` | Logout from current session |
+| `flux validate` | Check your agent code for errors |
+| `flux run --local` | Start development server (local testing mode) |
+| `flux run --prod` | Start with live iMessage bridge |
 
-Flux solves these problems in the following ways: 
+## 🔐 Authentication
 
-- **Deploy in < 5 seconds**: Link your LangChain agent to iMessage with a single command.
-- **Fully iMessage native**: Direct iMessage integration, not SMS or WhatsApp. 
-- **Zero Infrastructure**: No servers to manage, webhooks to configure, or Apple Developer account needed. 
-- **Open source**: Fully community driven.
-- **Free to use**: No subscription fees.
+Authentication is based on iMessage to ensure secure and simple access:
 
-<!-- --- -->
+1. **Code Generation**: The server generates a unique UUID for each login attempt
+2. **Phone Verification**: You send the verification code to the Flux number (`+16286298650`) via iMessage to prove phone ownership
+3. **Token Issuance**: Once verified, the server issues an authentication token
+4. **Persistent Login**: Credentials (token, phone, timestamp) are saved to `credentials.json`, so you only need to log in once
 
-## Examples
+## Proactive Messaging 
 
-### Echo Bot (No LLM)
+Agents can initiate conversations without waiting for a user message.  In production mode, `onInit` receives a sendMessage function that lets your agent send messages at any time.
 
 ```
-// agent.ts
+let sendMessage: (to: string, text: string) => Promise<boolean>;
+
 export default {
-  async invoke({ message }: { message: string }) {
-    return `You said: ${message}`;
-  }
+  async onInit(send) {
+    sendMessage = send;
+    // Now you can call sendMessage() anywhere in your agent
+  },
+  // ...
 };
 ```
 
-### ChatGPT Bot
+**Note**: Proactive messaging is only available in production mode `(flux run --prod`). In local mode, `onInit` is called without arguments.
+
+## 💡 Examples
+
+### Weather Agent
+
+An agent with a weather tool (returns mock data). 
+
+```typescript
+import * as z from "zod";
+import { createAgent, tool } from "langchain";
 
+const getWeather = tool(
+  ({ city }) => `It's always sunny in ${city}!`,
+  {
+    name: "get_weather",
+    description: "Get the weather for a given city",
+    schema: z.object({
+      city: z.string(),
+    }),
+  },
+);
+
+const agent = createAgent({
+  model: "claude-sonnet-4-5-20250929",
+  tools: [getWeather],
+});
+
+export default agent
 ```
+
+### Chatbot with Memory
+
+An advanced agent with memory:
+
+```typescript
 // agent.ts
+import "dotenv/config";
 import { ChatOpenAI } from "@langchain/openai";
-import { SystemMessage, HumanMessage } from "@langchain/core/messages";
+import { HumanMessage, AIMessage, SystemMessage } from "@langchain/core/messages";
 
 const llm = new ChatOpenAI({ modelName: "gpt-4o-mini" });
+const history: Array<HumanMessage | AIMessage> = [];
 
 export default {
   async invoke({ message }: { message: string }) {
+    history.push(new HumanMessage(message));
+    
     const response = await llm.invoke([
       new SystemMessage("You are a helpful assistant. Be concise."),
-      new HumanMessage(message),
+      ...history,
     ]);
-    return response.content as string;
+    
+    const reply = response.content as string;
+    history.push(new AIMessage(reply));
+    
+    // Keep last 20 messages to avoid token limits
+    if (history.length > 20) {
+      history.splice(0, 2);
+    }
+    
+    return reply;
   }
 };
 ```
 
-### Chatbot with tools
+##  Why Flux?
 
-```
-// agent.ts
-import { ChatOpenAI } from "@langchain/openai";
-import { tool } from "@langchain/core/tools";
-import { createReactAgent } from "@langchain/langgraph/prebuilt";
-import { z } from "zod";
+Connecting agents to messaging platforms traditionally involves complex processes like setting up servers, configuring webhooks, and dealing with platform APIs. Most solutions rely on SMS or WhatsApp, which can be unintuitive for many users.
 
-const calculator = tool(
-  async ({ expression }: { expression: string }) => {
-    return String(eval(expression));
-  },
-  {
-    name: "calculator",
-    description: "Evaluate a math expression",
-    schema: z.object({ expression: z.string() }),
-  }
-);
+**Flux solves these problems:**
 
-const getTime = tool(
-  async () => new Date().toLocaleTimeString(),
-  {
-    name: "get_time",
-    description: "Get the current time",
-    schema: z.object({}),
-  }
-);
+- **Deploy in < 5 seconds** — Link your LangChain agent to iMessage with a single command
+- **Fully iMessage native** — Direct iMessage integration, not SMS or WhatsApp
+- **Zero Infrastructure** — No servers to manage, webhooks to configure, or Apple Developer account needed
+- **Open source** — Fully community-driven and transparent
+- **Free to use** — No subscription fees or hidden costs
 
-const llm = new ChatOpenAI({ modelName: "gpt-4o-mini" });
-const agent = createReactAgent({ llm, tools: [calculator, getTime] });
+## 👤 Single-User Design
 
-export default {
-  async invoke({ message }: { message: string }) {
-    const result = await agent.invoke({ messages: [{ role: "user", content: message }] });
-    return result.messages[result.messages.length - 1].content as string;
-  }
-};
-```
+**Important:** Flux is designed for personal use and development. When you deploy an agent with Flux, **only your registered phone number** can interact with it via iMessage. This means:
 
-<!-- --- -->
+- ✅ Perfect for personal assistants and prototypes
+- ✅ Great for testing and development
+- ✅ Simple single-user experience
+- ❌ Not designed for multi-user conversations
+- ❌ No enterprise-level user management
 
-## Requirements
+### Need Enterprise Support?
 
-- **Node.js** 18+ (for the CLI)
-- **Python** 3.9+ (for the agent)
-- **LLM Keys (e.g. OpenAI API key)**
+For **enterprise-level iMessage agents** with advanced features, consider our [Advanced iMessage Kit](https://github.com/photon-hq/advanced-imessage-kit):
 
-<!-- --- -->
+- **Multi-user support** — Handle thousands of users simultaneously
+- **Dedicated phone line** — Get your own iMessage number
+- **Enterprise features** — Advanced conversation management and analytics
+- **Production-ready** — Enhanced stability and performance
+- **More functionalities** — Additional tools and integrations
 
+[**Explore Advanced iMessage Kit →**](https://github.com/photon-hq/advanced-imessage-kit)
 
-<div align="center">
+## ⚙️ Requirements
+
+- **Node.js** 18+ or **Bun** (for the CLI)
+- **Python** 3.9+ (for the agent, if using Python-based LangChain)
+- **LLM API Keys** (e.g., OpenAI API key for GPT-powered agents)
+
+## 🤝 Contributing
+
+We welcome contributions! Flux is fully open source and community-driven. Feel free to:
+
+- 🐛 [Report bugs](https://github.com/photon-hq/flux/issues)
+- 💡 [Request features](https://github.com/photon-hq/flux/issues)
+- 🔧 Submit pull requests
+- ⭐ Star the repository
+
+## 💬 Support
+
+- **Discord**: Join our community at [discord.gg/bZd4CMd2H5](https://discord.gg/bZd4CMd2H5)
+- **Issues**: Report problems on [GitHub Issues](https://github.com/photon-hq/flux/issues)
+- **Documentation**: Check out this README for comprehensive guides
+
+## 📄 License
+
+MIT License - see the [LICENSE](./LICENSE) file for details.
+
+<br /><div align="center">
   <sub>Built with ⚡ by <a href="https://photon.codes">Photon</a></sub>
-</div>
+</div>

package/dist/index.js

@@ -52148,7 +52148,8 @@ var FluxClient = class {
   async startMessageStream() {
     if (!this.client) return;
     (async () => {
-      for await (const [message] of this.client.FluxService.messageStream) {
+      const stream = this.client.FluxService.messageStream;
+      for await (const [message] of stream) {
         if ("ack" in message) {
           console.log(`[FLUX] Received ack: ${message.ack}`);
         } else {
@@ -52384,7 +52385,8 @@ async function loadAgent(agentPath) {
   }
   const moduleUrl = url.pathToFileURL(agentPath).href;
   const agentModule = await import(moduleUrl);
-  return agentModule.default;
+  const agent = agentModule.default;
+  return agent;
 }
 
 // src/index.ts
@@ -52418,6 +52420,9 @@ async function runLocal() {
     process.exit(1);
   }
   const agent = await loadAgent(agentPath);
+  if (agent.onInit) {
+    await agent.onInit();
+  }
   console.log("\n[FLUX] Welcome to Flux! Your agent is loaded.");
   console.log("[FLUX] Type a message to test it. Press Ctrl+C to exit.\n");
   const rl = readline__namespace.createInterface({
@@ -52441,12 +52446,18 @@ async function runLocal() {
       } catch (error) {
         console.log(`[FLUX] Error: ${error.message}
 `);
+        if (agent.onError) {
+          await agent.onError(error);
+        }
       }
       askQuestion();
     });
   };
-  rl.on("close", () => {
+  rl.on("close", async () => {
     console.log("\n[FLUX] Goodbye!");
+    if (agent.onShutdown) {
+      await agent.onShutdown();
+    }
     process.exit(0);
   });
   askQuestion();
@@ -52484,11 +52495,18 @@ async function runProd() {
   });
   await flux.connect();
   await flux.register();
+  if (agent.onInit) {
+    console.log("[FLUX] Initializing agent with proactive messaging support...");
+    await agent.onInit((to, text) => flux.sendMessage(to, text));
+  }
   console.log("[FLUX] Agent running in production mode. Press Ctrl+C to stop.");
   console.log(`[FLUX] Messages to ${phoneNumber} will be processed by your agent.
 `);
   process.on("SIGINT", async () => {
     console.log("\n[FLUX] Shutting down...");
+    if (agent.onShutdown) {
+      await agent.onShutdown();
+    }
     await flux.disconnect();
     process.exit(0);
   });