@jinn-network/client 0.1.2 → 0.1.3-canary.262e5cda

package/dist/templates/restorer/alternative-harness/src/phases/execute.ts.tmpl

@@ -0,0 +1,33 @@
+import type { RestorationContext } from '@jinn-network/restorer-sdk';
+import type { HarnessAdapter } from '../harness.js';
+import type { PlanResult } from './plan.js';
+import type { StrategyResult } from './strategize.js';
+
+export type ExecuteReturnReason =
+  | 'all-steps-completed'
+  | 'time-budget-exhausted'
+  | 'aborted';
+
+export interface ExecuteResult {
+  stepsCompleted: ReadonlyArray<string>;
+  stepsFailed: ReadonlyArray<string>;
+  returnReason: ExecuteReturnReason;
+}
+
+export async function runExecute(args: {
+  ctx: RestorationContext;
+  harness: HarnessAdapter;
+  plan: PlanResult;
+  strategy: StrategyResult;
+}): Promise<ExecuteResult> {
+  const { ctx, harness, plan, strategy } = args;
+  return harness.promptForJson<ExecuteResult>({
+    promptId: 'execute',
+    systemPrompt:
+      'Carry out the planned steps. Return early when success criteria are met.',
+    userPrompt: JSON.stringify({ intent: ctx.intent, plan, strategy }),
+    // Execute gets the largest budget — leave some room for debrief.
+    budgetMs: Math.min(ctx.msUntilEndTs(), 90_000),
+    abort: ctx.abort,
+  });
+}

package/dist/templates/restorer/alternative-harness/src/phases/improve.ts.tmpl

@@ -0,0 +1,31 @@
+import type { RestorationContext } from '@jinn-network/restorer-sdk';
+import type { HarnessAdapter } from '../harness.js';
+import type { DebriefResult } from './debrief.js';
+
+export interface ImproveResult {
+  mutations: ReadonlyArray<{ path: string; description: string }>;
+}
+
+/**
+ * Mutates impl-state under `ctx.implStateDir` based on what debrief
+ * surfaced. The example returns empty mutations; real impls write
+ * playbooks, calibration tables, or skill snippets.
+ */
+export async function runImprove(args: {
+  ctx: RestorationContext;
+  harness: HarnessAdapter;
+  debrief: DebriefResult;
+}): Promise<ImproveResult> {
+  const { ctx, harness, debrief } = args;
+  return harness.promptForJson<ImproveResult>({
+    promptId: 'improve',
+    systemPrompt:
+      'Propose minimal mutations to impl-state that would help the next attempt.',
+    userPrompt: JSON.stringify({
+      implStateDir: ctx.implStateDir,
+      debrief,
+    }),
+    budgetMs: Math.min(ctx.msUntilEndTs(), 10_000),
+    abort: ctx.abort,
+  });
+}

package/dist/templates/restorer/alternative-harness/src/phases/memory.ts.tmpl

@@ -0,0 +1,31 @@
+import type { RestorationContext } from '@jinn-network/restorer-sdk';
+import type { HarnessAdapter } from '../harness.js';
+import type { DebriefResult } from './debrief.js';
+
+export interface MemoryResult {
+  kept: number;
+  pruned: number;
+}
+
+/**
+ * Garbage-collects long-term memory. The example returns
+ * `{ kept: 0, pruned: 0 }`; real impls trim stale records under
+ * `ctx.implStateDir`.
+ */
+export async function runMemory(args: {
+  ctx: RestorationContext;
+  harness: HarnessAdapter;
+  debrief: DebriefResult;
+}): Promise<MemoryResult> {
+  const { ctx, harness, debrief } = args;
+  return harness.promptForJson<MemoryResult>({
+    promptId: 'memory',
+    systemPrompt: 'Decide which memory items to keep vs prune.',
+    userPrompt: JSON.stringify({
+      implStateDir: ctx.implStateDir,
+      debrief,
+    }),
+    budgetMs: Math.min(ctx.msUntilEndTs(), 10_000),
+    abort: ctx.abort,
+  });
+}

package/dist/templates/restorer/alternative-harness/src/phases/orient.ts.tmpl

