hyperstack-core 1.0.0 → 1.2.0

package/README.md

@@ -91,6 +91,10 @@ const blockers = await builder.tools.hs_blockers({ slug: "deploy-prod" });
 # Initialize with multi-agent template
 npx hyperstack-core init openclaw-multiagent
 
+# Auto-extract cards from text (zero LLM cost)
+npx hyperstack-core ingest project.txt
+echo "We use Next.js 14 and PostgreSQL" | npx hyperstack-core ingest -
+
 # Store cards
 npx hyperstack-core store --slug "use-clerk" --title "Use Clerk" --type decision
 

package/adapters/openclaw.js

@@ -176,12 +176,79 @@ function createOpenClawAdapter(opts = {}) {
           cards,
         };
       },
+
+      /**
+       * Auto-extract cards from raw text (conversation, project description).
+       * Finds preferences, people, decisions, tech stack mentions.
+       * Zero LLM cost. Best for onboarding.
+       */
+      async hs_ingest({ text }) {
+        if (!text || text.trim().length === 0) {
+          return { text: "Error: text parameter required", cards: [] };
+        }
+
+        const result = await client.ingest(text);
+        const cards = result.cards || [];
+
+        return {
+          text: `✅ Created ${cards.length} cards from ${text.length} chars of text:\n` +
+            cards.map(c => `  [${c.slug}] ${c.title} (${c.cardType})`).join("\n"),
+          cards,
+          count: cards.length,
+        };
+      },
     },
 
     /**
      * Hook: called when agent session starts.
      * Registers the agent and loads relevant context.
      */
