@prismer/runtime 2.0.8 → 2.2.55

package/plugins/memory/prismer/plugin.yaml

@@ -0,0 +1,8 @@
+name: prismer
+version: 1.0.0
+description: "Prismer Cloud — local-first memory provider. Archive recall via agent-driven memory_search/memory_load tools against the daemon's local FTS5 store; bounded core-inject; automatic extract; built-in MEMORY.md mirroring. Activating it replaces Honcho (Hermes allows one external provider)."
+# All config is provided by the daemon (ensureService) via the profile .env —
+# no external CLI dependency, the daemon HTTP endpoint IS the backend.
+hooks:
+  - on_pre_compress
+  - on_memory_write

package/plugins/memory/prismer/tool-schemas.generated.json

@@ -0,0 +1,249 @@
+{
+  "_generated": {
+    "by": "npx tsx scripts/memory211/generate-memory-tool-contract.ts",
+    "from": "sdk/prismer/src/adapters/memory-tools.ts",
+    "doNotEdit": "Regenerate instead of editing — see scripts/memory211/memory-tool-contract.ts"
+  },
+  "memoryTools": [
+    {
+      "name": "memory_search",
+      "description": "Search workspace memory (prior decisions, user preferences, knowledge pages). Use this only when you have a specific question that you believe past memory would answer — not on every turn. Most queries do not need this. Returns 0–N ranked snippets with prismer:// URIs; empty results are normal. Each hit reports where it sits in the wiki (hubPath, children), how linked it is (inboundLinkCount, outboundPreview) and whether it is distilled knowledge or raw source (tier) — use those to decide whether to load the page or follow a link. When your wording matched nothing, the response instead carries `navigation`: startPoints are NOT answers, they are the INDEX/hub entries to walk from — browse their children, batch-load what looks relevant, then follow links. Pass several related questions at once via `queries` instead of calling this tool repeatedly.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Free-text search query. Whitespace-separated terms are ANDed.",
+            "minLength": 1
+          },
+          "queries": {
+            "type": "array",
+            "description": "Batch recall: up to 8 related questions answered in ONE call, returned grouped in `resultsByQuery`. Prefer this over several separate memory_search calls.",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "maxItems": 8
+          },
+          "limit": {
+            "type": "integer",
+            "description": "Max number of results (default 5, max 20).",
+            "minimum": 1,
+            "maximum": 20,
+            "default": 5
+          },
+          "pageType": {
+            "type": "array",
+            "description": "Optional filter on page kind.",
+            "items": {
+              "type": "string",
+              "enum": [
+                "hub",
+                "leaf",
+                "decision",
+                "glossary",
+                "archive"
+              ]
+            }
+          }
+        },
+        "required": [
+          "query"
+        ]
+      }
+    },
+    {
+      "name": "memory_load",
+      "description": "Load a specific memory page by URI (prismer://workspace/<workspaceId>/memory/<path>) or by (workspaceId + path). Returns the full page content plus metadata and the page's outbound links (backlinks included) — served from the local link index even when the cloud is unreachable.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "uri": {
+            "type": "string",
+            "description": "Full prismer:// URI (preferred). Mutually exclusive with workspaceId+path.",
+            "pattern": "^prismer://"
+          },
+          "workspaceId": {
+            "type": "string",
+            "description": "Workspace identifier (used with `path`)."
+          },
+          "path": {
+            "type": "string",
+            "description": "Workspace-relative memory file path (used with `workspaceId`)."
+          }
+        }
+      }
+    },
+    {
+      "name": "memory_browse",
+      "description": "See the current memory structure BEFORE writing: the INDEX, existing hubs (with what each is about), and pages nearest to your query. Use it to decide placement (attach under a hub via memory_write parentHubPath, extend an existing page, or create a new hub).",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Optional topic — adds the nearest existing pages to the structure view."
+          }
+        }
+      }
+    },
+    {
+      "name": "memory_write",
+      "description": "Write a durable memory page to the workspace knowledge wiki (the WRITE path). Use this to persist a fact, decision, definition, or piece of project context that should survive across sessions. YOU author the page: write the `content` and choose its `path`, deciding placement from the memory structure (call memory_browse FIRST) — extend/replace an existing page by reusing its path, or create a new leaf under the right topic and ATTACH it via `parentHubPath`. An unanchored new leaf is rejected with `placement_required`; create a hub first when no existing hub fits. To extend someone else's existing page, prefer op=append-section (with `section`) over overwriting the whole page. One memory per distinct topic. A returned {\"ok\":true} means the mutation succeeded: for that fact/path, do not call memory_write again in this turn to polish or verify; use memory_load instead. Canonical content is PKF; markdown exists only as a legacy compatibility input and is normalized before storage.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Workspace-relative semantic path for the page, e.g. 'decisions/auth-model.pkf'. Reuse an existing page's path to extend/replace it.",
+            "minLength": 1
+          },
+          "content": {
+            "type": "string",
+            "description": "Canonical PKF page body. Markdown is accepted only for legacy compatibility and is normalized.",
+            "minLength": 1
+          },
+          "title": {
+            "type": "string",
+            "description": "Short page title."
+          },
+          "parentHubPath": {
+            "type": "string",
+            "description": "Attach this page under an existing hub — get hub paths from memory_browse. The daemon records a graph edge (page → hub) so the page nests under the hub instead of hanging flat off INDEX."
+          },
+          "relation": {
+            "type": "string",
+            "description": "Edge type for parentHubPath (default child-of).",
+            "enum": [
+              "child-of",
+              "related"
+            ]
+          },
+          "op": {
+            "type": "string",
+            "description": "Write operation (default replace = whole page). append-section appends a new section to an EXISTING page instead of overwriting it — preferred for extending someone else's page. rewrite-section overwrites just the section addressed by `section`.",
+            "enum": [
+              "replace",
+              "append-section",
+              "rewrite-section"
+            ]
+          },
+          "section": {
+            "type": "string",
+            "description": "Heading id (slug) of the target section. Required for op=append-section / rewrite-section."
+          },
+          "visibility": {
+            "type": "string",
+            "description": "Visibility scope for the page (default workspace). One of: workspace, agent:<imUserId>, private:<imUserId>, role:<slug>, council:<councilId>. role:/council: are for orchestrator writeback (e.g. a council roundtable writing a shared decision as council:<councilId>); a non-orchestrator caller falls back to workspace. Unknown values are treated as workspace."
+          }
+        },
+        "required": [
+          "path",
+          "content"
+        ]
+      }
+    },
+    {
+      "name": "memory_curate",
+      "description": "Curate workspace memory (knowledge-base maintenance). Ops: `candidates` READS what to converge (unplaced leaves + near-duplicate clusters + stale, remote-conflict, and oversized pages) — call this FIRST to decide clusters; `promote_to_hub` turns a leaf page into a hub; `supersede` archives a page and marks it stale; `rebuild_index` rebuilds machine-owned hub TOCs; top INDEX Contents is derived live from the graph. Section-level verbs (memory211 W5): `section_merge` folds one near-duplicate section into another (the cloud lands the supersedes/derived-from provenance edges for you), `section_supersede` retires one section in place, `rewire` re-points a broken or wrong link. `candidates` is read-only (any agent). Every other op is ORCHESTRATOR-ONLY — if you are not the workspace orchestrator they return an error.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "op": {
+            "type": "string",
+            "description": "Curation operation. candidates = READ unplaced/near-dup/stale/conflict/oversized surfaces (call first); promote_to_hub = leaf→hub; supersede = archive+stale; rebuild_index = rebuild hub TOCs (INDEX Contents is derived); section_merge = fold a near-duplicate section into another; section_supersede = retire one section; rewire = re-point a link.",
+            "enum": [
+              "candidates",
+              "promote_to_hub",
+              "supersede",
+              "rebuild_index",
+              "section_merge",
+              "section_supersede",
+              "rewire"
+            ]
+          },
+          "pageId": {
+            "type": "string",
+            "description": "Target page id. Required for promote_to_hub and supersede. For section_merge this is the WINNER page (the section that absorbs the duplicate). For section_supersede this is the page whose section retires."
+          },
+          "childPaths": {
+            "type": "array",
+            "description": "promote_to_hub only — existing page paths to attach under the new hub as its children.",
+            "items": {
+              "type": "string"
+            }
+          },
+          "reason": {
+            "type": "string",
+            "description": "Optional reason recorded by supersede / section_merge / section_supersede."
+          },
+          "kind": {
+            "type": "string",
+            "description": "candidates only — which surface to read (default all).",
+            "enum": [
+              "orphans",
+              "duplicates",
+              "stale",
+              "conflicts",
+              "oversized",
+              "all"
+            ]
+          },
+          "limit": {
+            "type": "integer",
+            "description": "candidates only — max items per kind.",
+            "minimum": 1,
+            "maximum": 500
+          },
+          "section": {
+            "type": "string",
+            "description": "section_supersede only — anchor slug of the section to retire."
+          },
+          "targetSection": {
+            "type": "string",
+            "description": "section_merge only — anchor slug of the WINNER section that absorbs the duplicate."
+          },
+          "sourcePageId": {
+            "type": "string",
+            "description": "section_merge only — id of the LOSER page whose section is folded away."
+          },
+          "sourceSection": {
+            "type": "string",
+            "description": "section_merge only — anchor slug of the LOSER section."
+          },
+          "mergedContent": {
+            "type": "string",
+            "description": "section_merge only — the merged section body to write into the winner (PKF per pkf-writing). The cloud writes the supersedes/derived-from provenance edges automatically."
+          },
+          "supersededByPageId": {
+            "type": "string",
+            "description": "section_supersede only — optional surviving page the retired section points at."
+          },
+          "supersededBySection": {
+            "type": "string",
+            "description": "section_supersede only — anchor slug on supersededByPageId."
+          },
+          "linkId": {
+            "type": "string",
+            "description": "rewire only — id of the link to re-point."
+          },
+          "toPageId": {
+            "type": "string",
+            "description": "rewire only — new target page id (mutually exclusive with toPath)."
+          },
+          "toPath": {
+            "type": "string",
+            "description": "rewire only — new target page path (mutually exclusive with toPageId)."
+          },
+          "toSection": {
+            "type": "string",
+            "description": "rewire only — optional new target section anchor."
+          }
+        },
+        "required": [
+          "op"
+        ]
+      }
+    }
+  ]
+}