@@ -0,0 +1,21 @@
+import type { RestorationContext } from '@jinn-network/restorer-sdk';
+import type { HarnessAdapter } from '../harness.js';
+
+export interface OrientResult {
+  topics: ReadonlyArray<{ name: string; summary: string }>;
+}
+
+export async function runOrient(args: {
+  ctx: RestorationContext;
+  harness: HarnessAdapter;
+}): Promise<OrientResult> {
+  const { ctx, harness } = args;
+  return harness.promptForJson<OrientResult>({
+    promptId: 'orient',
+    systemPrompt:
+      'You are an info-gathering subagent for a Jinn restoration intent.',
+    userPrompt: JSON.stringify({ intent: ctx.intent }),
+    budgetMs: Math.min(ctx.msUntilEndTs(), 30_000),
+    abort: ctx.abort,
+  });
+}

package/dist/templates/restorer/alternative-harness/src/phases/plan.ts.tmpl

@@ -0,0 +1,25 @@
+import type { RestorationContext } from '@jinn-network/restorer-sdk';
+import type { HarnessAdapter } from '../harness.js';
+import type { OrientResult } from './orient.js';
+import type { StrategyResult } from './strategize.js';
+
+export interface PlanResult {
+  steps: ReadonlyArray<{ id: string; description: string }>;
+}
+
+export async function runPlan(args: {
+  ctx: RestorationContext;
+  harness: HarnessAdapter;
+  strategy: StrategyResult;
+  orient: OrientResult;
+}): Promise<PlanResult> {
+  const { ctx, harness, strategy, orient } = args;
+  return harness.promptForJson<PlanResult>({
+    promptId: 'plan',
+    systemPrompt:
+      'Decompose the chosen approach into a small ordered list of steps.',
+    userPrompt: JSON.stringify({ intent: ctx.intent, strategy, orient }),
+    budgetMs: Math.min(ctx.msUntilEndTs(), 15_000),
+    abort: ctx.abort,
+  });
+}

package/dist/templates/restorer/alternative-harness/src/phases/strategize.ts.tmpl

@@ -0,0 +1,29 @@
+import type { RestorationContext } from '@jinn-network/restorer-sdk';
+import type { HarnessAdapter } from '../harness.js';
+import type { OrientResult } from './orient.js';
+
+export type TimingPosture =
+  | 'early-return'
+  | 'hold-and-revise'
+  | 'continuous-observation';
+
+export interface StrategyResult {
+  approach: string;
+  successCriteria: string;
+  timingPosture: TimingPosture;
+}
+
+export async function runStrategize(args: {
+  ctx: RestorationContext;
+  harness: HarnessAdapter;
+  orient: OrientResult;
+}): Promise<StrategyResult> {
+  const { ctx, harness, orient } = args;
+  return harness.promptForJson<StrategyResult>({
+    promptId: 'strategize',
+    systemPrompt: 'You commit to one approach and freeze success criteria.',
+    userPrompt: JSON.stringify({ intent: ctx.intent, orient }),
+    budgetMs: Math.min(ctx.msUntilEndTs(), 20_000),
+    abort: ctx.abort,
+  });
+}

package/dist/templates/restorer/alternative-harness/test/coordinator.test.ts.tmpl

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { runCoordinator } from '../src/coordinator.js';
+import { createMockHarness } from '../src/mock-harness.js';
+import type {
+  ExternalRestorerEnv,
+  RestorationContext,
+} from '@jinn-network/restorer-sdk';
+import type { HarnessAdapter, HarnessPromptArgs } from '../src/harness.js';
+
+const env: ExternalRestorerEnv = {
+  implName: '{{packageName}}',
+  implVersion: '0.1.0',
+  network: '{{network}}',
+  implStateDir: '/tmp/x',
+  secrets: Object.freeze({}),
+  log: () => {},
+  stub: false,
+};
+
+const ctx: RestorationContext = {
+  intent: { id: 'phase-order-1', spec: { kind: '{{kindString}}' } },
+  intentCid: undefined,
+  implStateDir: '/tmp/x',
+  workingDir: '/tmp/x-work',
+  log: () => {},
+  abort: new AbortController().signal,
+  msUntilEndTs: () => 60_000,
+};
+
+describe('runCoordinator', () => {
+  it('invokes phases in order: orient -> strategize -> plan -> execute -> debrief -> improve -> memory', async () => {
+    const calls: string[] = [];
+    const inner = createMockHarness(env);
+    const wrapped: HarnessAdapter = {
+      name: inner.name,
+      async promptForJson<T>(args: HarnessPromptArgs): Promise<T> {
+        calls.push(args.promptId);
+        return inner.promptForJson<T>(args);
+      },
+    };
+    await runCoordinator({ ctx, harness: wrapped });
+    expect(calls).toEqual([
+      'orient',
+      'strategize',
+      'plan',
+      'execute',
+      'debrief',
+      'improve',
+      'memory',
+    ]);
+  });
+});

