@atlaso-labs/opencode 0.1.0

package/lib/state.ts

@@ -0,0 +1,125 @@
+/** Persisted cloud-link / entitlement verdict — ported 1:1 from the Python thin
+ *  client's `state.py`. The free plan allows ONE active tool per device; the
+ *  SERVER does not enforce that on the memory endpoints (by design), so each tool
+ *  caches its own verdict here and self-gates. The verdict is scoped to
+ *  (tool, device_id) so one tool never inherits another's, and is trusted for a
+ *  short TTL before re-verifying with the brain.
+ *
+ *  Stored at <atlaso_dir>/cloud_state.json (next to auth.json), overridable via
+ *  ATLASO_STATE. Written atomically (wx temp + fsync + rename).
+ */
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { atlasoDir } from "./atlaso";
+
+// `0` (or negative) disables caching → re-verify every call, like the Python client.
+const _ttl = parseInt(process.env.ATLASO_ENTITLEMENT_TTL ?? "600", 10);
+export const ENTITLEMENT_TTL = Number.isFinite(_ttl) ? _ttl : 600;
+
+export const LINKED = "linked";
+export const LOCAL_ONLY = "local_only";
+export const REVOKED = "revoked";
+export const NOT_ENTITLED = "not_entitled";
+export const NOT_CONNECTED = "not_connected";
+
+export interface Grace {
+  in_grace: boolean;
+  days_left: number | null;
+  tools_connected: number | null;
+}
+
+export interface Verdict {
+  mode: string; // "linked" | "local_only"
+  reason: string | null; // "revoked" | "not_entitled" | "not_connected" | null
+  since: number;
+  checked_at: number;
+  active_tool: string | null;
+  tool: string | null;
+  device_id: string | null;
+  grace: Grace | null;
+}
+
+function statePath(): string {
+  return process.env.ATLASO_STATE || join(atlasoDir(), "cloud_state.json");
+}
+
+const nowS = () => Math.floor(Date.now() / 1000);
+
+/** An UNVERIFIED-LINKED baseline (checked_at:0 → never fresh) so first-run /
+ *  foreign / corrupt state forces a re-verify rather than blocking. */
+export function defaultState(): Verdict {
+  return { mode: LINKED, reason: null, since: 0, checked_at: 0, active_tool: null, tool: null, device_id: null, grace: null };
+}
+
+export function get(): Verdict {
+  try {
+    const o = JSON.parse(readFileSync(statePath(), "utf-8"));
+    if (o && typeof o === "object" && o.mode) return { ...defaultState(), ...o };
+  } catch {
+    /* missing / malformed → default */
+  }
+  return defaultState();
+}
+
+function write(v: Verdict): void {
+  try {
+    const target = statePath();
+    const dir = dirname(target); // temp in the TARGET's dir so the rename is atomic (honors ATLASO_STATE)
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.cloud_state.${process.pid}.${randomUUID()}.tmp`);
+    const fd = openSync(tmp, "wx", 0o600);
+    try {
+      writeFileSync(fd, JSON.stringify(v, null, 2));
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(tmp, target);
+  } catch {
+    /* best-effort — absence just forces re-verify */
+  }
+}
+
+export function setLinked(opts: { tool?: string | null; device_id?: string | null; grace?: Grace | null }): void {
+  write({
+    mode: LINKED, reason: null, since: 0, checked_at: nowS(), active_tool: null,
+    tool: opts.tool ?? null, device_id: opts.device_id ?? null, grace: opts.grace ?? null,
+  });
+}
+
+export function setLocalOnly(
+  reason: string,
+  opts: { active_tool?: string | null; tool?: string | null; device_id?: string | null },
+): void {
+  const prev = get();
+  // preserve `since` across same-reason+identity rewrites (so a one-time notice isn't re-shown)
+  const same = prev.mode === LOCAL_ONLY && prev.reason === reason &&
+    prev.tool === (opts.tool ?? null) && prev.device_id === (opts.device_id ?? null);
+  write({
+    mode: LOCAL_ONLY, reason, since: same ? prev.since : nowS(), checked_at: nowS(),
+    active_tool: opts.active_tool ?? null, tool: opts.tool ?? null, device_id: opts.device_id ?? null, grace: null,
+  });
+}
+
+/** Drop the verdict so a fresh credential never inherits a stale free pass. */
+export function invalidate(): void {
+  try {
+    unlinkSync(statePath());
+  } catch {
+    /* already gone */
+  }
+}
+
+/** A verdict is authoritative only for the (tool, device_id) that produced it. */
+export function matches(st: Verdict, tool: string | null | undefined, deviceId: string | null | undefined): boolean {
+  return st.tool === (tool ?? null) && st.device_id === (deviceId ?? null);
+}
+
+export function isFresh(st: Verdict): boolean {
+  try {
+    return nowS() - (st.checked_at || 0) < ENTITLEMENT_TTL;
+  } catch {
+    return false;
+  }
+}

package/opencode.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "_comment": "Atlaso memory for OpenCode. The plugin (hooks: auto-recall + auto-capture) IS the value and is pure TypeScript talking only to the Atlaso brain. Model-invoked memory tools (recall/remember/forget/recent/status over MCP) are a REMOTE-MCP follow-up shipped at deploy — intentionally NOT a local Python MCP here. To enable: `bun add -d @atlaso-labs/opencode` then keep the entries below. Sign in happens via a browser-authorize on first run.",
+  "plugin": ["@atlaso-labs/opencode"],
+  "instructions": [".opencode/atlaso/AGENTS.md"]
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@atlaso-labs/opencode",
+  "version": "0.1.0",
+  "description": "Long-term memory for OpenCode — recalls what you've decided and remembers what matters, across sessions, projects, and tools. A pure-TypeScript OpenCode plugin (no engine; HTTP to the Atlaso brain only).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Atlaso Labs Inc. <hello@atlaso.ai>",
+  "homepage": "https://atlaso.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atlaso-labs/opencode.git"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "memory",
+    "long-term-memory",
+    "agent-memory",
+    "recall",
+    "atlaso"
+  ],
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "lib",
+    "skills",
+    "AGENTS.md",
+    "opencode.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "latest",
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "bugs": {
+    "url": "https://github.com/atlaso-labs/opencode/issues"
+  }
+}

package/skills/memory/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: memory
+description: >-
+  Atlaso memory curation judgment. Use ONLY when deciding whether/what to save to
+  memory, whether something is personal vs project-specific, or when deliberately
+  recalling, forgetting, or correcting a memory. Do NOT use for ordinary recall —
+  relevant memories are already injected automatically every turn.
+when_to_use: >-
+  deciding if something is worth remembering; choosing personal vs project memory;
+  superseding or forgetting a wrong/outdated memory; deliberately searching past
+  sessions for a prior decision.
+---
+
+# Using Atlaso memory well
+
+Relevant memories are **auto-injected every turn** (the "Atlaso Memory" block) — so
+most of the time you do nothing. Reach for the memory tools (`recall`, `remember`,
+`forget`, `recent`, `status`) only for the judgment calls below. When in doubt, do
+less: a smaller, higher-signal memory is worth more than volume.
+
+## 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.
+
+## When to deliberately `recall` (vs trusting the auto-injection)
+
+The automatic block usually has what you need. Search explicitly only when:
+- the user references a past decision ("what did we decide about X?"),
+- you're about to do something that might contradict an earlier choice, or
+- you're starting unfamiliar work where prior context would clearly help.
+
+Otherwise, trust the injected memories and **don't over-search**.
+
+## Fixing memory
+
+A memory is wrong or outdated → `recall` to find its id, then `forget` it (or save the
+correction). 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)*
+- ✅ "Tauri signing key must be single-line in CI or it errors." *(hard-won gotcha)*
+- ⏭️ "Compiled the app and the tests passed." *(ephemeral — skip)*

package/src/connect-entry.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env bun
+/**
+ * Runnable device-authorize entrypoint, spawned DETACHED by maybeAutoconnect()
+ * on first run (and usable directly: `bun run src/connect-entry.ts`). Opens the
+ * browser, polls until approved, writes the shared ~/.atlaso/auth.json, then
+ * releases the connect lock. Defaults ATLASO_TOOL to "opencode".
+ */
+import { runConnect } from "../lib/connect";
+
+if (!process.env.ATLASO_TOOL) process.env.ATLASO_TOOL = "opencode";
+
+runConnect()
+  .then((rc) => process.exit(rc))
+  .catch(() => process.exit(1));

package/src/index.ts

@@ -0,0 +1,184 @@
+/**
+ * Atlaso memory — OpenCode plugin (the npm package main + default export).
+ *
+ * The automatic memory loop, in pure TypeScript (bun-native, no Python). It owns
+ * NO memory logic: it only does HTTP to the brain `/v1/*` via the shared, tool-
+ * agnostic `lib/` (copied from the Cursor connector). The engine — retrieval,
+ * the conflict gate, the worth-keeping judgment — stays on the server. This is
+ * the IP thin-client rule, in an OpenCode plugin.
+ *
+ * Two hooks make the loop:
+ *   • "chat.message"      → recall relevant memory and inject it as a synthetic
+ *                           text part BEFORE the model responds (auto-recall).
+ *   • "event"/session.idle → capture the user's statement to memory when the
+ *                           turn finishes (auto-capture).
+ *
+ * EVERYTHING is FAIL-OPEN: a hook error must never break an OpenCode turn, so
+ * each hook body is wrapped in try/catch and the loop degrades to a no-op.
+ *
+ * Recall injection (verified live, opencode 1.17.x): pushing a SCHEMA-VALID
+ * synthetic text part onto chat.message `output.parts` injects AI-visible context —
+ * the model reads it and answers from it. OpenCode PERSISTS + strictly validates the
+ * part (id must be `prt_*`, messageID must be this turn's real `msg_*`), so we derive
+ * both from `output.message` and only ever ADD to the array. Fail-open: if there's no
+ * real message id we SKIP injecting (a malformed part would throw and break the turn).
+ */
+import { createHash } from "node:crypto";
+import type { Hooks, Plugin } from "@opencode-ai/plugin";
+import type { Part } from "@opencode-ai/sdk";
+
+import { deposit, loadAuth, recall, type DepositItem } from "../lib/atlaso";
+import { buildContent, classifyScope, heuristicPolarity, scrub, shouldDeposit } from "../lib/capture";
+import { maybeAutoconnect } from "../lib/connect";
+import { online } from "../lib/entitlement";
+import { log } from "../lib/log";
+import { projectKey } from "../lib/project";
+import { renderBlock } from "../lib/render";
+
+const TOOL = "opencode";
+const RECALL_LIMIT = 5;
+
+/** Deterministic idempotency key, so a re-deposit of the same statement collapses
+ *  to ONE memory server-side. Scope + project key are folded in so the SAME
+ *  content captured in a DIFFERENT project keeps its own attribution (matches the
+ *  Cursor/Claude-Code connectors + the Python client). */
+function clientId(content: string, scope: string, project: string | null): string {
+  return createHash("sha256").update(`${scope} ${project ?? ""} ${content}`).digest("hex").slice(0, 32);
+}
+
+/** Join this turn's REAL user text from a chat.message output — only `type:"text"`
+ *  parts that are NOT synthetic (so we never echo our own injected block back). */
+function userTextFrom(parts: unknown): string {
+  if (!Array.isArray(parts)) return "";
+  const out: string[] = [];
+  for (const p of parts as any[]) {
+    if (p && p.type === "text" && typeof p.text === "string" && !p.synthetic) out.push(p.text);
+  }
+  return out.join("\n").trim();
+}
+
+/** A SCHEMA-VALID synthetic TextPart carrying the recalled block. OpenCode SAVES
+ *  injected parts and validates them strictly: `id` must start with `prt_` and
+ *  `messageID` must be THIS turn's real `msg_*` — a malformed part throws and BREAKS
+ *  the turn (verified live on opencode 1.17.x). So we derive both from
+ *  `output.message`; the caller only calls this when a real message id is present. */
+function memoryPart(block: string, message: { id: string; sessionID: string }): Part {
+  return {
+    id: `prt_${createHash("sha256").update(`${message.id}:${block}`).digest("hex").slice(0, 24)}`,
+    sessionID: message.sessionID,
+    messageID: message.id,
+    type: "text",
+    text: block,
+    synthetic: true, // marks it as injected — kept out of the user transcript
+  };
+}
+
+export const AtlasoMemory: Plugin = async ({ directory, worktree }): Promise<Hooks> => {
+  // Detached browser-authorize on first run; no-op once this machine is linked.
+  try {
+    maybeAutoconnect(TOOL);
+  } catch {
+    /* fail-open: never let connect setup break plugin init */
+  }
+
+  // Per-session pending capture: the user's statement, saved at chat.message and
+  // deposited on session.idle (which carries only the sessionID, not the text).
+  const pending = new Map<string, { user: string }>();
+
+  // Resolve the project ONCE at init (the plugin's directory is stable for the
+  // session); null → personal-only scope.
+  const project = projectKey(directory || worktree) || undefined;
+
+  return {
+    /**
+     * AUTO-RECALL. On each new user message, recall relevant memory and unshift it
+     * as a synthetic text part so the model sees it before responding. Cloud-gated
+     * (free plan = 1 active tool/device; the brain doesn't enforce it — we do).
+     */
+    "chat.message": async (input, output) => {
+      if (process.env.ATLASO_EXTRACTING) return; // never recall inside our own enrichment
+      try {
+        if (!output || !Array.isArray(output.parts)) return; // shape changed → no-op
+        const userText = userTextFrom(output.parts);
+        if (!userText) return;
+
+        const auth = loadAuth();
+        if (!auth) return; // online-first: not linked → nothing to recall
+        if (!(await online(auth, TOOL, auth.device_id ?? null))) return; // local-only this turn
+
+        const results = await recall(auth, userText, RECALL_LIMIT, project, input.sessionID);
+        const block = renderBlock(results);
+        // OpenCode persists + strictly validates injected parts, so we can only build
+        // a schema-valid one when THIS turn's real message id (msg_*) is present on
+        // output.message. If it's missing, skip injecting (never crash the turn).
+        const message = (output as { message?: { id?: string; sessionID?: string } }).message;
+        if (block && message?.id) {
+          output.parts.unshift(memoryPart(block, { id: message.id, sessionID: message.sessionID || input.sessionID }));
+          log("recall", `injected n=${results.length} session=${input.sessionID}`);
+        } else if (block) {
+          log("recall", "skip-inject (no message id on output.message)");
+        }
+        // remember this turn's user statement for capture at session.idle
+        pending.set(input.sessionID, { user: userText });
+      } catch (e) {
+        log("recall", `error ${e}`); // fail open — memory must never break a turn
+      }
+    },
+
+    /**
+     * AUTO-CAPTURE. session.idle fires at end of turn and carries ONLY the
+     * sessionID — so we deposit the user statement we stashed at chat.message.
+     * Write-only; injects no context. Cloud-gated + secret-scrubbed client-side.
+     *
+     * TODO(enrichment): session.idle has no assistant text, so v1 captures the
+     * user statement alone (the core value). A follow-up can fetch the turn's
+     * assistant reply via the opencode SDK client and enrich buildContent(user,
+     * assistant) before depositing.
+     */
+    event: async ({ event }) => {
+      if (process.env.ATLASO_EXTRACTING) return; // never capture our own enrichment
+      try {
+        if (event?.type !== "session.idle") return;
+        const sessionID: string | undefined = (event as any)?.properties?.sessionID;
+        if (!sessionID) return;
+        const p = pending.get(sessionID);
+        if (!p) return;
+        pending.delete(sessionID); // one capture per stashed statement
+
+        const user = p.user;
+        if (!shouldDeposit(user)[0]) {
+          log("capture", "skip (gate)");
+          return;
+        }
+        const auth = loadAuth();
+        if (!auth) return;
+        if (!(await online(auth, TOOL, auth.device_id ?? null))) {
+          log("capture", "skip (not cloud-linked — local-only)");
+          return;
+        }
+
+        const content = buildContent(scrub(user)[0], ""); // assistant omitted in v1 (see TODO)
+        if (!content) return;
+        const scope = classifyScope(user);
+        const pk = projectKey(directory || worktree); // for the project tag + idempotency key
+        const tags = ["opencode", "auto", `pol-hint:${heuristicPolarity(user)}`, `scope:${scope}`];
+        if (scope === "project" && pk) tags.push(`project:${pk}`);
+
+        const item: DepositItem = {
+          client_id: clientId(content, scope, scope === "project" ? pk : null),
+          text: content,
+          polarity: "open",
+          evidence_grade: "anecdotal",
+          scope_note: null,
+          tags,
+        };
+        const saved = await deposit(auth, [item]);
+        log("capture", `saved=${saved} scope=${scope} session=${sessionID}`);
+      } catch (e) {
+        log("capture", `error ${e}`); // fail open
+      }
+    },
+  };
+};
+
+export default AtlasoMemory;