ever-opencode 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -56,21 +56,29 @@ curl http://127.0.0.1:8000/health # → {"status":"ok"}
56
56
 
57
57
  ### 2. Install the plugin
58
58
 
59
- Add it to your OpenCode config's `plugins` array:
59
+ From GitHub (no npm needed — one command, writes your global config):
60
+
61
+ ```sh
62
+ opencode plugin add github:xeon826/ever-opencode#v0.2.0
63
+ ```
64
+
65
+ `#v0.2.0` pins the release tag; `#main` tracks the branch (with update
66
+ checks), and a full commit SHA pins exactly. Or add it to your OpenCode
67
+ config's `plugins` array by hand:
60
68
 
61
69
  ```json
62
70
  {
63
- "plugins": ["ever-opencode"]
71
+ "plugins": ["github:xeon826/ever-opencode#v0.2.0"]
64
72
  }
65
73
  ```
66
74
 
67
- Or with options:
75
+ Also available on npm as `ever-opencode`. With options:
68
76
 
69
77
  ```json
70
78
  {
71
79
  "plugins": [
72
80
  {
73
- "package": "ever-opencode",
81
+ "package": "github:xeon826/ever-opencode#v0.2.0",
74
82
  "options": {
75
83
  "everosUrl": "http://127.0.0.1:8000",
76
84
  "flushEvery": 3,
@@ -94,6 +102,17 @@ ls ~/.everos/opencode/<project>/users/<you>/episodes/
94
102
 
95
103
  Future sessions in the same project recall what happened in past ones.
96
104
 
105
+ ## Agent tools
106
+
107
+ Beyond passive capture + recall injection, the plugin registers three tools the
108
+ agent can call on demand (same pattern as the mem0 plugin's memory tools):
109
+
110
+ | Tool | What it does |
111
+ | --- | --- |
112
+ | `everos_search` | Query memory on demand — "what did we decide about X last month?" Search runs server-side (BM25/vector); results carry relevance scores and ages. Searches this project's memory only — EverOS cannot search across projects. |
113
+ | `everos_add` | Store a durable fact immediately — add + synchronous extraction. Becomes searchable within a few seconds. |
114
+ | `everos_flush` | Force extraction of the session's buffered conversation. |
115
+
97
116
  ## EverOS `[llm]` provider matrix
98
117
 
99
118
  Any OpenAI-protocol chat-completions endpoint works. Copy-paste TOML for
package/dist/index.d.ts CHANGED
@@ -26,7 +26,8 @@ export type { EverosOptions, PluginContext } from "./types.js";
26
26
  export type { EverosEpisode, EverosMessage, EverosError } from "./everos.js";
27
27
  export { EverosClient } from "./everos.js";
28
28
  export { extractTranscript } from "./extract.js";
29
- export { formatRecall } from "./inject.js";
29
+ export { formatRecall, formatEpisodeLines } from "./inject.js";
30
+ export { buildTools, everosToolNames, registerTools } from "./tools.js";
30
31
  export { slugify, resolveIdentity } from "./identity.js";
31
32
  declare const _default: {
32
33
  id: string;
package/dist/index.js CHANGED
@@ -19,6 +19,7 @@ import { extractTranscript } from "./extract.js";
19
19
  import { formatRecall } from "./inject.js";
20
20
  import { resolveScope } from "./identity.js";
21
21
  import { Logger } from "./log.js";
22
+ import { registerTools } from "./tools.js";
22
23
  const DEFAULTS = {
23
24
  everosUrl: "http://127.0.0.1:8000",
24
25
  flushEvery: 3,
@@ -226,16 +227,29 @@ export async function setupPlugin(rawCtx) {
226
227
  log.debug(`flushed before compaction (${sessionID})`);
227
228
  }, sessionID);
228
229
  });
230
+ // ---- Agent tools (everos_search / everos_add / everos_flush) ----------
231
+ // Optional domain: hosts without ctx.tool simply get no tools.
232
+ const toolsRegistration = core
233
+ ? await registerTools(rawCtx, {
234
+ client: core.client,
235
+ scopeBase: core.scopeBase,
236
+ recallMethod: config.recallMethod,
237
+ defaultTopK: config.topK,
238
+ log,
239
+ })
240
+ : undefined;
229
241
  // ---- Cleanup ----------------------------------------------------------
230
242
  return () => {
231
243
  controller.abort();
232
244
  void recallRegistration.dispose();
233
245
  void compactionRegistration.dispose();
246
+ void toolsRegistration?.dispose();
234
247
  };
235
248
  }
236
249
  export { EverosClient } from "./everos.js";
237
250
  export { extractTranscript } from "./extract.js";
238
- export { formatRecall } from "./inject.js";
251
+ export { formatRecall, formatEpisodeLines } from "./inject.js";
252
+ export { buildTools, everosToolNames, registerTools } from "./tools.js";
239
253
  export { slugify, resolveIdentity } from "./identity.js";
240
254
  export default {
241
255
  // Matches the V2 plugin object contract ({ id, setup }); kept structural so
package/dist/inject.d.ts CHANGED
@@ -3,6 +3,15 @@
3
3
  * Empty input yields "" (caller skips injection entirely).
4
4
  */
5
5
  import type { EverosEpisode } from "./everos.js";
6
+ /**
7
+ * Render episodes as `- summary [score X (age)]` lines — the single
8
+ * representation shared by system-prompt recall and the agent tools.
9
+ * Empty input yields [].
10
+ */
11
+ export declare function formatEpisodeLines(episodes: EverosEpisode[], opts?: {
12
+ topK?: number;
13
+ now?: number;
14
+ }): string[];
6
15
  export declare function formatRecall(episodes: EverosEpisode[], opts?: {
7
16
  topK?: number;
8
17
  now?: number;
package/dist/inject.js CHANGED
@@ -17,19 +17,29 @@ function relativeDate(ts, now) {
17
17
  return `${months}mo ago`;
18
18
  return `${Math.floor(months / 12)}y ago`;
19
19
  }
20
- export function formatRecall(episodes, opts = {}) {
20
+ /**
21
+ * Render episodes as `- summary [score X (age)]` lines — the single
22
+ * representation shared by system-prompt recall and the agent tools.
23
+ * Empty input yields [].
24
+ */
25
+ export function formatEpisodeLines(episodes, opts = {}) {
21
26
  const top = episodes
22
27
  .slice(0, Math.max(1, opts.topK ?? 5))
23
28
  .filter((e) => typeof e?.summary === "string" && e.summary.trim().length > 0);
24
29
  if (top.length === 0)
25
- return "";
30
+ return [];
26
31
  const now = opts.now ?? Date.now();
27
- const lines = top.map((e) => {
32
+ return top.map((e) => {
28
33
  const date = relativeDate(e.timestamp, now);
29
34
  const score = typeof e.score === "number" ? e.score.toFixed(2) : "?";
30
35
  const dateSuffix = date.length > 0 ? ` (${date})` : "";
31
36
  return `- ${e.summary.trim()} [score ${score}${dateSuffix}]`;
32
37
  });
38
+ }
39
+ export function formatRecall(episodes, opts = {}) {
40
+ const lines = formatEpisodeLines(episodes, opts);
41
+ if (lines.length === 0)
42
+ return "";
33
43
  return [
34
44
  "<everos-recall>",
35
45
  "Relevant memories from previous sessions (may be imperfect; verify before relying on them):",
@@ -0,0 +1,63 @@
1
+ /**
2
+ * Agent-facing memory tools (OpenCode V2 `ctx.tool.transform`).
3
+ *
4
+ * The passive path (capture + recall injection) is automatic; these tools give
5
+ * the agent an explicit query/write surface — mirroring the mem0 plugin's
6
+ * tool-based memory access:
7
+ * everos_search — query memories on demand (BM25/vector recall server-side)
8
+ * everos_add — store a fact now (add + synchronous extraction via flush)
9
+ * everos_flush — force extraction of the session's deferred capture buffer
10
+ *
11
+ * Tool definitions are plain structural objects: `input` is a JSON Schema and
12
+ * `execute` returns `{content}` — no SDK runtime import, keeping the plugin
13
+ * unit-testable with synthetic contexts.
14
+ */
15
+ import type { EverosClient } from "./everos.js";
16
+ import type { Logger } from "./log.js";
17
+ /** JSON-Schema-backed tool definition (structural subset of V2 Tool.Info). */
18
+ export interface EverosToolDef {
19
+ readonly name: string;
20
+ readonly description: string;
21
+ readonly input: Record<string, unknown>;
22
+ execute(input: unknown, context: {
23
+ sessionID?: string;
24
+ }): Promise<ToolOutput>;
25
+ }
26
+ /** Structural `Tool.Result`: the model sees `content`. */
27
+ export interface ToolOutput {
28
+ readonly content: string;
29
+ readonly metadata?: Record<string, unknown>;
30
+ }
31
+ export interface ToolEditorLike {
32
+ add(tool: EverosToolDef): void;
33
+ }
34
+ export interface ToolDomainLike {
35
+ transform(callback: (editor: ToolEditorLike) => void): Promise<{
36
+ dispose(): Promise<void> | void;
37
+ }>;
38
+ }
39
+ export interface ToolDeps {
40
+ readonly client: EverosClient;
41
+ /** Identity resolved at setup: stable user/app/project scope base. */
42
+ readonly scopeBase: {
43
+ userId: string;
44
+ appId: string;
45
+ projectId: string;
46
+ };
47
+ readonly recallMethod: string;
48
+ readonly defaultTopK: number;
49
+ readonly log: Logger;
50
+ }
51
+ /** All tool names this plugin registers (exported for tests/diagnostics). */
52
+ export declare const everosToolNames: readonly string[];
53
+ /** Build the tool definitions (exported for tests). */
54
+ export declare function buildTools(deps: ToolDeps): EverosToolDef[];
55
+ /**
56
+ * Register the tools via `ctx.tool.transform`. Returns the registration, or
57
+ * `undefined` when the host exposes no tool domain (older hosts / tests).
58
+ */
59
+ export declare function registerTools(ctx: {
60
+ tool?: ToolDomainLike;
61
+ }, deps: ToolDeps): Promise<{
62
+ dispose(): Promise<void> | void;
63
+ } | undefined>;
package/dist/tools.js ADDED
@@ -0,0 +1,154 @@
1
+ /**
2
+ * Agent-facing memory tools (OpenCode V2 `ctx.tool.transform`).
3
+ *
4
+ * The passive path (capture + recall injection) is automatic; these tools give
5
+ * the agent an explicit query/write surface — mirroring the mem0 plugin's
6
+ * tool-based memory access:
7
+ * everos_search — query memories on demand (BM25/vector recall server-side)
8
+ * everos_add — store a fact now (add + synchronous extraction via flush)
9
+ * everos_flush — force extraction of the session's deferred capture buffer
10
+ *
11
+ * Tool definitions are plain structural objects: `input` is a JSON Schema and
12
+ * `execute` returns `{content}` — no SDK runtime import, keeping the plugin
13
+ * unit-testable with synthetic contexts.
14
+ */
15
+ import { formatEpisodeLines } from "./inject.js";
16
+ const TOOL_NAMES = ["everos_search", "everos_add", "everos_flush"];
17
+ function clampTopK(raw, fallback) {
18
+ const n = typeof raw === "number" ? raw : Number.NaN;
19
+ if (!Number.isFinite(n))
20
+ return fallback;
21
+ return Math.min(25, Math.max(1, Math.floor(n)));
22
+ }
23
+ /** Capture-path scope ids are derived per session; tools do the same. */
24
+ function sessionScope(deps, sessionID) {
25
+ return {
26
+ session_id: (sessionID ?? "everos-tools").slice(0, 128),
27
+ app_id: deps.scopeBase.appId,
28
+ project_id: deps.scopeBase.projectId,
29
+ };
30
+ }
31
+ /** Never let a tool failure crash the model turn — report it as content. */
32
+ async function guarded(deps, tool, fn) {
33
+ try {
34
+ return await fn();
35
+ }
36
+ catch (err) {
37
+ const detail = err instanceof Error && err.code
38
+ ? `${err.code}: ${err.message}`
39
+ : err instanceof Error
40
+ ? err.message
41
+ : String(err);
42
+ deps.log.debug(`${tool} error: ${detail}`);
43
+ return { content: `everos ${tool} failed: ${detail}`, metadata: { error: true } };
44
+ }
45
+ }
46
+ function makeSearchTool(deps) {
47
+ return {
48
+ name: "everos_search",
49
+ description: "Search this project's persistent EverOS memory (episodes + atomic facts from previous " +
50
+ "sessions of this project). Use proactively when context from past work would help — " +
51
+ "prior decisions, preferences, debugging history. Results are ranked server-side " +
52
+ "(BM25/vector); each line carries a relevance score and age. Searches the current " +
53
+ "project's scope only — EverOS cannot search across projects.",
54
+ input: {
55
+ type: "object",
56
+ properties: {
57
+ query: { type: "string", description: "Free-text query, e.g. 'how did we fix the flaky login test'" },
58
+ top_k: { type: "number", description: `Max results (1-25, default ${deps.defaultTopK})` },
59
+ },
60
+ required: ["query"],
61
+ },
62
+ async execute(rawInput, context) {
63
+ const input = (rawInput ?? {});
64
+ const query = typeof input.query === "string" ? input.query.trim() : "";
65
+ if (query.length === 0) {
66
+ return { content: "everos_search failed: 'query' (non-empty string) is required." };
67
+ }
68
+ return guarded(deps, "everos_search", async () => {
69
+ const topK = clampTopK(input.top_k, deps.defaultTopK);
70
+ // Scope narrowing is mandatory: the server pins app_id/project_id (defaults
71
+ // "default"/"default") into the store filter, so omitting either searches an
72
+ // empty partition — there is no cross-scope mode in the v2 API.
73
+ const episodes = await deps.client.searchMemories(deps.scopeBase.userId, query, {
74
+ method: deps.recallMethod,
75
+ topK,
76
+ scope: { appId: deps.scopeBase.appId, projectId: deps.scopeBase.projectId },
77
+ });
78
+ const lines = formatEpisodeLines(episodes, { topK });
79
+ if (lines.length === 0) {
80
+ return { content: `No memories found for: ${query}` };
81
+ }
82
+ return {
83
+ content: [`EverOS memories (${lines.length}, may be imperfect):`, ...lines].join("\n"),
84
+ metadata: { sessionID: context.sessionID, scope: "project", count: lines.length },
85
+ };
86
+ });
87
+ },
88
+ };
89
+ }
90
+ function makeAddTool(deps) {
91
+ return {
92
+ name: "everos_add",
93
+ description: "Store a durable fact in EverOS memory (decisions, preferences, learnings) so future " +
94
+ "sessions can recall it. One sentence per call. The fact is extracted synchronously " +
95
+ "but may take a few seconds before search indexes see it.",
96
+ input: {
97
+ type: "object",
98
+ properties: {
99
+ text: { type: "string", description: "The fact to remember, one sentence" },
100
+ },
101
+ required: ["text"],
102
+ },
103
+ async execute(rawInput, context) {
104
+ const input = (rawInput ?? {});
105
+ const text = typeof input.text === "string" ? input.text.trim() : "";
106
+ if (text.length === 0) {
107
+ return { content: "everos_add failed: 'text' (non-empty string) is required." };
108
+ }
109
+ return guarded(deps, "everos_add", async () => {
110
+ const scope = sessionScope(deps, context?.sessionID);
111
+ await deps.client.addMemory(scope, [{ sender_id: deps.scopeBase.userId, role: "user", timestamp: Date.now(), content: text }], { deferExtraction: true });
112
+ // Synchronous extraction so the new fact is queryable right away.
113
+ await deps.client.flushMemory(scope);
114
+ return {
115
+ content: `Remembered: ${text} (may take a few seconds to become searchable)`,
116
+ metadata: { sessionID: scope.session_id },
117
+ };
118
+ });
119
+ },
120
+ };
121
+ }
122
+ function makeFlushTool(deps) {
123
+ return {
124
+ name: "everos_flush",
125
+ description: "Force EverOS to extract memories from this session's captured conversation so far. " +
126
+ "Useful right before asking a question about the current session's history.",
127
+ input: { type: "object", properties: {} },
128
+ async execute(_input, context) {
129
+ return guarded(deps, "everos_flush", async () => {
130
+ const scope = sessionScope(deps, context?.sessionID);
131
+ await deps.client.flushMemory(scope);
132
+ return { content: "EverOS buffer flushed (extraction complete).", metadata: { sessionID: scope.session_id } };
133
+ });
134
+ },
135
+ };
136
+ }
137
+ /** All tool names this plugin registers (exported for tests/diagnostics). */
138
+ export const everosToolNames = TOOL_NAMES;
139
+ /** Build the tool definitions (exported for tests). */
140
+ export function buildTools(deps) {
141
+ return [makeSearchTool(deps), makeAddTool(deps), makeFlushTool(deps)];
142
+ }
143
+ /**
144
+ * Register the tools via `ctx.tool.transform`. Returns the registration, or
145
+ * `undefined` when the host exposes no tool domain (older hosts / tests).
146
+ */
147
+ export async function registerTools(ctx, deps) {
148
+ if (!ctx.tool)
149
+ return undefined;
150
+ return ctx.tool.transform((editor) => {
151
+ for (const tool of buildTools(deps))
152
+ editor.add(tool);
153
+ });
154
+ }
package/dist/types.d.ts CHANGED
@@ -50,6 +50,23 @@ export interface SessionDomainLike {
50
50
  export interface VcsDomainLike {
51
51
  get(input?: Record<string, unknown>): Promise<unknown>;
52
52
  }
53
+ /** Structural view of the V2 tool editor handed to `ctx.tool.transform`. */
54
+ export interface ToolEditorLike {
55
+ add(tool: {
56
+ readonly name: string;
57
+ readonly description: string;
58
+ readonly input: Record<string, unknown>;
59
+ execute(input: unknown, context: {
60
+ sessionID?: string;
61
+ }): Promise<{
62
+ content: string;
63
+ }>;
64
+ }): void;
65
+ }
66
+ /** Subset of `ctx.tool` (optional — absent on hosts without tool registration). */
67
+ export interface ToolDomainLike {
68
+ transform(callback: (editor: ToolEditorLike) => void): Promise<RegistrationLike>;
69
+ }
53
70
  /** Structural view of the V2 plugin setup context. */
54
71
  export interface PluginContext {
55
72
  readonly options: Readonly<Record<string, unknown>>;
@@ -62,4 +79,5 @@ export interface PluginContext {
62
79
  readonly event: EventDomainLike;
63
80
  readonly session: SessionDomainLike;
64
81
  readonly vcs?: VcsDomainLike;
82
+ readonly tool?: ToolDomainLike;
65
83
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ever-opencode",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "EverOS persistent memory plugin for OpenCode V2 \u2014 capture each turn, inject recall. Local-first, provider-neutral.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -21,7 +21,8 @@
21
21
  "scripts": {
22
22
  "build": "tsc",
23
23
  "test": "vitest run",
24
- "test:integration": "echo 'integration harness not yet implemented (real EverOS server required)'"
24
+ "test:integration": "EVEROS_INTEGRATION=1 vitest run integration.live",
25
+ "prepack": "npm run build"
25
26
  },
26
27
  "dependencies": {
27
28
  "@opencode/plugin": "^2.2.5"