package/dist/templates/restorer/alternative-harness/test/unit.test.ts.tmpl

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import createRestorer from '../src/index.js';
+import type {
+  ExternalRestorerEnv,
+  RestorationContext,
+} from '@jinn-network/restorer-sdk';
+
+const env: ExternalRestorerEnv = {
+  implName: '{{packageName}}',
+  implVersion: '0.1.0',
+  network: '{{network}}',
+  implStateDir: '/tmp/{{packageNameSlug}}',
+  secrets: Object.freeze({}),
+  log: () => {},
+  stub: false,
+};
+
+function makeCtx(intentId: string): RestorationContext {
+  return {
+    intent: { id: intentId, spec: { kind: '{{kindString}}' } },
+    intentCid: undefined,
+    implStateDir: '/tmp/{{packageNameSlug}}',
+    workingDir: '/tmp/{{packageNameSlug}}-work',
+    log: () => {},
+    abort: new AbortController().signal,
+    msUntilEndTs: () => 60_000,
+  };
+}
+
+describe('{{packageName}}', () => {
+  it('runs all seven phases against the mock harness', async () => {
+    const impl = createRestorer(env);
+    const out = await impl.run(makeCtx('test-1'));
+    expect(out.venueRef.name).toBe('mock-harness');
+    expect(out.gating.executeReturnReason).toBe('all-steps-completed');
+    expect(out.gating.debriefVerdict).toBe('yes');
+  });
+
+  it('threads the strategy timingPosture into gating', async () => {
+    const impl = createRestorer(env);
+    const out = await impl.run(makeCtx('test-2'));
+    expect(out.gating.timingPosture).toBe('early-return');
+  });
+
+  it('declines evaluation intents', () => {
+    const impl = createRestorer(env);
+    expect(
+      impl.supports({ kind: '{{kindString}}', type: 'evaluation' }),
+    ).toBe(false);
+    expect(
+      impl.supports({ kind: '{{kindString}}', type: 'restoration' }),
+    ).toBe(true);
+  });
+});

package/dist/templates/restorer/alternative-harness/tsconfig.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2022", "DOM"],
+    "types": []
+  },
+  "include": ["src/**/*"]
+}

package/dist/templates/restorer/evaluator/README.md.tmpl

@@ -0,0 +1,36 @@
+# {{packageName}}
+
+Jinn external **evaluator** impl for `{{kindString}}` on `{{network}}`.
+
+Evaluators score restoration envelopes after their resolution window
+closes. They emit a `verdictPayload` matching the kind's verdict schema.
+
+## Quickstart
+
+```bash
+yarn install
+yarn test
+```
+
+Edit `src/index.ts` to plug in your scoring rule + oracle. Replace the
+placeholder return with your real `verdictPayload`.
+
+## Coexistence with the in-repo evaluator
+
+If your evaluator targets `{{kindString}}` and there is already an
+in-repo evaluator for that kind
+(`client/src/restorer/impls/{{kindString}}-evaluator/`), the daemon
+registers the in-repo one by default and excludes yours per
+`spec/2026-05-external-restorer-impls.md` §3.4 step 8 (`impl-name-collision`
+resolution).
+
+To run your evaluator instead of the in-repo one, add to your daemon
+config:
+
+```jsonc
+{ "restorers": { "disabled": ["{{kindString}}-evaluator"] } }
+```
+
+## Spec
+
+`spec/2026-04-30-plug-in-surface.md` §3.3.2 (evaluator pattern).

package/dist/templates/restorer/evaluator/gitignore.tmpl

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+.DS_Store

package/dist/templates/restorer/evaluator/jinn.manifest.json.tmpl

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn external evaluator for {{kindString}}.",
+  "supportedKinds": ["{{kindString}}>=1.0.0"],
+  "entry": "./dist/index.js",
+  "package": {
+    "cid": "bafy-PLACEHOLDER",
+    "hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "capabilities": {
+    "rpc": [
+      { "chainId": {{networkChainId}}, "methods": ["eth_call", "eth_blockNumber", "eth_getLogs"] }
+    ]
+  },
+  "signature": {
+    "alg": "ed25519",
+    "publicKey": "PLACEHOLDER",
+    "sig": "PLACEHOLDER"
+  }
+}

