@jinn-network/client 0.1.5 → 0.1.6-canary.118cd4d0

package/plugins/swe-rebench-v2-runtime/README.md

@@ -9,3 +9,16 @@ This plugin bundles two skills:
 The plugin is loaded automatically when an operator's daemon has the `swe-rebench-v2.v1` SolverNet enabled, per the SDK's `defaultRuntimePlugins: ['bundled:swe-rebench-v2-runtime']`.
 
 License: MIT.
+
+## See also
+
+- `client/plugins/swe-rebench-v2-diffmin/` — complementary minimal-diff +
+  test-mapping skills. Stacks with this plug-in: a daemon can load both for
+  the same SolverNet. The two plug-ins cover different angles:
+  `swe-rebench-v2-runtime` orients + plans; `swe-rebench-v2-diffmin` enforces
+  minimal-diff discipline and pre-loads the PASS_TO_PASS call-graph.
+
+Already shipping a Hermes skill? Drop it under `skills/<name>/SKILL.md`, add
+a `jinn.plugin.json` targeting `swe-rebench-v2.v1`, `yarn pack`, then
+`jinn solver-plugins publish`. See `swe-rebench-v2-diffmin/README.md` for
+the Hermes-migrator quickstart.

package/plugins/swe-rebench-v2-runtime/skills/orient/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: swe-rebench-v2-orient
-description: Orient on a SWE-rebench v2 task — read the problem statement, repo, base commit, and auxiliary interface info; identify the test files in FAIL_TO_PASS; understand what change the issue requires.
+description: Orient on a SWE-rebench v2 task — set up the repo at the right base commit, read the problem statement and auxiliary interface info, identify the test files in FAIL_TO_PASS, look for prior execution data, and understand what change the issue requires.
 ---
 
 # Orient on a SWE-rebench v2 task
@@ -14,11 +14,15 @@ Inputs you receive under `goal.spec` in the full task body:
 - `goal.spec.problem_statement` — the issue description
 - `goal.spec.interface` — auxiliary interface info (function names, signatures, descriptions). May be empty.
 
-Steps:
+## Set up the repo
+
+Treat `$workingDir/repo` as the only task repository checkout. Do not reuse a repo from another `workingDir` or from `implStateDir`. If `$workingDir/repo/.git` is missing, clone `https://github.com/<goal.spec.repo>.git` into `$workingDir/repo` and checkout `<goal.spec.base_commit>` before editing. All your in-tree edits must live in `$workingDir/repo` — that's both where the test infrastructure expects to find them and where the daemon's harvester reads a `git diff` from as a last-resort fallback if your typed-payload submission never lands.
+
+## Steps
 
 1. Read the problem statement carefully. Note the symptom, the expected behaviour, and any hints about which files / symbols are involved.
 2. If `task.interface` is non-empty, treat it as authoritative for function names + signatures of the API you must implement / fix.
-3. Use Network Tools to look for prior execution data from similar SWE-rebench v2 work. Call `search_records` with `solverType: "swe-rebench-v2.v1"`, `role: "restoration"`, and `artifactType: "swe-rebench-v2_v1_solution"`; use `inspect_record` on promising refs. Call `acquire_artifact` only when the inspected record has donated IPFS sources and the full execution data is likely to help this task.
+3. Look for prior execution data from similar SWE-rebench v2 work in the Jinn knowledge corpus: search for records with `solverType: "swe-rebench-v2.v1"`, `role: "restoration"`, and `artifactType: "swe-rebench-v2_v1_solution"`. For any promising hit, examine its index card before deciding to spend on artifact bytes — only download the full execution data when its index card suggests it is likely relevant. Your available Jinn corpus tools include separate "search", "inspect", and "acquire" operations; pick each by what you are trying to do (find candidates → examine one → download bytes).
 4. Check the `FAIL_TO_PASS` test names from the HF row — these define the success criterion. Find them in the codebase via grep / fs search.
 5. Output a brief Orient summary (3-5 sentences): your hypothesis about the bug, the files you intend to touch, the test you intend to satisfy, and any donated execution data that affected the plan.
 

