optic-agent 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OPTIC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opticagents/optic-agent/main/brand/logo-light.png">
+    <img src="https://raw.githubusercontent.com/opticagents/optic-agent/main/brand/logo-dark.png" width="150" alt="OPTIC">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">optic-agent</h1>
+
+<p align="center"><b>Balance beyond noise.</b> OPTIC in your terminal.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/optic-agent"><img src="https://img.shields.io/npm/v/optic-agent?color=111111&label=npm" alt="npm"></a>
+  <a href="https://github.com/opticagents/optic-agent"><img src="https://img.shields.io/badge/github-optic--agent-111111?logo=github" alt="GitHub"></a>
+  <a href="https://opticagents.com"><img src="https://img.shields.io/badge/web-opticagents.com-111111" alt="Website"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-555555" alt="MIT"></a>
+</p>
+
+OPTIC is a portfolio agent on Robinhood Chain built on the barbell strategy. Most of a portfolio sits on the **safe side** (tokenized stocks and ETFs, USDG); a small share rides the **meme side** (Pons memecoins). Every five minutes six on-chain readings become a **market score** from 1 (panic) to 10 (euphoria). In euphoria it takes meme profit into stocks, in panic it buys memes back with safe-side money, in between it only moves on a large drift.
+
+This package only **reads**. It holds no keys and signs nothing. Rebalancing happens in the web terminal at **[opticagents.com/app](https://opticagents.com/app)**, where your own wallet confirms every step.
+
+## Use
+
+```sh
+npx optic-agent                 # the market score, its six readings and the note
+npx optic-agent record          # the four house books and what Optic AI did
+npx optic-agent picks           # memes that pass the rug scan right now
+npx optic-agent bar 0x…         # safe side, meme side and the rebalance plan for any wallet
+npx optic-agent watch           # the score, refreshed every minute
+```
+
+Or install once and run `optic`:
+
+```sh
+npm i -g optic-agent
+optic
+```
+
+`OPTIC_URL` points the CLI at another OPTIC server, for example your own: `OPTIC_URL=http://127.0.0.1:4350 optic`.
+
+## The score
+
+| Reading | Weight |
+|---|---|
+| Pons volume against its own baseline | 25% |
+| Share of Pons volume that is buying | 25% |
+| Pons launch rate | 10% |
+| ETH 24 h move | 15% |
+| SPY / QQQ token 24 h move | 10% |
+| Tone of ETH and SPY headlines (VADER) | 15% |
+
+Code computes the score, the rule and the picks. Claude only writes the short note under the number.
+
+## The rule
+
+- Score 8 or higher and the meme side over target: trim it back to target.
+- Score 3 or lower and the meme side under target: top it up to target, spending USDG first.
+- Anything in between: act only on a drift beyond the band, and never against the score.
+- Memes it may buy are the busiest Pons tokens of the last 24 h, older than 6 h, still on their curve, with rug risk under 30.
+
+## Honest limits
+
+The score describes the last few hours; it is not a forecast. Four public paper books, opened the same day with the same money, show whether following it helps. Stock tokens follow their stocks through on-chain pools and are not shares. Not financial advice. Not affiliated with Robinhood, Uniswap or Pons.
+
+## License
+
+MIT

package/bin/optic.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// optic: the OPTIC terminal for your shell. It only reads: no keys, no signing.
+// Rebalancing a wallet is signed in the web terminal, where the wallet itself confirms each step.
+const VERSION = "1.0.1";
+const SERVER = (process.env.OPTIC_URL || "https://opticagents.com").replace(/\/$/, "");
+
+const tty = (process.stdout.isTTY || !!process.env.FORCE_COLOR) && !process.env.NO_COLOR;
+const c = (code) => (s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const gold = c("38;2;230;194;154"), safe = c("38;2;157;184;236"), wild = c("38;2;255;148;102"), ok = c("38;2;134;217;168"), bad = c("38;2;255;138;114");
+const dim = c("2"), bold = c("1");
+const out = (s = "") => process.stdout.write(s + "\n");
+const strip = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, "");
+const pad = (s, n, right = false) => { const g = Math.max(0, n - strip(s).length); return right ? " ".repeat(g) + s : s + " ".repeat(g); };
+const usd = (x, d = 2) => (x == null ? "–" : "$" + Number(x).toLocaleString("en-US", { minimumFractionDigits: d, maximumFractionDigits: d }));
+const pct = (x, d = 2) => (x == null ? "–" : (x > 0 ? "+" : "") + Number(x).toFixed(d) + "%");
+const signed = (x, s) => (x >= 0 ? ok(s) : bad(s));
+const ago = (t) => { if (!t) return "–"; const s = Math.round((Date.now() - t) / 1000); return s < 60 ? `${s}s ago` : s < 3600 ? `${Math.round(s / 60)}m ago` : s < 86400 ? `${Math.round(s / 3600)}h ago` : `${Math.round(s / 86400)}d ago`; };
+const zoneCol = (k) => (k === "panic" ? safe : k === "euphoria" ? wild : (s) => s);
+
+async function get(path) {
+  let r;
+  try { r = await fetch(SERVER + path, { headers: { "user-agent": "optic-cli/" + VERSION } }); }
+  catch { throw new Error(`Cannot reach ${SERVER}. Check your connection, or set OPTIC_URL.`); }
+  const j = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(j.error || `HTTP ${r.status}`);
+  return j;
+}
+
+function head(title) {
+  out();
+  out(`  ${gold("◠")} ${bold("OPTIC")} ${dim("·")} ${title}`);
+  out(dim("  " + "─".repeat(58)));
+}
+
+// a 1–10 scale with the needle where the score sits
+function meter(score, w = 46) {
+  const i = Math.round(((score - 1) / 9) * (w - 1));
+  let bar = "";
+  for (let k = 0; k < w; k++) { const ch = k === i ? "●" : "─"; const at = k / (w - 1); bar += k === i ? bold(ch) : at < 0.23 ? safe(ch) : at > 0.77 ? wild(ch) : dim(ch); }
+  return `  ${bar}\n  ${dim(pad("1 panic", 12) + pad("3", 12) + pad("8", 12) + pad("10", 10, true))}`;
+}
+
+const PART = { memeVolume: "Meme volume", memeBuyShare: "Meme buying", launches: "New launches", eth: "ETH", stocks: "Stock tokens", news: "Headlines" };
+function partVal(k, p) {
+  if (p.value == null) return "–";
+  return k === "news" ? (p.value > 0 ? "+" : "") + p.value.toFixed(2) : k === "memeVolume" ? `${p.value} ETH/h` : k === "memeBuyShare" ? `${p.value}%` : k === "launches" ? `${p.value}/h` : pct(p.value, 2);
+}
+
+async function score() {
+  const s = await get("/api/state");
+  head("market score");
+  if (s.score == null) { out("  The first score lands a few minutes after the server starts."); return out(); }
+  out();
+  out(`  ${bold(gold(s.score.toFixed(1)))}${dim("/10")}   ${zoneCol(s.zone.key)(s.zone.label.toUpperCase())}   ${dim("updated " + ago(s.scoreAt))}`);
+  out();
+  out(meter(s.score));
+  out();
+  out("  " + (s.why || `${s.zone.label}: ${s.zone.act}.`));
+  out();
+  out(dim("  READING            VALUE           HEAT        WEIGHT"));
+  for (const [k, p] of Object.entries(s.parts || {})) {
+    const h = Math.round((p.heat || 0) * 10), heat = "▮".repeat(h) + dim("▯".repeat(10 - h));
+    out(`  ${pad(PART[k] || k, 19)}${pad(partVal(k, p), 16)}${p.heat > 0.6 ? wild(heat) : p.heat < 0.4 ? safe(heat) : heat}  ${dim(Math.round(s.weights[k] * 100) + "%")}`);
+  }
+  out();
+}
+
+async function record() {
+  const s = await get("/api/state"), H = s.house || {};
+  head("the record");
+  out(dim(`  Four paper books of ${(s.start || 1000).toLocaleString()} USDG${s.houseStarted ? ", opened " + new Date(s.houseStarted).toLocaleDateString() : ""}. Live quotes, all fees in.`));
+  out();
+  out(dim("  BOOK              RETURN      EQUITY      RULE"));
+  for (const [k, b] of Object.entries(H)) out(`  ${pad(k === "barbell" ? gold(b.name) : b.name, 18)}${pad(signed(b.ret, pct(b.ret)), 12)}${pad(usd(b.equity), 12)}${dim(b.note)}`);
+  const t = H.barbell?.trades || [];
+  if (t.length) {
+    out();
+    out(dim(`  WHAT ${(H.barbell.name || "").toUpperCase()} DID`));
+    for (const x of t.slice(0, 8)) out(`  ${pad(dim(ago(x.t)), 10)}${pad(x.side === "buy" ? ok(x.side) : x.side === "sell" ? bad(x.side) : dim(x.side), 7)}${pad(usd(x.usd), 12)}${x.what}  ${dim(x.why)}`);
+  }
+  out();
+}
+
+async function picks() {
+  const s = await get("/api/state");
+  head("memes it may buy now");
+  out(dim("  Busiest Pons tokens of the last 24 h, older than 6 h, still on their curve, rug risk under 30."));
+  out();
+  if (!s.picks?.length) out("  No memecoin passes the scan right now.");
+  else {
+    out(dim("  TOKEN           24H VOLUME    RUG RISK   CA"));
+    for (const p of s.picks) out(`  ${pad(gold("$" + p.symbol), 16)}${pad(p.volEth + " ETH", 14)}${pad(p.risk + "/100", 11)}${dim(p.token)}`);
+  }
+  out(dim(`\n  scanned ${ago(s.picksAt)}`));
+  out();
+}
+
+async function bar(address, target) {
+  if (!/^0x[0-9a-fA-F]{40}$/.test(address || "")) throw new Error("Usage: optic bar <0x wallet address> [--target 20]");
+  const q = `/api/look?address=${address}` + (target != null ? `&target=${target}` : "");
+  if (tty) process.stdout.write(dim("  reading the wallet from the chain…") + "\r");
+  const [v, s] = await Promise.all([get(q), get("/api/state")]);
+  if (tty) process.stdout.write(" ".repeat(40) + "\r");
+  const h = v.holdings, total = h.safeUsd + h.memeUsd, share = total ? h.memeUsd / total : 0, tgt = v.policy.target;
+  head(`bar of ${address.slice(0, 6)}…${address.slice(-4)}`);
+  out();
+  out(`  ${bold(usd(total))} ${dim("on the bar")}   ${dim("score")} ${s.score?.toFixed(1) ?? "–"} ${zoneCol(s.zone?.key)(s.zone?.label || "")}`);
+  out();
+  const w = 46, cut = Math.round((1 - share) * w), tm = Math.round((1 - tgt) * w);
+  let line = ""; for (let k = 0; k < w; k++) line += k === tm ? gold("┃") : !total ? dim("─") : k < cut ? safe("█") : wild("█");
+  out("  " + line);
+  out(`  ${safe(total ? `safe ${((1 - share) * 100).toFixed(1)}%` : "safe –")}${" ".repeat(8)}${dim(`target ${Math.round(tgt * 100)}% meme`)}${" ".repeat(8)}${wild(`meme ${(share * 100).toFixed(1)}%`)}`);
+  out();
+  out(safe("  SAFE SIDE"));
+  if (!h.safe.length) out(dim("  no stock tokens or USDG"));
+  for (const x of h.safe) out(`  ${pad(x.sym, 10)}${pad(x.amount.toLocaleString("en-US", { maximumFractionDigits: 4 }), 16, true)}${pad(usd(x.usd), 14, true)}`);
+  out(wild("\n  MEME SIDE"));
+  if (!h.meme.length) out(dim("  no Pons memecoin traded in the last week"));
+  for (const x of h.meme) out(`  ${pad("$" + x.symbol, 26)}${pad(usd(x.usd), 14, true)}`);
+  out(dim(`\n  ETH for gas: ${h.eth.amount.toFixed(5)} (${usd(h.eth.usd)})`));
+  out();
+  const p = v.plan;
+  const title = p.action === "trim" ? `Take ${usd(p.usd)} of meme profit into the safe side` : p.action === "topup" ? `Buy ${usd(p.usd)} of memes back with safe-side money` : "Hold. The bar is where it should be.";
+  out(`  ${gold("THE PLAN")}  ${bold(title)}`);
+  out("  " + dim(p.reason));
+  p.steps.forEach((t, i) => out(`  ${gold(String(i + 1))}  ${t}`));
+  if (p.steps.length) out(`\n  Sign these steps with your wallet at ${gold(SERVER + "/app#bar")}`);
+  out();
+}
+
+function help() {
+  out();
+  out(`  ${gold("◠")} ${bold("OPTIC")} ${dim("v" + VERSION + " · balance beyond noise")}`);
+  out();
+  out(`  ${bold("optic")}                    the live score, its six readings and the note`);
+  out(`  ${bold("optic record")}             the four house books and what Optic did`);
+  out(`  ${bold("optic picks")}              memes that pass the rug scan right now`);
+  out(`  ${bold("optic bar")} ${dim("<0x…>")}          holdings and the rebalance plan for a wallet`);
+  out(`  ${bold("optic watch")}              the score, refreshed every minute`);
+  out();
+  out(dim("  Read-only. No keys, no signing: trades are signed in the web terminal."));
+  out(dim(`  Server: ${SERVER} (override with OPTIC_URL)`));
+  out();
+}
+
+async function watch() {
+  const tick = async () => { if (tty) process.stdout.write("\x1b[2J\x1b[H"); try { await score(); } catch (e) { out(bad("  " + e.message)); } out(dim("  refreshing every minute · ctrl+c to stop")); };
+  await tick(); setInterval(tick, 60_000);
+}
+
+const [cmd = "score", ...rest] = process.argv.slice(2);
+const flag = (n) => { const i = rest.indexOf("--" + n); return i < 0 ? null : rest[i + 1]; };
+const run = { score, record, picks, watch, bar: () => bar(rest[0], flag("target")), help, "--help": help, "-h": help, "--version": () => out(VERSION), "-v": () => out(VERSION) }[cmd];
+if (!run) { out(bad(`  Unknown command: ${cmd}`)); help(); process.exit(1); }
+Promise.resolve().then(run).catch((e) => { out(bad("\n  " + e.message + "\n")); process.exit(1); });

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "optic-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "OPTIC in your terminal: the live market score, the four house books, the meme picks and a read-only look at any wallet's safe side and meme side on Robinhood Chain.",
+  "type": "module",
+  "bin": { "optic": "bin/optic.mjs" },
+  "files": ["bin", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "homepage": "https://opticagents.com",
+  "repository": { "type": "git", "url": "git+https://github.com/opticagents/optic-agent.git" },
+  "bugs": { "url": "https://github.com/opticagents/optic-agent/issues" },
+  "keywords": ["optic", "robinhood-chain", "pons", "memecoin", "portfolio", "agent", "cli", "rebalance", "barbell", "uniswap", "usdg"],
+  "author": "OPTIC (https://opticagents.com)",
+  "license": "MIT"
+}