@atlaso-labs/opencode 0.1.0

package/AGENTS.md

@@ -0,0 +1,68 @@
+<!--
+This is the Atlaso memory instruction block for OpenCode. It uses OpenCode's
+native instructions format (AGENTS.md). Add it ONE of these ways:
+  1. Save it at <repo>/.opencode/atlaso/AGENTS.md and point opencode.json at it
+     via the "instructions" array, e.g. "instructions": [".opencode/atlaso/AGENTS.md"]
+     (this is what the template opencode.json does), OR
+  2. Append the section below to your project-root AGENTS.md (or
+     ~/.config/opencode/AGENTS.md for global).
+Docs: https://opencode.ai/docs/rules/
+-->
+
+# Using Atlaso memory well
+
+Atlaso is the user's long-term memory. Two things are already automatic, so most
+of the time you do nothing:
+
+- **Auto-recall:** before each of your turns, relevant memories are injected into
+  your context as an `=== Atlaso Memory ===` block. Trust it; don't re-search what
+  it already gave you.
+- **Auto-capture:** when a turn finishes, what the user told you is saved
+  automatically. You rarely need to save things by hand.
+
+When in doubt, do less: a smaller, higher-signal memory is worth more than volume.
+The judgment calls below are about *what* is worth remembering and *where* it
+belongs (personal vs project) — apply them as you work.
+
+## What's worth remembering (default: don't)
+
+Save **durable** things:
+- decisions **and the reason** behind them
+- the user's stable preferences and working style
+- hard-won gotchas ("X silently fails unless Y")
+- stable facts/commands (ports, endpoints, conventions)
+
+Don't save: transient state ("ran the tests just now"), secrets/tokens,
+restatements of files already in the repo, or anything that's just in this turn's
+context.
+
+## Personal vs project — Atlaso's dual memory
+
+Atlaso keeps two memories. Route deliberately:
+- **Personal** (follows the user across every project/tool): cross-project
+  preferences, identity, working style. → "true in every repo."
+- **Project** (this repo only): architecture, repo-specific decisions and gotchas.
+  → "true only here."
+
+Rule of thumb: *would this still be true in a different project?* Yes → personal.
+No → project.
+
+## Trust the injected memories
+
+The automatic `=== Atlaso Memory ===` block usually has what you need — use it,
+and **don't over-rely on it either**: if the user references a past decision, or
+you're about to do something that might contradict an earlier choice, weigh what
+the block actually says rather than assuming.
+
+## When memory looks wrong
+
+If an injected memory is clearly outdated or contradicted by the current
+conversation, prefer what the user just told you and note the correction so the
+newer fact is what gets captured. Supersede rather than piling up contradictions.
+
+## Good vs skip
+
+- ✅ "Use pnpm, never npm — the user's standard across all projects." *(personal)*
+- ✅ "Brain server runs on port 8800; recall is `GET /v1/recall`." *(project)*
+- ✅ "Signing key must be single-line in CI or it errors." *(hard-won gotcha)*
+- ⏭️ "Compiled the app and the tests passed." *(ephemeral — skip)*

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atlaso Labs Inc.
+
+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