package/dist/templates/restorer/evaluator/package.json.tmpl

@@ -0,0 +1,26 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn external evaluator impl for {{kindString}}.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist/", "jinn.manifest.json", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@jinn-network/restorer-sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/dist/templates/restorer/evaluator/src/index.ts.tmpl

@@ -0,0 +1,35 @@
+import type {
+  RestorerImpl,
+  ExternalRestorerEnv,
+  RestorationContext,
+  RestorationOutput,
+} from '@jinn-network/restorer-sdk';
+
+export default function createEvaluator(env: ExternalRestorerEnv): RestorerImpl {
+  return {
+    name: env.implName,
+    version: env.implVersion,
+    supports({ kind, type }) {
+      return kind === '{{kindString}}' && type === 'evaluation';
+    },
+    async isReady() {
+      return env.stub
+        ? { ready: false, reason: 'stub mode' }
+        : { ready: true };
+    },
+    async run(ctx: RestorationContext): Promise<RestorationOutput> {
+      env.log({
+        level: 'info',
+        msg: 'evaluator.run',
+        data: { intentId: ctx.intent.id },
+      });
+      // TODO: read the restoration envelope under evaluation, fetch ground-truth
+      // from your oracle, compute your score. Replace this stub with your impl.
+      return {
+        venueRef: { name: '{{packageName}}' },
+        gating: { score: 0, scoringRule: 'placeholder' },
+        verdictPayload: { score: 0, scoringRule: 'placeholder' },
+      };
+    },
+  };
+}

package/dist/templates/restorer/evaluator/test/unit.test.ts.tmpl

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import createEvaluator from '../src/index.js';
+import type {
+  ExternalRestorerEnv,
+  RestorationContext,
+} from '@jinn-network/restorer-sdk';
+
+const env: ExternalRestorerEnv = {
+  implName: '{{packageName}}',
+  implVersion: '0.1.0',
+  network: '{{network}}',
+  implStateDir: '/tmp/{{packageNameSlug}}',
+  secrets: Object.freeze({}),
+  log: () => {},
+  stub: false,
+};
+
+const ctx: RestorationContext = {
+  intent: { id: 'eval-1', type: 'evaluation', spec: { kind: '{{kindString}}' } },
+  intentCid: undefined,
+  implStateDir: '/tmp/{{packageNameSlug}}',
+  workingDir: '/tmp/{{packageNameSlug}}-work',
+  log: () => {},
+  abort: new AbortController().signal,
+  msUntilEndTs: () => 60_000,
+};
+
+describe('{{packageName}}', () => {
+  it('supports the configured kind only as evaluation', () => {
+    const impl = createEvaluator(env);
+    expect(impl.supports({ kind: '{{kindString}}', type: 'evaluation' })).toBe(
+      true,
+    );
+    expect(impl.supports({ kind: '{{kindString}}', type: 'restoration' })).toBe(
+      false,
+    );
+    expect(impl.supports({ kind: 'other.v0', type: 'evaluation' })).toBe(false);
+  });
+
+  it('produces a verdictPayload with a score field', async () => {
+    const impl = createEvaluator(env);
+    const out = await impl.run(ctx);
+    expect(out.verdictPayload).toBeDefined();
+    expect(typeof (out.verdictPayload as Record<string, unknown>).score).toBe(
+      'number',
+    );
+  });
+});

package/dist/templates/restorer/evaluator/tsconfig.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2022", "DOM"],
+    "types": []
+  },
+  "include": ["src/**/*"]
+}

package/dist/templates/restorer/forecaster/README.md.tmpl

@@ -0,0 +1,25 @@
+# {{packageName}}
+
+Jinn external restorer impl for `{{kindString}}` on `{{network}}`.
+
+## Quickstart
+
+```bash
+yarn install
+yarn test       # unit tests
+yarn build      # produces dist/
+```
+
+Edit `src/index.ts` to plug in your forecasting pipeline. The `run()` method receives a `RestorationContext` (intent + workingDir + capability handles) and returns a `RestorationOutput`.
+
+## Publishing
+
+1. Compute your tarball CID + sha256: `npm pack && ipfs add *.tgz` and `shasum -a 256 *.tgz`.
+2. Update `jinn.manifest.json` with the resulting CID + hash.
+3. Sign the manifest with your ed25519 key (see `spec/2026-05-executor-trust-boundary.md` §5.2).
+4. Pin tarball + signed manifest on IPFS.
+5. Operators install via `jinn impls add ipfs://<manifest-cid>`.
+
+## Spec
+
+See `spec/2026-04-30-plug-in-surface.md` §3.3.1 (forecaster pattern).