package/plugins/swe-rebench-v2-runtime/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: swe-rebench-v2-plan
-description: Plan the patch for a SWE-rebench v2 task — given the Orient summary, sketch the minimal diff that resolves the issue without breaking existing PASS_TO_PASS tests, then submit the final patch via the `submit_typed_payload` MCP tool.
+description: Plan the patch for a SWE-rebench v2 task — given the Orient summary, sketch the minimal diff that resolves the issue without breaking existing PASS_TO_PASS tests, then submit the final patch as a typed structured payload to the daemon.
 ---
 
 # Plan the patch
@@ -25,11 +25,9 @@ Pass this plan forward to the Execute phase, which produces the actual patch.
 
 ## Submitting the final patch
 
-Once Execute has produced the unified diff, call the **`submit_typed_payload`** MCP tool exposed by the daemon to register the Solution. The daemon validates the payload against the SolverNet contract's solution schema before persisting it; if validation fails, the tool returns the Zod error tree under `error.issues` and you can retry.
+Once Execute has produced the unified diff, hand the Solution back to the daemon by submitting a **typed structured payload** through the Jinn client tools available to you. Your tool catalogue includes a dedicated "submit typed payload" action that validates the payload against the active SolverNet contract schema before persisting it. The validator runs server-side — on schema mismatch you will receive a Zod-style `issues[]` tree and can correct the payload and re-submit.
 