+      /**
+       * Check for cards directed at this agent from other agents.
+       * Enables cross-agent coordination via shared memory.
+       */
+      async hs_inbox({ since } = {}) {
+        const result = await client.inbox({ since });
+        const cards = result.cards || [];
+        if (!cards.length) {
+          return { text: `No messages for agent "${agentId}".`, cards: [] };
+        }
+        return {
+          text: `${cards.length} message(s) for "${agentId}":\n` +
+            cards.map(c => `  [${c.slug}] ${c.title}${c.body ? `\n    ${c.body.slice(0, 150)}` : ""}`).join("\n"),
+          cards,
+        };
+      },
+
+      /**
+       * Register a webhook for real-time notifications. Requires Team plan.
+       */
+      async hs_webhook({ url, events, secret } = {}) {
+        if (!url) return { text: "Error: url required" };
+        const result = await client.registerWebhook({
+          url,
+          events: events ? events.split(",").map(e => e.trim()) : ["*"],
+          secret,
+        });
+        if (result.error) return { text: `Webhook error: ${result.error}` };
+        return { text: `Webhook registered for agent "${agentId}".\nURL: ${url}\nID: ${result.id}` };
+      },
+
+      /**
+       * List all registered webhooks for this account.
+       */
+      async hs_webhooks() {
+        const result = await client.listWebhooks();
+        const hooks = result.webhooks || [];
+        if (!hooks.length) return { text: "No webhooks registered." };
+        return {
+          text: `${hooks.length} webhook(s):\n` +
+            hooks.map(h => `  [${h.agentId}] ${h.url} — events: ${h.events.join(", ")}`).join("\n"),
+          hooks,
+        };
+      },
+    },
+
     async onSessionStart({ agentName, agentRole }) {
       // Register this agent in the graph
       await client.registerAgent({

package/cli.js

@@ -42,6 +42,7 @@ Commands:
   decide              Record a decision (use --slug, --title, --rationale)
   blockers <slug>     Show what blocks a card
   graph <slug>        Traverse graph from a card
+  ingest <file|text>  Auto-extract cards from text (zero LLM cost)
   list                List all cards
 
 Templates:
@@ -61,6 +62,8 @@ Examples:
   npx hyperstack-core store --slug "use-clerk" --title "Use Clerk for auth" --type decision
   npx hyperstack-core blockers deploy-prod
   npx hyperstack-core graph auth-api --depth 2
+  npx hyperstack-core ingest project.txt
+  echo "We use Next.js 14 and PostgreSQL" | npx hyperstack-core ingest -
 `);
 }
 
@@ -480,6 +483,47 @@ async function run() {
     return;
   }
 
+  if (command === "ingest") {
+    let text = "";
+    const input = args[1];
+
+    if (!input) {
+      console.error("Usage: npx hyperstack-core ingest <file|text|->");
+      console.error("  file   Read from file");
+      console.error("  -      Read from stdin");
+      console.error("  text   Treat argument as raw text");
+      process.exit(1);
+    }
+
+    if (input === "-") {
+      // Read from stdin
+      const chunks = [];
+      process.stdin.on("data", chunk => chunks.push(chunk));
+      await new Promise(resolve => process.stdin.on("end", resolve));
+      text = Buffer.concat(chunks).toString("utf-8");
+    } else if (existsSync(input)) {
+      // Read from file
+      text = readFileSync(input, "utf-8");
+    } else {
+      // Treat as raw text
+      text = input;
+    }
+
+    if (!text || text.trim().length === 0) {
+      console.error("Error: No text provided");
+      process.exit(1);
+    }
+
+    console.log(`Ingesting ${text.length} chars...`);
+    const result = await client.ingest(text);
+    const cards = result.cards || [];
+    console.log(`\n✅ Created ${cards.length} cards:\n`);
+    for (const c of cards) {
+      console.log(`  [${c.slug}] ${c.title} (${c.cardType || "general"})`);
+    }
+    return;
+  }
+
   if (command === "list") {
     const result = await client.list();
     console.log(`HyperStack: ${result.count ?? 0}/${result.limit ?? "?"} cards (plan: ${result.plan || "?"})\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperstack-core",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Typed graph memory for AI agents. Replace GOALS.md with queryable cards + relations. Works with OpenClaw, Claude Desktop, Cursor.",
   "type": "module",
   "main": "index.js",

package/src/client.js

@@ -129,6 +129,17 @@ class HyperStackClient {
     return this._request("DELETE", `/api/cards?workspace=${this.workspace}&id=${slug}`);
   }
 
+  /**
+   * Auto-extract cards from raw text.
+   * Finds preferences, people, decisions, tech stack mentions using regex.
+   * Zero LLM cost. Great for onboarding.
+   * @param {string} text — raw conversation or project description
+   * @returns {Promise<{cards: Array, count: number}>}
+   */
+  async ingest(text) {
+    return this._request("POST", `/api/ingest?workspace=${this.workspace}`, { text });
+  }
+
   // ─── Graph ───────────────────────────────────────────
 
   /**
@@ -242,6 +253,48 @@ class HyperStackClient {
    * @param {string} agent.role — what this agent does
    * @param {string[]} [agent.owns] — slugs this agent owns
    */
+  /**
+   * Check for cards directed at this agent by other agents.
+   * Enables cross-agent coordination via shared memory.
+   * @param {object} [opts]
+   * @param {string} [opts.since] — ISO timestamp, only cards after this time
+   * @returns {Promise<{cards: Array}>}
+   */
+  async inbox(opts = {}) {
+    const agentId = this.agentId;
+    if (!agentId) throw new Error("agentId required for inbox");
+    let url = `/api/cards?workspace=${this.workspace}&targetAgent=${agentId}`;
+    if (opts.since) url += `&since=${encodeURIComponent(opts.since)}`;
+    return this._request("GET", url);
+  }
+
+  /**
+   * Register a webhook to receive real-time notifications.
+   * Agent gets notified when cards are directed at it. Requires Team plan.
+   * @param {object} webhook
+   * @param {string} webhook.url — URL to receive POST events
+   * @param {string[]} [webhook.events] — events to listen for (default: all)
+   * @param {string} [webhook.secret] — HMAC secret for signature verification
+   * @returns {Promise<{id: string}>}
+   */
+  async registerWebhook(webhook) {
+    return this._request("POST", `/api/agent-webhooks`, {
+      agentId: this.agentId,
+      url: webhook.url,
+      events: webhook.events || ["*"],
+      workspace: this.workspace,
+      secret: webhook.secret || undefined,
+    });
+  }
+
+  /**
+   * List all registered webhooks for this account.
+   * @returns {Promise<{webhooks: Array}>}
+   */
+  async listWebhooks() {
+    return this._request("GET", `/api/agent-webhooks`);
+  }
+
   async registerAgent(agent) {
     const links = [];
     if (agent.owns) {