@dotdotgod/hermes 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0 (ELv2)
+
+Copyright 2026 JooYoung Kim
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not
+licensed, and your licenses will automatically terminate. If the licensor
+provides you with a notice of your violation, and you cease all violation of
+this license no later than 30 days after you receive that notice, your
+licenses will be reinstated retroactively. However, if you violate these
+terms after such reinstatement, any additional violation of these terms will
+cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @dotdotgod/hermes
 
-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.
+Hermes CLI and messaging-gateway project memory adapter, without Plan Mode.
+Target host revision: `19b57f11d6eefb17e3e8a58e40b0b16aeb8b83b9`.
+
+## Installation
+
+Requires Python 3.11+ (use the host's supported Python version), Node 22.19+,
+Git for impact tracking, and an explicitly enabled native Hermes plugin.
+The installed directory must contain plugin.yaml and __init__.py at its root.
+
+For a source checkout:
+
+```bash
+pnpm install
+pnpm run generate
+mkdir -p "$HOME/.hermes/plugins"
+cp -R packages/hermes "$HOME/.hermes/plugins/dotdotgod"
+hermes plugins enable dotdotgod
+```
+
+For npm distribution, run npm pack @dotdotgod/hermes@0.6.0 and extract its package
+directory into the same native plugin location. npm installation alone does not
+activate a Hermes plugin. Generated MCP/CLI/client artifacts are self-contained;
+consumer node_modules, a global dotdotgod CLI and Python MCP dependencies are not
+required for core operation. Restart Hermes after installation/resource changes.
+Do not enable a separate profile-wide dotdotgod MCP server for these tools.
+
+Optional semantic embeddings use the existing explicit installation workflow;
+map/README routing works without them. Do not automatically install dependencies.
+
+## Gateway Repository Access
+
+The operator configures labels and principal-specific grants in config.yaml:
+
+```yaml
+plugins:
+  enabled: [dotdotgod]
+  entries:
+    dotdotgod:
+      settings:
+        roots:
+          app: /absolute/path/to/app
+          docs: /absolute/path/to/docs-project
+        gateway_access:
+          "telegram:123456": [app]
+          "discord:987654": [docs]
+```
+
+Use the trusted sender ID supplied by your Hermes gateway, not a display name.
+The model cannot grant itself a root or choose arbitrary filesystem paths.
+On an unbound gateway session the adapter requests dotdotgod_select_root with an
+authorized label before substantive work. Missing/changed grants deny access.
+CLI starts at the launch directory; optional cli_root sets its repository.
+
+One bridge and MCP server are created lazily per authorized repository/host
+session. Same-repository connections share the project SQLite DB, not mutable
+connection-session identity. Explicit context session_resume affects only the
+caller's connection; its last resumed ID survives transport reconnects.
+Selections persist in profile-owned plugin state and are reauthorized on restore.
+Startup/restored sessions conservatively reassess project memory; abandoned
+sibling completion is not inherited.
+
+This is routing isolation, not multi-tenant OS isolation. Hermes and enabled
+plugins retain host permissions. Authorized users of the same repository share
+project data; context scope/session filters are not access-control lists.
+
+## Features
+
+- Generated project-initializer, project-load, impact-review and document-clarify
+  skills from canonical shared sources.
+- Automatic load-required instructions; call dotdotgod_project_load once with an
+  agent-selected focus and continue the original request. Explicit load uses the
+  same tool/skill; full map depth is 5, focused map depth 3 with up to 30 query hits.
+- `dd:no-load` in a request skips only that request's automatic load instruction.
+- Explicit/fuzzy reference evidence via the bundled CLI; no full auto-validation.
+- Native dotdotgod execution/context/operations tools backed by per-session MCP.
+  They return a JSON envelope with content and structuredContent. Do not parse the
+  Markdown content as JSON or assume Pi's codemode object-return contract.
+- dotdotgod_select_root and dotdotgod_impact_status are adapter-local tools.
+- Pending impact is derived from Git dirty/untracked fingerprints and durable
+  checked fingerprints. Successful checks clear only checked, unchanged paths.
+  Source edits reopen pending state; reads and impact checks remain available.
+- Native Hermes delegate_task is the delegation mechanism. Child hooks inherit
+  only an already authorized matching-principal parent repository, with a separate
+  context connection; impact covers their changes in the shared worktree.
+
+No dedicated planning state, wizard, source-edit approval UI, compaction feature,
+Pi TUI implementation, or pi-subagents port is included.
+
+## Gate And Lifecycle Limits
+
+Recognized git commit/push/tag, npm/pnpm/yarn test/verify/build/lint/check/publish/deploy and common
+Python/Node test commands are blocked while impact is pending. Execute batches
+are checked inside the adapter too. Opaque execute_file calls are blocked while
+pending because their effects cannot be inferred safely.
+
+Native file path arguments and terminal workdir are rooted to the selected local
+repository; reads may also access the installed bundled skill resources. This adapter targets local host worktrees, not remote/container path
+translation. Shell paths, patch bodies, arbitrary programs and other plugins are
+not a filesystem sandbox; keep Hermes's own approvals and OS isolation.
+Shell mutations hidden inside one combined mutation/release command are not fully
+recognized. Native hooks can fail open under host errors/timeouts; no universal
+bypass-prevention claim is made.
+
+Interrupted turns close their context connection without replaying writes.
+Finalized/reset sessions release processes. Normal end-of-turn retains connections
+and background jobs. Transport failure ends the uncertain call; only a subsequent
+user/model call reconnects, with no automatic mutation replay. In-flight requests
+have a 660-second MCP and 690-second bridge timeout; cancellation kills the local
+process group after sending SDK cancellation so the server can reap detached
+command groups. Forced transport loss cannot guarantee termination of all detached
+commands; uncertain calls are never replayed. Persisted ingestion jobs retain
+shared runtime restart semantics. Cleanup is POSIX-tested; Windows is unverified.
+
+## Verification
+
+```bash
+pnpm --filter @dotdotgod/hermes run verify
+pnpm --filter @dotdotgod/hermes run pack:dry-run
+```
+
+Tests exercise native registration/lifecycle callbacks with host-shaped fixtures
+and real generated MCP processes, including concurrent roots/sessions, restore,
+reference/load fallback, impact failure/subsets/re-edits and cancellation.
+Live pinned host installation and messaging smoke results are recorded separately;
+fixture success alone is not a claim that every host lifecycle path was exercised.

package/__init__.py

@@ -0,0 +1,48 @@
+"""dotdotgod native Hermes plugin; no Plan Mode and no shared-profile MCP connection."""
+import json
+from pathlib import Path
+
+from .runtime import Runtime
+
+NAMES = {
+    "index": "dotdotgod_context_index", "search": "dotdotgod_context_search",
+    "stats": "dotdotgod_context_stats", "doctor": "dotdotgod_context_doctor",
+    "purge": "dotdotgod_context_purge", "session_resume": "dotdotgod_context_session_resume",
+}
+
+
+def register(ctx):
+    runtime = Runtime(ctx)
+    for skill in sorted((Path(__file__).parent / "skills").glob("*/SKILL.md")):
+        ctx.register_skill(skill.parent.name, skill)
+    tools = json.loads((Path(__file__).parent / "mcp" / "tools.json").read_text())
+    for tool in tools:
+        remote = tool["name"]
+        name = NAMES.get(remote, remote if remote.startswith("dotdotgod_") else "dotdotgod_" + remote)
+
+        def handle(args, session_id="", _remote=remote, **kwargs):
+            try:
+                return json.dumps(runtime.call(_remote, args, session_id), ensure_ascii=False)
+            except Exception as error:
+                return json.dumps({"error": str(error), "ok": False}, ensure_ascii=False)
+
+        ctx.register_tool(name=name, toolset="dotdotgod", schema={
+            "name": name, "description": tool["description"], "parameters": tool["inputSchema"],
+        }, handler=handle, description=tool["description"])
+
+    for name, schema, description in [
+        ("dotdotgod_select_root", {"type": "object", "properties": {"label": {"type": "string"}}, "required": ["label"], "additionalProperties": False}, "Select an operator-authorized repository for this host session."),
+        ("dotdotgod_impact_status", {"type": "object", "properties": {}, "additionalProperties": False}, "Read pending impact paths for the selected repository; does not clear them."),
+    ]:
+        def handle_local(args, session_id="", _name=name, **kwargs):
+            try:
+                return json.dumps(runtime.call(_name, args, session_id), ensure_ascii=False)
+            except Exception as error:
+                return json.dumps({"error": str(error), "ok": False}, ensure_ascii=False)
+        ctx.register_tool(name=name, toolset="dotdotgod", schema={"name": name, "description": description, "parameters": schema}, handler=handle_local, description=description)
+
+    ctx.register_hook("pre_llm_call", runtime.before_llm)
+    ctx.register_hook("pre_tool_call", runtime.before_tool)
+    ctx.register_hook("on_session_finalize", runtime.finalize)
+    ctx.register_hook("on_session_reset", runtime.finalize)
+    ctx.register_hook("on_session_end", runtime.end_turn)

package/mcp/bridge-entry.mjs

@@ -0,0 +1,41 @@
+// Adapter-owned stdio MCP client. One process/connection per repository + host session.
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+
+const root = realpathSync(process.argv[2]);
+const sessionId = process.argv[3];
+const client = new Client({ name: 'dotdotgod-hermes', version: '0.6.0' });
+const transport = new StdioClientTransport({
+  command: process.execPath, args: [fileURLToPath(new URL('./server.mjs', import.meta.url))], cwd: root,
+  env: { ...process.env, DOTDOTGOD_PROJECT_ROOT: root, DOTDOTGOD_SESSION_ID: sessionId }, stderr: 'inherit',
+});
+const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
+const lines = input[Symbol.asyncIterator](); // Subscribe before MCP startup; early requests must not be dropped.
+let active;
+let stopping = false;
+process.on('SIGTERM', () => { stopping = true; active?.abort(); input.close(); });
+try {
+  await client.connect(transport);
+  for await (const line of lines) {
+    try {
+      const request = JSON.parse(line);
+      active = new AbortController();
+      // Session resumes are validated by the existing shared contract. Do not replay failed writes.
+      const value = request.list ? await client.listTools() : await client.callTool({
+        name: request.name, arguments: request.arguments ?? {},
+      }, undefined, { timeout: 660000, signal: active.signal });
+      process.stdout.write(`${JSON.stringify({ ok: true, value })}\n`);
+    } catch (error) {
+      process.stdout.write(`${JSON.stringify({ ok: false, error: String(error.message ?? error) })}\n`);
+    }
+    active = undefined;
+    if (stopping) break;
+  }
+} finally {
+  // Let the server consume SDK cancellation and reap detached command groups before transport teardown.
+  if (stopping) await new Promise(resolve => setTimeout(resolve, 1000));
+  await client.close();
+}