package/dist/templates/restorer/forecaster/gitignore.tmpl

@@ -0,0 +1,5 @@
+dist/
+node_modules/
+.DS_Store
+.yarn/cache/
+.yarn/install-state.gz

package/dist/templates/restorer/forecaster/jinn.manifest.json.tmpl

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn external restorer impl for {{kindString}}.",
+  "supportedKinds": ["{{kindString}}>=1.0.0"],
+  "entry": "./dist/index.js",
+  "package": {
+    "cid": "bafy-PLACEHOLDER",
+    "hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "capabilities": {
+    "rpc": [
+      { "chainId": {{networkChainId}}, "methods": ["eth_call", "eth_blockNumber"] }
+    ]
+  },
+  "signature": {
+    "alg": "ed25519",
+    "publicKey": "PLACEHOLDER",
+    "sig": "PLACEHOLDER"
+  }
+}

package/dist/templates/restorer/forecaster/package.json.tmpl

@@ -0,0 +1,26 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn external restorer impl for {{kindString}}.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist/", "jinn.manifest.json", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@jinn-network/restorer-sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/dist/templates/restorer/forecaster/src/index.ts.tmpl

@@ -0,0 +1,33 @@
+import type {
+  RestorerImpl,
+  ExternalRestorerEnv,
+  RestorationContext,
+  RestorationOutput,
+} from '@jinn-network/restorer-sdk';
+
+export default function createRestorer(env: ExternalRestorerEnv): RestorerImpl {
+  return {
+    name: env.implName,
+    version: env.implVersion,
+    supports({ kind, type }) {
+      return kind === '{{kindString}}' && type !== 'evaluation';
+    },
+    async isReady() {
+      return env.stub
+        ? { ready: false, reason: 'stub mode' }
+        : { ready: true };
+    },
+    async run(ctx: RestorationContext): Promise<RestorationOutput> {
+      env.log({
+        level: 'info',
+        msg: 'forecaster.run',
+        data: { intentId: ctx.intent.id },
+      });
+      // TODO: call your existing forecasting pipeline here.
+      return {
+        venueRef: { name: '{{packageName}}' },
+        gating: { probability: 0.5 },
+      };
+    },
+  };
+}

package/dist/templates/restorer/forecaster/test/unit.test.ts.tmpl

@@ -0,0 +1,41 @@
+import { describe, it, expect } from 'vitest';
+import createRestorer from '../src/index.js';
+import type {
+  ExternalRestorerEnv,
+  RestorationContext,
+} from '@jinn-network/restorer-sdk';
+
+const env: ExternalRestorerEnv = {
+  implName: '{{packageName}}',
+  implVersion: '0.1.0',
+  network: '{{network}}',
+  implStateDir: '/tmp/{{packageNameSlug}}',
+  secrets: Object.freeze({}),
+  log: () => {},
+  stub: false,
+};
+
+const ctx: RestorationContext = {
+  intent: { id: 'test', spec: { kind: '{{kindString}}' } },
+  intentCid: undefined,
+  implStateDir: '/tmp/{{packageNameSlug}}',
+  workingDir: '/tmp/{{packageNameSlug}}-work',
+  log: () => {},
+  abort: new AbortController().signal,
+  msUntilEndTs: () => 60_000,
+};
+
+describe('{{packageName}}', () => {
+  it('supports the configured kind', () => {
+    const impl = createRestorer(env);
+    expect(impl.supports({ kind: '{{kindString}}' })).toBe(true);
+    expect(impl.supports({ kind: 'other.v0' })).toBe(false);
+  });
+
+  it('produces a RestorationOutput with a probability', async () => {
+    const impl = createRestorer(env);
+    const out = await impl.run(ctx);
+    expect(out.gating).toHaveProperty('probability');
+    expect(typeof out.gating.probability).toBe('number');
+  });
+});

package/dist/templates/restorer/forecaster/tsconfig.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2022", "DOM"],
+    "types": []
+  },
+  "include": ["src/**/*"]
+}