@@ -0,0 +1,140 @@
+# Atlaso × OpenCode
+
+Long-term memory for [OpenCode](https://opencode.ai) — recalls what you've
+decided and remembers what matters, across sessions, projects, and tools.
+
+This is a **pure-TypeScript, bun-native OpenCode plugin**. No Python, no local
+engine: the plugin only does HTTP to the Atlaso brain's `/v1/*` API. The
+intelligence — retrieval, the conflict gate, the worth-keeping judgment — stays
+on the server. Memory is **fail-open**: a hook error never breaks an OpenCode
+turn.
+
+## What you get
+
+| Piece | OpenCode mechanism | What it does |
+|---|---|---|
+| **Auto-recall** | plugin `chat.message` hook | Before each of your turns, recalled memory is injected as a synthetic text part so the model sees it. |
+| **Auto-capture** | plugin `event` hook on `session.idle` | When a turn finishes, the user's statement is saved (scrubbed for secrets first). |
+| **Instructions** | `AGENTS.md` (native rules format) | Teaches the model how to use memory well (personal vs project, what's worth keeping). |
+| **Skill** | `.opencode/skills/memory/SKILL.md` | Curation judgment, auto-discovered by OpenCode. |
+
+The automatic loop is the value and comes **entirely from the plugin hooks**.
+
+> **Model-invoked memory tools** (`recall` / `remember` / `forget` / `recent` /
+> `status` over MCP) are a **remote-MCP follow-up shipped at deploy** — this
+> connector intentionally ships **no** local Python MCP. The hooks above don't
+> depend on them.
+
+## Install
+
+Atlaso memory is one npm package: `@atlaso-labs/opencode`.
+
+### Recommended — add it to your `opencode.json`
+
+```bash
+bun add -d @atlaso-labs/opencode
+```
+
+then list it in your project (or global `~/.config/opencode/`) `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@atlaso-labs/opencode"],
+  "instructions": [".opencode/atlaso/AGENTS.md"]
+}
+```
+
+The `opencode.json` in this folder is a ready-to-use template. Copy `AGENTS.md`
+to `.opencode/atlaso/AGENTS.md` (or point `instructions` at wherever you keep it),
+and the `skills/memory/` folder to `.opencode/skills/memory/` so OpenCode
+auto-discovers the curation skill.
+
+### Dev — drop the plugin file in directly
+
+For local hacking you can skip npm and copy the entry into OpenCode's plugin
+directory ([docs](https://opencode.ai/docs/plugins/)):
+
+- **Project-local:** copy `src/index.ts` → `<repo>/.opencode/plugins/atlaso-memory.ts`
+- **Global:** copy it → `~/.config/opencode/plugins/atlaso-memory.ts`
+
+(Note the **plural** `plugins/` directory — that's the OpenCode convention. When
+copying the single file in, keep the `lib/` folder reachable next to it, or use
+the npm install above so the imports resolve.)
+
+### Sign in (first run)
+
+Memory is **cloud-linked**: on the first turn after install the plugin opens a
+browser to **authorize this device** (a one-time device-link flow that writes the
+shared `~/.atlaso/auth.json`). Approve it in the dashboard and memory starts
+syncing. Until then — or for a tool that isn't your active tool on the free plan
+— the plugin simply does nothing that turn (fail-open).
+
+OpenCode itself: `curl -fsSL https://opencode.ai/install | bash` (or
+`npm i -g opencode-ai`); provider auth via the TUI `/connect` or
+`opencode auth login`.
+
+## How it works
+
+```
+tools/opencode/
+  src/index.ts          plugin entry: chat.message (recall) + event/session.idle (capture)
+  src/connect-entry.ts  detached browser-authorize process (spawned on first run)
+  lib/                  tool-agnostic brain client, copied from the Cursor connector:
+    atlaso.ts             thin /v1/* HTTP client (recall/deposit/entitlement), fail-open
+    capture.ts            commodity heuristics (worth-keeping gate, scope, polarity, secret scrub)
+    project.ts            stable per-project key (git remote / path hash), read-only
+    entitlement.ts        cloud-linked vs local-only gate (free = 1 active tool/device)
+    state.ts              cached entitlement verdict (tool+device scoped)
+    connect.ts            device-link handshake → ~/.atlaso/auth.json
+    render.ts             builds the "=== Atlaso Memory ===" injection string
+    log.ts                opt-in debug log (ATLASO_DEBUG=1)
+  skills/memory/SKILL.md  curation judgment (auto-discovered)
+  AGENTS.md               memory instructions (native rules format)
+  opencode.json           install template
+  tests/                  bun tests (lib + plugin behavior, all with fakes — no network)
+```
+
+- **The dual memory** (the headline feature) is preserved: `personal` memories
+  follow the user across every project/tool; `project` memories stay isolated to
+  the repo (a stable key derived from the git remote, with strict cross-project
+  visibility). Nothing is ever written into your project folder.
+- **Auto-capture** rides `session.idle`, which carries only the sessionID — so the
+  plugin stashes the user's statement at `chat.message` and deposits it when the
+  turn goes idle. Assistant-snippet enrichment is a follow-up (see the `TODO` in
+  `src/index.ts`).
+- **Secrets never leave the machine**: captures are scrubbed client-side
+  (defense-in-depth; the server re-scrubs too).
+- **Graceful degradation**: a revoked or non-entitled tool keeps working and never
+  deletes memories — that's the shared cloud-linked/local-only state machine.
+
+## Honesty / caveats (verify on a live OpenCode before relying on these)
+
+- **Auto-capture is the documented, robust half.** It's a write-only side effect
+  on the documented `event`/`session.idle` hook — it depends on nothing fragile.
+- **Auto-recall injection is a community pattern.** Pushing a synthetic text part
+  onto `chat.message` `output.parts` is how working OpenCode memory plugins inject
+  AI-visible context today; a documented true-injection API is still an open
+  feature request, and some OpenCode builds have reportedly mis-rendered injected
+  parts. We only ever **add** a well-formed part and otherwise no-op, so a future
+  OpenCode never breaks because of us — but **confirm the block actually surfaces
+  to the model in your build**.
+- **The exact `session.idle` payload path is `event.properties.sessionID`** per
+  the current contract; confirm it live (a different shape just means no capture
+  that turn — still fail-open).
+- **Windows global-config path is unverified.** Project-level `<repo>/.opencode/`
+  works cross-OS; the documented global path is `~/.config/opencode`.
+
+## Dev / test
+
+```bash
+cd platform/tools/opencode
+bun install
+bun test          # all fakes, no network
+bun run typecheck # tsc --noEmit
+```
+
+`ATLASO_DEBUG=1` writes per-hook logs to `<atlaso dir>/atlaso-opencode-*.log`.
+Env escape hatches: `ATLASO_NO_CONNECT=1` (skip the browser-authorize),
+`ATLASO_SERVER` (point at a non-prod brain), `ATLASO_GLOBAL_PATH` (redirect
+`auth.json` + state for throwaway testing).

package/lib/atlaso.ts

@@ -0,0 +1,172 @@
+/**
+ * Thin Atlaso brain client for the Cursor plugin — bun-native, ZERO deps.
+ *
+ * Reads the SAME `~/.atlaso/auth.json` every Atlaso connector shares
+ * ({server, token, user_id, device_id}) and calls the brain's documented REST
+ * endpoints over the global `fetch`. The engine stays on the server; this only
+ * knows the URLs — the IP thin-client rule, in TypeScript.
+ *
+ * v1 is ONLINE-FIRST: no local cache / outbox / sync (deferred — see README).
+ * Every call is FAIL-OPEN (memory must never break a Cursor turn): callers get
+ * `[]` / `false` on any error — never a throw. A REACHED-but-rejected token
+ * (HTTP 401/403) is the one authoritative signal: we retire auth.json so the next
+ * session re-authorizes (mirrors the Python client's AuthRejected handling).
+ */
+import { readFileSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface Auth {
+  server: string;
+  token: string;
+  user_id?: string;
+  device_id?: string;
+}
+
+export interface RecallResult {
+  id?: string;
+  content?: string;
+  scope?: string;
+  has_disagreement?: boolean;
+  conflict_peers?: unknown[];
+  tags?: string[];
+}
+
+export interface DepositItem {
+  client_id: string;
+  text: string;
+  polarity: string;
+  evidence_grade: string;
+  scope_note: string | null;
+  tags: string[];
+}
+
+const RECALL_TIMEOUT_MS = 8000;
+const DEPOSIT_TIMEOUT_MS = 15000;
+
+export function atlasoDir(): string {
+  return (
+    process.env.ATLASO_GLOBAL_PATH ||
+    process.env.ATLASO_PATH ||
+    join(homedir(), ".atlaso")
+  );
+}
+
+export function authPath(): string {
+  return join(atlasoDir(), "auth.json");
+}
+
+export function defaultServer(): string {
+  return process.env.ATLASO_SERVER || "https://api.atlaso.ai";
+}
+
+/** {server, token, user_id, device_id} from auth.json, or null if not connected. */
+export function loadAuth(): Auth | null {
+  try {
+    const obj = JSON.parse(readFileSync(authPath(), "utf-8"));
+    if (obj && typeof obj === "object" && typeof obj.token === "string" && obj.token) {
+      return {
+        server: typeof obj.server === "string" && obj.server ? obj.server : defaultServer(),
+        token: obj.token,
+        user_id: obj.user_id,
+        device_id: obj.device_id,
+      };
+    }
+  } catch {
+    /* not connected / unreadable → offline */
+  }
+  return null;
+}
+
+/** A reachable brain rejected our token (401/403) → retire auth.json so the next
+ *  session's sessionStart hook re-runs the device-authorize flow. Non-destructive
+ *  (renamed, not deleted). Transport errors (offline/5xx) never reach here. */
+export function markRevoked(): void {
+  try {
+    renameSync(authPath(), authPath() + ".revoked");
+  } catch {
+    /* already gone / unwritable — best-effort */
+  }
+}
+
+/** One bearer-authed JSON call, hard-bounded by a timeout. null on ANY non-2xx
+ *  or transport/parse error; 401/403 also retires the (revoked) token. */
+async function call(
+  auth: Auth,
+  method: string,
+  path: string,
+  body: unknown,
+  timeoutMs: number,
+): Promise<any | null> {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(auth.server.replace(/\/+$/, "") + path, {
+      method,
+      headers: {
+        Authorization: `Bearer ${auth.token}`,
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: ctrl.signal,
+    });
+    if (res.status === 401 || res.status === 403) {
+      markRevoked(); // authoritative: token rejected → re-authorize next session
+      return null;
+    }
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null; // transport/timeout/parse — transient, leave auth.json intact
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Smart recall from the server. `project` scopes to personal + this-project.
+ *  `session` threads the opencode session id through `&session=<id>` so the brain
+ *  can close the recall-usefulness loop (mirrors the Python client's session
+ *  threading) — omitted when absent. */
+export async function recall(
+  auth: Auth,
+  query: string,
+  limit = 8,
+  project?: string,
+  session?: string,
+): Promise<RecallResult[]> {
+  const params = new URLSearchParams({ q: query, limit: String(limit) });
+  if (project) params.set("project", project);
+  if (session) params.set("session", session);
+  const data = await call(auth, "GET", `/v1/recall?${params.toString()}`, null, RECALL_TIMEOUT_MS);
+  const results = data?.results;
+  return Array.isArray(results) ? results : [];
+}
+
+/** Most-recent deposits (the sessionStart fallback). NOT project-filtered by the
+ *  server — callers MUST filter with project.visibleInProject before showing them. */
+export async function recent(auth: Auth, limit = 8): Promise<RecallResult[]> {
+  const data = await call(auth, "GET", `/v1/memories?limit=${limit}`, null, RECALL_TIMEOUT_MS);
+  const deposits = data?.deposits;
+  return Array.isArray(deposits) ? deposits : [];
+}
+
+/** Batch deposit (the server re-scrubs + runs the worth-keeping gate). The
+ *  client_id is the server idempotency key, so a retry never duplicates. */
+export async function deposit(auth: Auth, items: DepositItem[]): Promise<boolean> {
+  if (!items.length) return false;
+  const data = await call(auth, "POST", "/v1/memories/batch", { items }, DEPOSIT_TIMEOUT_MS);
+  return !!data;
+}
+
+/** POST /v1/entitlement — this device's tool policy {active_tool, multi_tool,
+ *  needs_reconnect, in_grace, grace_days_left, tools_connected, ...}. null on a
+ *  transient error OR a revoked token (call() already retired auth.json on 401/403). */
+export async function entitlementCall(auth: Auth): Promise<any | null> {
+  return call(auth, "POST", "/v1/entitlement", null, RECALL_TIMEOUT_MS);
+}
+
+/** POST /v1/devices/claim-tool — claim the free active slot for `tool` (no-op if a
+ *  tool already holds it). Returns {active_tool, multi_tool} or null. */
+export async function claimToolCall(auth: Auth, tool: string): Promise<any | null> {
+  return call(auth, "POST", "/v1/devices/claim-tool", { tool }, RECALL_TIMEOUT_MS);
+}

package/lib/capture.ts

@@ -0,0 +1,109 @@
+/** Commodity capture heuristics — NOT the IP.
+ *
+ * Simple regex/string helpers (a chatter gate, scope router, polarity hint,
+ * secret scrub) that decide WHETHER and HOW to send a capture to the server.
+ * None of the proprietary engine lives here — that stays on the brain. Ported
+ * 1:1 from the Python thin client's `_capture.py` so the bun connector keeps the
+ * same capture quality. The server re-scrubs + runs the real worth-keeping gate.
+ */
+
+// ── worth-keeping gate ───────────────────────────────────────────────────────
+const CHATTER =
+  /^(?:ok(?:ay)?|k|thx|thanks?|thank you|ty|yes|yep|yeah|yup|no|nope|sure|cool|nice|great|awesome|perfect|lgtm|got it|continue|go ahead|do it|please do|proceed|run it|run the tests?|next|stop|wait|hmm+|ah|oh|nvm|never ?mind)[\s.!?]*$/i;
+const SIGNAL =
+  /\b(prefer|always|never|don'?t|do not|avoid|use\b|using|i like|we should|should (?:always|never|use)|remember|note that|going with|decided|rule:|important|make sure|ensure|must\b|need to|require|my .+ is\b|the .+ is\b)\b/i;
+const MIN_WORDS = 4;
+
+export function shouldDeposit(userText: string): [boolean, string] {
+  const t = (userText || "").trim();
+  if (!t) return [false, "empty"];
+  if (CHATTER.test(t)) return [false, "chatter"];
+  if (SIGNAL.test(t)) return [true, "signal"];
+  if (t.split(/\s+/).length < MIN_WORDS) return [false, "too_short"];
+  return [true, "substantive"];
+}
+
+export function heuristicPolarity(userText: string): string {
+  const t = (userText || "").toLowerCase();
+  if (/\b(never|don'?t|do not|avoid|stop|doesn'?t work|didn'?t work|fails?|failed|broke|broken|bug|wrong|bad)\b/.test(t))
+    return "cautionary";
+  if (/\b(prefer|always|use|like|love|want|should|works?|good)\b/.test(t)) return "positive";
+  return "open";
+}
+
+// ── scope router (personal/global vs project) ────────────────────────────────
+const PERSONAL =
+  /\b(i (?:prefer|like|love|always|usually|tend to|never|hate|avoid)\b|my (?:favou?rite|preferred|default|usual|go-?to|style|setup|workflow)\b|for all my (?:projects|repos)\b|i'?m a .*?(?:person|developer|engineer)\b)/i;
+const PROJECT =
+  /(?:\b(?:this (?:project|repo|codebase|app|service)|in this (?:repo|project)|the (?:server|database|db|api|endpoint|service|build|deploy(?:ment)?|schema)\b|localhost|127\.0\.0\.1|\b\d{1,3}(?:\.\d{1,3}){3}\b)|\/[\w.\-]+\/[\w./\-]+)/i;
+
+export function classifyScope(userText: string): string {
+  const t = userText || "";
+  if (PROJECT.test(t)) return "project";
+  if (PERSONAL.test(t)) return "personal";
+  return "project"; // default: contain locally rather than pollute global
+}
+
+export function buildContent(userText: string, asstText: string): string {
+  let content = (userText || "").trim();
+  const a = (asstText || "").trim();
+  if (a) content += `\n\n(assistant: ${a.slice(0, 400)})`;
+  return content.trim();
+}
+
+// ── secret scrub (defense-in-depth; the server re-scrubs too) ────────────────
+type Rule = { kind: string; re: RegExp };
+const PATTERNS: Rule[] = [
+  { kind: "private_key", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g },
+  { kind: "openai_anthropic_key", re: /\bsk-[A-Za-z0-9_-]{16,}\b/g },
+  { kind: "github_token", re: /\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}\b/g },
+  { kind: "aws_access_key", re: /\bAKIA[0-9A-Z]{16}\b/g },
+  { kind: "google_api_key", re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { kind: "slack_token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+  { kind: "uri_credential", re: /\b([a-zA-Z][a-zA-Z0-9+.\-]*:\/\/[^\s:/@]*):([^\s/@]+)@/g },
+  { kind: "jwt", re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+  { kind: "bearer", re: /\bbearer\s+[A-Za-z0-9._\-]{16,}/gi },
+  {
+    // key looks secret-y → redact its value whether unquoted OR quoted (quoted
+    // values may contain spaces, e.g. PASSWORD="correct horse battery staple").
+    kind: "assignment",
+    re: /\b([A-Za-z0-9_]*(?:api[_-]?key|secret|token|password|passwd|pwd|access[_-]?key|client[_-]?secret|auth[_-]?token)[A-Za-z0-9_]*)\s*[:=]\s*(?:"[^"]{2,}"|'[^']{2,}'|[^\s"']{6,})/gi,
+  },
+];
+const BLOB = /\b[A-Za-z0-9+/=_-]{32,}\b/g;
+const ENTROPY_THRESHOLD = 4.2;
+
+function entropy(s: string): number {
+  if (!s) return 0;
+  const n = s.length;
+  const counts = new Map<string, number>();
+  for (const c of s) counts.set(c, (counts.get(c) || 0) + 1);
+  let e = 0;
+  for (const c of counts.values()) e -= (c / n) * Math.log2(c / n);
+  return e;
+}
+
+/** Returns [scrubbed, kindsFound]. */
+export function scrub(text: string): [string, string[]] {
+  if (!text) return [text, []];
+  const found: string[] = [];
+  let out = text;
+  for (const { kind, re } of PATTERNS) {
+    out = out.replace(re, (...args: any[]) => {
+      const groups = args.slice(1, -2); // capture groups (drop offset + whole string)
+      found.push(kind);
+      if (kind === "assignment") return `${groups[0]}=[REDACTED]`; // keep the key name
+      if (kind === "uri_credential") return `${groups[0]}:[REDACTED]@`; // keep scheme+user+host
+      return `[REDACTED:${kind}]`;
+    });
+  }
+  out = out.replace(BLOB, (tok: string) => {
+    if (tok.includes("REDACTED")) return tok;
+    if (entropy(tok) >= ENTROPY_THRESHOLD) {
+      found.push("high_entropy");
+      return "[REDACTED:high_entropy]";
+    }
+    return tok;
+  });
+  return [out, found];
+}