-Only if `submit_typed_payload` is not available in the current harness, write the same payload object directly to `<workingDir>/.execute/solution-payload.json`. Do not choose the direct file path when the tool is available. Create the `.execute` directory if needed. The daemon's harvester reads that file after the harness exits and applies the same SolverNet payload schema during envelope assembly.
-
-Required payload shape for `swe-rebench-v2.v1`:
+The required payload shape for `swe-rebench-v2.v1` restoration is:
 
 ```json
 {
@@ -44,21 +42,12 @@ Optional fields:
 
 Do **not** include daemon-derived fields (e.g. trajectory CIDs) — the daemon attaches trajectory provenance to the envelope automatically. The Solution payload is purely solver-known fields.
 
-Example call:
-
-```
-submit_typed_payload({
-  payload: {
-    schemaVersion: "swe-rebench-v2-solution.v1",
-    patch: "--- a/src/foo.c\n+++ b/src/foo.c\n@@ -1 +1 @@\n-old\n+new\n"
-  }
-})
-```
-
-A successful response looks like:
+A successful submission response looks like:
 
 ```json
 { "accepted": true, "solverType": "swe-rebench-v2.v1", "role": "restoration", "persistedTo": "<workingDir>/.execute/solution-payload.json" }
 ```
 
+If — and only if — your harness exposes no typed-payload submission tool at all, fall back by writing the same payload object directly to `<workingDir>/.execute/solution-payload.json` (create the `.execute` directory if needed). The daemon's harvester reads that file post-execution and applies the same SolverNet payload schema during envelope assembly. Prefer the tool path whenever it exists, because the tool gives you immediate schema validation feedback while the file path does not.
+
 After a successful submission, this Plan/Execute cycle is complete — the daemon's harness picks up the persisted payload post-execution and assembles the on-chain envelope.

package/templates/plugins/runtime-plugin/.mcp.json.tmpl

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "example": {
+      "command": "node",
+      "args": ["mcp/server.mjs"]
+    }
+  }
+}

package/templates/plugins/runtime-plugin/README.md.tmpl

@@ -0,0 +1,30 @@
+# {{packageName}}
+
+Jinn runtime SolverPlugin — exposes MCP tools to every Jinn harness session, regardless of SolverNet.
+
+## What this is
+
+A runtime SolverPlugin declares `jinn.supports: ['jinn.runtime']` and is loaded by Jinn-running daemons as a global MCP tool source. Use this pattern when your plug-in's value is harness-shaped (a network tool, a data lookup, a system probe) rather than task-shaped.
+
+If your plug-in is task-shaped (skills + tools scoped to a specific SolverNet), use the `solver-type-plugin` pattern instead: `jinn create plugin <name> --pattern solver-type-plugin --solver-type <id>`.
+
+## Get started
+
+```bash
+yarn install
+yarn test
+```
+
+Replace `mcp/server.mjs` with a real MCP server implementation (typically via `@modelcontextprotocol/sdk`) exposing the tools you want available.
+
+## Publish
+
+```bash
+jinn solver-plugins validate path:.
+jinn solver-plugins publish path:.
+```
+
+## Reference
+
+- Quickstart: https://github.com/Jinn-Network/mono/blob/main/cargo/docs/build/quickstart.md (placeholder until `52x3.6` ships the canonical docs tree)
+- Existing reference: `client/plugins/network-tools/` in the Jinn monorepo.

package/templates/plugins/runtime-plugin/gitignore.tmpl

@@ -0,0 +1,3 @@
+node_modules/
+.DS_Store
+*.log

package/templates/plugins/runtime-plugin/jinn.plugin.json.tmpl

@@ -0,0 +1,21 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "jinn": {
+    "supports": ["jinn.runtime"],
+    "capabilities": {
+      "tools": {
+        "example": [
+          "example_tool"
+        ]
+      }
+    },
+    "mcpServers": {
+      "example": {
+        "command": "node",
+        "args": ["mcp/server.mjs"]
+      }
+    },
+    "description": "Example runtime SolverPlugin exposing one MCP tool."
+  }
+}

package/templates/plugins/runtime-plugin/mcp/server.mjs.tmpl

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+// Minimal MCP server stub.
+//
+// Replace this body with a real MCP server implementation (e.g. via
+// @modelcontextprotocol/sdk) that exposes the tools declared in
+// jinn.plugin.json's jinn.mcpServers.example.
+
+import { createInterface } from 'node:readline';
+
+const rl = createInterface({ input: process.stdin });
+
+rl.on('line', (line) => {
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return;
+  }
+  if (msg?.method === 'initialize') {
+    process.stdout.write(
+      JSON.stringify({
+        jsonrpc: '2.0',
+        id: msg.id,
+        result: {
+          protocolVersion: '2024-11-05',
+          capabilities: { tools: {} },
+          serverInfo: { name: '{{packageNameSlug}}-example', version: '0.1.0' },
+        },
+      }) + '\n',
+    );
+  }
+});

package/templates/plugins/runtime-plugin/package.json.tmpl

@@ -0,0 +1,15 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn runtime SolverPlugin — exposes MCP tools available to every harness session.",
+  "type": "module",
+  "files": ["jinn.plugin.json", ".mcp.json", "mcp/", "README.md"],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  },
+  "keywords": ["jinn", "solver-plugin", "runtime", "mcp"],
+  "license": "MIT"
+}

package/templates/plugins/runtime-plugin/test/plugin.test.ts.tmpl

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+describe('{{packageName}} runtime manifest', () => {
+  it('has a valid jinn.plugin.json declaring jinn.runtime', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(ROOT, 'jinn.plugin.json'), 'utf8'),
+    );
+    expect(manifest.name).toBe('{{packageName}}');
+    expect(manifest.jinn.supports).toEqual(['jinn.runtime']);
+  });
+
+  it('has a .mcp.json mirroring the jinn.plugin.json mcpServers block', () => {
+    expect(existsSync(join(ROOT, '.mcp.json'))).toBe(true);
+    const mcp = JSON.parse(readFileSync(join(ROOT, '.mcp.json'), 'utf8'));
+    expect(mcp.mcpServers).toBeDefined();
+    expect(Object.keys(mcp.mcpServers).length).toBeGreaterThan(0);
+  });
+
+  it('every declared MCP server entry-point file exists', () => {
+    const mcp = JSON.parse(readFileSync(join(ROOT, '.mcp.json'), 'utf8'));
+    for (const [, server] of Object.entries(mcp.mcpServers as Record<string, { args?: string[] }>)) {
+      const args = server.args ?? [];
+      for (const arg of args) {
+        if (arg.endsWith('.mjs') || arg.endsWith('.js') || arg.endsWith('.ts')) {
+          expect(existsSync(join(ROOT, arg)), `missing MCP entry file: ${arg}`).toBe(true);
+        }
+      }
+    }
+  });
+});

package/templates/plugins/runtime-plugin/tsconfig.json.tmpl

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["test/**/*.ts"]
+}

package/templates/plugins/solver-type-plugin/README.md.tmpl

@@ -0,0 +1,35 @@
+# {{packageName}}
+
+Jinn SolverPlugin targeting `{{solverTypeString}}`.
+
+## What this is
+
+A SolverPlugin is a package that drops into a Jinn-running harness (Hermes, Claude Code, Codex) and contributes skills + MCP tools when the harness runs a task on `{{solverTypeString}}`. See the canonical `/docs/build/` tree for the full builder reference.
+
+## Get started
+
+```bash
+yarn install
+yarn test
+```
+
+Edit `skills/example/SKILL.md` with the actual skill content you want to ship. Add new skill files under `skills/<name>/SKILL.md` and add their paths to `jinn.plugin.json`'s `jinn.skills` array.
+
+## Publish
+
+When ready to ship:
+
+```bash
+# Validate the manifest first
+jinn solver-plugins validate path:.
+
+# Publish to the Jinn network
+jinn solver-plugins publish path:.
+```
+
+The published plug-in becomes discoverable to operators running `{{solverTypeString}}` SolverNets.
+
+## Reference
+
+- Quickstart: https://github.com/Jinn-Network/mono/blob/main/cargo/docs/build/quickstart.md (placeholder until `52x3.6` ships the canonical docs tree)
+- Spec: `docs/superpowers/specs/2026-05-13-plug-in-builder-entry-point-design.md`

package/templates/plugins/solver-type-plugin/gitignore.tmpl

@@ -0,0 +1,3 @@
+node_modules/
+.DS_Store
+*.log

package/templates/plugins/solver-type-plugin/jinn.plugin.json.tmpl

@@ -0,0 +1,11 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "jinn": {
+    "supports": ["{{solverTypeString}}"],
+    "skills": [
+      "skills/example/SKILL.md"
+    ],
+    "description": "Example SolverPlugin for {{solverTypeString}}."
+  }
+}

package/templates/plugins/solver-type-plugin/package.json.tmpl

@@ -0,0 +1,15 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn SolverPlugin for {{solverTypeString}}.",
+  "type": "module",
+  "files": ["jinn.plugin.json", "skills/", "README.md"],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  },
+  "keywords": ["jinn", "solver-plugin", "{{solverTypeString}}"],
+  "license": "MIT"
+}

package/templates/plugins/solver-type-plugin/skills/example/SKILL.md.tmpl

@@ -0,0 +1,10 @@
+---
+name: {{packageNameSlug}}-example
+description: An example skill that ships with the {{packageName}} plug-in. Replace this body with your plug-in's actual skill content.
+---
+
+# Example skill
+
+This skill is a placeholder. Replace its body with content that helps a solver agent attempt `{{solverTypeString}}` tasks.
+
+Skills are markdown files with YAML frontmatter. The frontmatter's `name` and `description` are used by harnesses to decide when to load the skill into context.

package/templates/plugins/solver-type-plugin/test/plugin.test.ts.tmpl

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+describe('{{packageName}} manifest', () => {
+  it('has a valid jinn.plugin.json', () => {
+    const manifestPath = join(ROOT, 'jinn.plugin.json');
+    expect(existsSync(manifestPath)).toBe(true);
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    expect(manifest.name).toBe('{{packageName}}');
+    expect(manifest.jinn.supports).toContain('{{solverTypeString}}');
+    expect(Array.isArray(manifest.jinn.skills)).toBe(true);
+  });
+
+  it('every declared skill file exists', () => {
+    const manifestPath = join(ROOT, 'jinn.plugin.json');
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    for (const skill of manifest.jinn.skills ?? []) {
+      expect(existsSync(join(ROOT, skill)), `missing skill file: ${skill}`).toBe(true);
+    }
+  });
+});

package/templates/plugins/solver-type-plugin/tsconfig.json.tmpl

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["test/**/*.ts"]
+}