package/plugins/tools/prismer-recall/__init__.py

@@ -0,0 +1,282 @@
+"""Prismer Cloud recall-tools — reversible register_tool plugin lane.
+
+Desktop-202 doc 19 §8 — the *lightest, most reversible* way to give a Hermes
+agent the memory recall affordance. It also carries one bounded, signed-runtime
+lifecycle bridge needed to bind the provider's actual response routing to the
+exact daemon run:
+
+  * It calls ``ctx.register_tool(...)`` TWICE (memory_search / memory_load) so
+    the two tools land in ``agent.tools`` via the registry's
+    ``get_tool_definitions()`` (agent_init.py:1156-1187 dedupes the memory-
+    provider injection against exactly these plugin-registered names).
+  * It registers ``post_api_request`` and forwards ONLY session id, the response
+    model (or Hermes' request-locked model when the upstream omits that field),
+    provider, agent and workspace. Raw response/content never crosses
+    this bridge. It still registers NO prefetch / sync / inject / extract /
+    compress behaviour and does not register a memory provider, so it does not
+    pin ``memory.provider`` or trip Hermes' provider exclusivity.
+
+Reversibility judge (doc 19 §3): delete this dir + drop ``prismer-recall``
+from ``plugins.enabled`` = fully gone. No distributed artifact, no version
+obligation, no framework lifecycle coupling.
+
+The handlers mirror the daemon-calling logic of the full provider shell
+(plugins/memory/prismer/) — plain HTTP GET to the daemon's local loopback
+``/local/memory/search`` and ``/local/memory/load`` (FTS5 BM25 + graph, NO
+vector) — but as plain callables, not provider methods.
+
+Config (profile .env, written by the daemon / the TS adapter wiring):
+  PRISMER_WORKSPACE_ID       — the workspace this profile's agent is bound to
+  PRISMER_DAEMON_PORT        — daemon loopback port (default 3210)
+  PRISMER_DAEMON_TOKEN       — optional bearer for the local data-plane
+  PRISMER_AGENT_IM_USER_ID   — the calling agent's IM user id (M-ACTOR-THREAD).
+                               Forwarded as ``actorImUserId`` + ``actorKind=agent``
+                               so the daemon attributes the ``recall_pull``
+                               observability event to this agent. The hermes
+                               gateway already exports this var into the plugin's
+                               inherited environment (hermes/index.ts gateway
+                               spawn env); when ABSENT the params are omitted and
+                               the daemon skips emission rather than fabricating
+                               an actor.
+
+NOTE: this file intentionally avoids the substrings the Hermes plugin loader
+sniffs for to auto-coerce a plugin to ``kind="exclusive"`` (plugins.py:1318).
+It is a plain ``standalone`` tool plugin — see plugin.yaml ``kind: standalone``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_PORT = "3210"
+_RECALL_TIMEOUT = 5
+_ROUTING_TIMEOUT = 2
+
+# Tool names are FROZEN to mirror the shared TS spec
+# (sdk/prismer/src/adapters/memory-tools.ts) and the OpenAI-style
+# shapes in the hermes adapter (HERMES_MEMORY_TOOLS). Do NOT rename.
+_TOOLSET = "prismer_recall"
+
+_MEMORY_SEARCH_SCHEMA = {
+    "name": "memory_search",
+    "description": (
+        "Search workspace memory (prior decisions, user preferences, knowledge "
+        "pages). Use this only when you have a specific question that you believe "
+        "past memory would answer — not on every turn. Most queries do not need "
+        "this. Returns 0–N ranked snippets with prismer:// URIs; empty results "
+        "are normal."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Free-text search query. Whitespace-separated terms are ANDed.",
+                "minLength": 1,
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Max number of results (default 5, max 20).",
+                "minimum": 1,
+                "maximum": 20,
+                "default": 5,
+            },
+            "pageType": {
+                "type": "array",
+                "description": "Optional filter on page kind.",
+                "items": {
+                    "type": "string",
+                    "enum": ["hub", "leaf", "decision", "glossary", "archive"],
+                },
+            },
+        },
+        "required": ["query"],
+    },
+}
+
+_MEMORY_LOAD_SCHEMA = {
+    "name": "memory_load",
+    "description": (
+        "Load a specific memory page by URI "
+        "(prismer://workspace/<workspaceId>/memory/<path>) or by "
+        "(workspaceId + path). Returns the full page content plus metadata."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "uri": {
+                "type": "string",
+                "description": "Full prismer:// URI (preferred). Mutually exclusive with workspaceId+path.",
+                "pattern": "^prismer://",
+            },
+            "workspaceId": {
+                "type": "string",
+                "description": "Workspace identifier (used with `path`).",
+            },
+            "path": {
+                "type": "string",
+                "description": "Workspace-relative memory file path (used with `workspaceId`).",
+            },
+        },
+    },
+}
+
+
+def _daemon_base() -> str:
+    port = (os.environ.get("PRISMER_DAEMON_PORT") or _DEFAULT_PORT).strip() or _DEFAULT_PORT
+    return f"http://127.0.0.1:{port}"
+
+
+def _headers() -> Dict[str, str]:
+    h = {"Content-Type": "application/json"}
+    token = (os.environ.get("PRISMER_DAEMON_TOKEN") or "").strip()
+    if token:
+        h["Authorization"] = f"Bearer {token}"
+    # memory203 doc 08 §2 (F4) — forward the daemon-injected per-agent memory
+    # capability so the daemon enforces workspace scope on recall RPCs.
+    cap = (os.environ.get("PRISMER_MEMORY_CAP") or "").strip()
+    if cap:
+        h["x-prismer-memory-cap"] = cap
+    return h
+
+
+def _http_get(path: str, timeout: int) -> Optional[dict]:
+    url = _daemon_base() + path
+    req = urllib.request.Request(url, headers=_headers(), method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except Exception as exc:  # noqa: BLE001 — degrade-not-break (doc 19 §8)
+        logger.debug("prismer-recall GET %s failed: %s", path, exc)
+        return None
+
+
+def _http_post(path: str, body: Dict[str, Any], timeout: int) -> Optional[dict]:
+    url = _daemon_base() + path
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(body, separators=(",", ":")).encode("utf-8"),
+        headers=_headers(),
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read()
+            return json.loads(raw.decode("utf-8")) if raw else {"ok": True}
+    except Exception as exc:  # noqa: BLE001 — routing evidence fails closed
+        logger.debug("prismer-recall POST %s failed: %s", path, exc)
+        return None
+
+
+def _workspace_id() -> str:
+    return (os.environ.get("PRISMER_WORKSPACE_ID") or "").strip()
+
+
+def _actor_params() -> Dict[str, str]:
+    """M-ACTOR-THREAD — the calling agent's actor identity for recall_pull.
+
+    Reads ``PRISMER_AGENT_IM_USER_ID`` from the inherited gateway env. When set,
+    returns ``{actorImUserId, actorKind}`` so the daemon RPC handler
+    (rpc.ts handleSearch / handleLoad) can attribute the ``recall_pull``
+    observability event to this agent. When ABSENT (legacy / anonymous), returns
+    ``{}`` so the daemon skips emission rather than fabricating an actor.
+    """
+    actor = (os.environ.get("PRISMER_AGENT_IM_USER_ID") or "").strip()
+    if not actor:
+        return {}
+    return {"actorImUserId": actor, "actorKind": "agent"}
+
+
+def _handle_memory_search(args: Dict[str, Any], **_kw: Any) -> str:
+    ws = _workspace_id()
+    if not ws:
+        return json.dumps({"error": "no workspace bound"})
+    query = str(args.get("query", "") or "").strip()
+    if not query:
+        return json.dumps({"error": "missing_query"})
+    params = {
+        "workspaceId": ws,
+        "q": query,
+        "topK": str(int(args.get("limit", 5) or 5)),
+        **_actor_params(),
+    }
+    page_type = args.get("pageType")
+    if isinstance(page_type, list) and page_type:
+        # Daemon accepts a single pageType per request — take the first
+        # (mirrors memory-tools.ts:173-176).
+        params["pageType"] = str(page_type[0])
+    res = _http_get(f"/local/memory/search?{urllib.parse.urlencode(params)}", _RECALL_TIMEOUT)
+    return json.dumps(res if res is not None else {"query": query, "results": []})
+
+
+def _handle_memory_load(args: Dict[str, Any], **_kw: Any) -> str:
+    ws = _workspace_id()
+    q: Dict[str, str] = {}
+    if args.get("uri"):
+        q["uri"] = str(args["uri"])
+    elif args.get("workspaceId") and args.get("path"):
+        q["workspaceId"] = str(args["workspaceId"])
+        q["path"] = str(args["path"])
+    elif ws and args.get("path"):
+        q["workspaceId"] = ws
+        q["path"] = str(args["path"])
+    else:
+        return json.dumps({"error": "memory_load requires either `uri` or `workspaceId`+`path`"})
+    q.update(_actor_params())
+    res = _http_get(f"/local/memory/load?{urllib.parse.urlencode(q)}", _RECALL_TIMEOUT)
+    return json.dumps(res if res is not None else {"error": "not_found"})
+
+
+def _record_terminal_routing(**kwargs: Any) -> None:
+    """Forward bounded post-response evidence; ignore raw response/content."""
+    session_id = str(kwargs.get("session_id") or "").strip()
+    # Some OpenAI-compatible streaming responses omit the optional `model`
+    # field. Hermes still passes `model=agent.model`, which is the model locked
+    # onto this exact API request (`require_model_lock=true` on the sessions
+    # path). It is terminal lifecycle evidence here, not profile/config fallback.
+    served_model = str(kwargs.get("response_model") or kwargs.get("model") or "").strip()
+    served_provider = str(kwargs.get("provider") or "").strip()
+    agent_im_user_id = (os.environ.get("PRISMER_AGENT_IM_USER_ID") or "").strip()
+    workspace_id = _workspace_id()
+    if not all((session_id, served_model, served_provider, agent_im_user_id, workspace_id)):
+        return
+    _http_post(
+        "/v1/hooks/post_api_request",
+        {
+            "session_id": session_id,
+            "extra": {
+                "agent_im_user_id": agent_im_user_id,
+                "workspace_id": workspace_id,
+                "served_model": served_model,
+                "served_provider": served_provider,
+            },
+        },
+        _ROUTING_TIMEOUT,
+    )
+
+
+def register(ctx) -> None:
+    """Register recall tools plus the bounded terminal-routing bridge."""
+    ctx.register_tool(
+        name="memory_search",
+        toolset=_TOOLSET,
+        schema=_MEMORY_SEARCH_SCHEMA,
+        handler=_handle_memory_search,
+        emoji="🔎",
+    )
+    ctx.register_tool(
+        name="memory_load",
+        toolset=_TOOLSET,
+        schema=_MEMORY_LOAD_SCHEMA,
+        handler=_handle_memory_load,
+        emoji="📄",
+    )
+    ctx.register_hook("post_api_request", _record_terminal_routing)
+    logger.info("prismer-recall registered tools + bounded post_api_request routing hook")

package/plugins/tools/prismer-recall/plugin.yaml

@@ -0,0 +1,15 @@
+name: prismer-recall
+version: 1.1.0
+kind: standalone
+description: >-
+  Prismer Cloud recall-tools — registers the agent-driven memory_search /
+  memory_load tools (FTS5 BM25 + graph, no vector) against the local daemon
+  via plain register_tool plus a bounded post_api_request routing-evidence
+  bridge. It does not own memory persistence or provider selection and does not
+  trip the single-external-provider exclusivity. Remove this dir + drop the
+  name from plugins.enabled = fully gone.
+hooks:
+  - post_api_request
+provides_tools:
+  - memory_search
+  - memory_load