@volter/supercode-orchestrator 0.4.7 → 0.4.9

package/activation.mjs

@@ -3,6 +3,7 @@
 // subfolder named by its id, pointed at through the harness's own env var.
 
 import { join, relative, resolve } from 'node:path';
+import { homedir } from 'node:os';
 import { mkdirSync, readFileSync, readdirSync, lstatSync, rmSync, writeFileSync, existsSync } from 'node:fs';
 import { CLAUDE_BRIDGE, linkTo, skillSources } from './hermes-home.mjs';
 
@@ -40,7 +41,10 @@ export function activationEnv({ root, profile, surfaceKey, vault }) {
   const env = {};
   const worker = profile.worker;
   const homeVar = HOME_ENV[worker.harness];
-  if (homeVar) env[homeVar] = join(profile.dir, worker.harness);
+  // `home: user` keeps the user's own harness home (their CLAUDE.md, skills, hooks, plugins, MCP servers and login);
+  // the profile's persona and skills come in beside it through the launch (userHomeArguments).
+  if (worker.home === 'user') env.HOME = homedir();
+  else if (homeVar) env[homeVar] = join(profile.dir, worker.harness);
   for (const [k, v] of Object.entries(worker.env ?? {})) env[k] = resolveRef(v, vault);
   env[ORCH_ENV.root] = root;
   env[ORCH_ENV.profile] = profile.name;
@@ -91,6 +95,28 @@ export function materializePersona(profile) {
  */
 export const HOME_SKILLS = Object.freeze({ codex: 'skills', 'claude-code': 'skills' });
 
+/** The harnesses a worker can run in the user's own home, with the profile brought in beside it. */
+export const USER_HOME_HARNESSES = Object.freeze(new Set(['claude-code']));
+
+/**
+ * The launch arguments that bring a profile's skills in beside the user's own Claude home (`home: user`): its
+ * skills folder as a session plugin (Claude Code's `--plugin-dir`; the folder carries the plugin manifest
+ * materializeSkills writes). Nothing for a worker in the profile's home.
+ */
+export function userHomeArguments(profile) {
+  const worker = profile.worker;
+  if (worker?.home !== 'user') return [];
+  if (!USER_HOME_HARNESSES.has(worker.harness)) throw new Error(`worker.home: user is not available for ${worker.harness} workers`);
+  return ['--plugin-dir', join(profile.dir, worker.harness)];
+}
+
+/** The persona a worker in the user's own home carries in its system prompt (its home's CLAUDE.md is the user's). */
+export function userHomePersona(profile) {
+  if (profile.worker?.home !== 'user') return '';
+  const persona = join(profile.dir, 'AGENTS.md');
+  return existsSync(persona) ? readFileSync(persona, 'utf8').trim() : '';
+}
+
 export function materializeSkills(profile) {
   const worker = profile.worker;
   const sub = worker && HOME_SKILLS[worker.harness];
@@ -98,6 +124,13 @@ export function materializeSkills(profile) {
   const sources = skillSources(profile.dir);
   const into = join(profile.dir, worker.harness, sub);
   mkdirSync(into, { recursive: true });
+  // In the user's own home the folder is loaded as a session plugin, which needs its manifest.
+  if (worker.home === 'user') {
+    const manifest = join(profile.dir, worker.harness, '.claude-plugin', 'plugin.json');
+    const text = `${JSON.stringify({ name: profile.name, description: `The ${profile.name} profile's skills` }, null, 2)}\n`;
+    mkdirSync(join(profile.dir, worker.harness, '.claude-plugin'), { recursive: true });
+    if (!existsSync(manifest) || readFileSync(manifest, 'utf8') !== text) writeFileSync(manifest, text);
+  }
   for (const [name, from] of sources) linkTo(join(into, name), relative(into, from));
   for (const entry of readdirSync(into)) {
     const path = join(into, entry);

package/adapters/rh2.mjs

@@ -45,11 +45,12 @@ const CLOCK_SKEW_MS = 60_000;
 const ECHO_MEMORY = 500;
 
 export class Rh2Adapter {
-  constructor({ platform = 'rh2', profile = 'default', channel = null, vault = new Map(), log = () => {}, fetchImpl = globalThis.fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  constructor({ platform = 'rh2', profile = 'default', channel = null, vault = new Map(), refreshVault = () => false, log = () => {}, fetchImpl = globalThis.fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
     this.platform = platform;
     this.profile = profile;
     this.channel = channel;
     this.vault = vault;
+    this.refreshVault = refreshVault;
     this.log = log;
     this.fetch = fetchImpl;
     this.sleep = sleep;
@@ -110,7 +111,13 @@ export class Rh2Adapter {
   async get(path, params = {}) {
     const url = new URL(`${this.apiUrl()}/api/v3${path}`);
     for (const [k, v] of Object.entries(params)) url.searchParams.set(k, String(v));
-    const res = await this.fetch(url, { headers: this.headers() });
+    let res = await this.fetch(url, { headers: this.headers() });
+    // A refused credential may have been replaced in the home's `.env` since it was read: read it again and, when
+    // it changed, retry with it, so replacing the bot's session never needs a restart.
+    if (res.status === 401 && this.refreshVault()) {
+      this.log('info', `${this.platform}: credential refused; retrying with the one now in the home's .env`);
+      res = await this.fetch(url, { headers: this.headers() });
+    }
     if (!res.ok) {
       const error = new Error(`GET ${path} -> HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
       error.status = res.status;

package/bin/orchestrator.mjs

@@ -61,7 +61,7 @@ import { adoptHome } from '../hermes-home.mjs';
 import { hermesAccess } from '../hermes-cli.mjs';
 
 import {
-  load, save, step, importFrom, exportTo, closeWorld, Orchestrator, LoopbackAdapter,
+  load, save, refreshVault, step, importFrom, exportTo, closeWorld, Orchestrator, LoopbackAdapter,
   ChatSdkAdapter, ApiServerAdapter, Rh2Adapter,
   TICK_MS, accessPolicy, applyOperator, performRemoveProfileDir, OPERATOR_OPS,
 } from '../index.mjs';
@@ -80,7 +80,7 @@ const ADAPTERS = {
   loopback: (platform, profile) => new LoopbackAdapter({ platform, profile }),
   'chat-sdk': (platform, profile, ctx) => new ChatSdkAdapter({ platform, profile, profileDir: ctx.state.profiles[profile]?.dir ?? null, channel: ctx.channel, vault: ctx.vault, log: ctx.log }),
   api_server: (platform, profile, ctx) => new ApiServerAdapter({ platform, profile, channel: ctx.channel, vault: ctx.vault, state: ctx.state, log: ctx.log }),
-  rh2: (platform, profile, ctx) => new Rh2Adapter({ platform, profile, channel: ctx.channel, vault: ctx.vault, log: ctx.log }),
+  rh2: (platform, profile, ctx) => new Rh2Adapter({ platform, profile, channel: ctx.channel, vault: ctx.vault, refreshVault: () => refreshVault(ctx.state, ctx.vault), log: ctx.log }),
 };
 
 /// The selector a `platforms:` block resolves through: its `extra.adapter`

package/index.d.ts

@@ -195,6 +195,12 @@ export function materializePersona(profile: Profile): Path | null;
 export const HOME_ENV: Readonly<Record<HarnessId, string>>;
 /** Links each skill the profile has into the worker's config home `skills/` (Codex, Claude Code); answers that folder, or null. */
 export function materializeSkills(profile: Profile): Path | null;
+/** Harnesses whose worker can run in the user's own home (`worker.home: user`). */
+export const USER_HOME_HARNESSES: ReadonlySet<string>;
+/** `--plugin-dir <profile>/<harness>` for a worker in the user's own home; nothing otherwise. */
+export function userHomeArguments(profile: { dir: string; worker?: { harness: string; home?: 'profile' | 'user' } }): string[];
+/** The profile's persona text for a worker in the user's own home; empty otherwise. */
+export function userHomePersona(profile: { dir: string; worker?: { harness: string; home?: 'profile' | 'user' } }): string;
 export const HOME_SKILLS: Readonly<Record<HarnessId, string>>;
 export const HOME_PERSONA: Readonly<Record<HarnessId, Readonly<Record<string, 'link' | 'bridge'>>>>;
 export const ORCH_ENV: Readonly<{ root: string; profile: string; surface: string }>;
@@ -440,6 +446,8 @@ export function emptyRuntime(): RuntimeState;
 export function canonicalJson(value: unknown): string;
 export function persistedView(state: OrchestratorState): Omit<OrchestratorState, 'runtime'>;
 export function parseDotenv(text: string): Map<string, string>;
+/** Read every profile's `.env` into `vault` again, in place; true when a value changed. */
+export function refreshVault(state: { profiles: Record<string, { dir: string }> }, vault: Map<string, string>): boolean;
 
 export const CHAT_TYPES: Set<ChatType>;
 export const END_REASONS: Set<EndReason>;

package/index.mjs

@@ -3,11 +3,11 @@ export {
   renderSurfaceKey, parseSurfaceKey, surfaceKeyString, parseTarget, renderTarget, resolveRoute, routeSpecificity,
   emptyState, emptyProfile, emptyRuntime, canonicalJson, persistedView, decodeContextFrom,
 } from './ir.mjs';
-export { load, save, compile, importFrom, exportTo, closeWorld, retainWorld, releaseWorld, stateOf, parseDotenv, supercodeCommand } from './orchestration.mjs';
+export { load, save, compile, importFrom, exportTo, closeWorld, retainWorld, releaseWorld, stateOf, parseDotenv, supercodeCommand, refreshVault } from './orchestration.mjs';
 export { step, expired, leaseId, accessPolicy, dmBehavior } from './reducer.mjs';
 export * as events from './events.mjs';
 export { parseCommand, frame, COMMANDS, REPLY } from './commands.mjs';
-export { activationEnv, activationCwd, materializePersona, materializeSkills, HOME_ENV, HOME_PERSONA, HOME_SKILLS, ORCH_ENV } from './activation.mjs';
+export { activationEnv, activationCwd, materializePersona, materializeSkills, HOME_ENV, HOME_PERSONA, HOME_SKILLS, ORCH_ENV, USER_HOME_HARNESSES, userHomeArguments, userHomePersona } from './activation.mjs';
 export { Orchestrator, normalizeWorkerEvent, webhookPort, TICK_MS } from './loop.mjs';
 export {
   cronTick, dueJobs, nextRunAt, parseCron, scheduleError, claimFire, finishFire, advanceSchedule, resolveTarget,

package/kanban-worker.mjs

@@ -12,7 +12,7 @@ import { existsSync, statSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
 import { load } from './orchestration.mjs';
-import { INSTRUCTION_ARGUMENTS, activationCwd, activationEnv, sandboxArguments, approvalPolicy, limitArguments, materializePersona, materializeSkills, modelArguments, turnCounter } from './activation.mjs';
+import { INSTRUCTION_ARGUMENTS, activationCwd, activationEnv, sandboxArguments, approvalPolicy, limitArguments, materializePersona, materializeSkills, modelArguments, turnCounter, userHomeArguments, userHomePersona } from './activation.mjs';
 import { workerRoute } from './worker-route.mjs';
 import { KANBAN_ENV, untrustedServerVerdict, hermesApproval, hermesInstall, hermesToolEnv, kanbanPrompt, memorySnapshot, mirrorSession } from './hermes-cli.mjs';
 import { mountOrchestratorMcp } from './mcp/mount.mjs';
@@ -68,7 +68,7 @@ export async function runKanbanWorker(argv, env = process.env) {
   // Hermes's system prompt for a dispatched worker: the home's memory, the task protocol, the task's skills
   const memory = await memorySnapshot(profile.dir).catch(() => '');
   const board = await kanbanPrompt(profile.dir, { skills: args.skills, task: taskId, env: task });
-  const instructions = [memory, board.guidance, board.skills].filter(Boolean).join('\n\n');
+  const instructions = [userHomePersona(profile), memory, board.guidance, board.skills].filter(Boolean).join('\n\n');
 
   const client = new SupercodeHarnessClient(env.SUPERCODE_BIN ? { command: env.SUPERCODE_BIN } : {});
   try {
@@ -85,7 +85,7 @@ async function runTurn({ client, profile, harness, worker, route, root, vault, s
   const reasoning = args.reasoning && harness === 'codex' ? ['-c', `model_reasoning_effort=${JSON.stringify(args.reasoning)}`] : [];
   const launch = {
     program: base.program,
-    arguments: [...(base.arguments ?? []), ...modelArguments(worker), ...route.args, ...(instructions && INSTRUCTION_ARGUMENTS[harness] ? INSTRUCTION_ARGUMENTS[harness](instructions) : []), ...reasoning, ...sandboxArguments(profile, harness), ...limitArguments(profile, worker, (level, line) => say(line))],
+    arguments: [...(base.arguments ?? []), ...modelArguments(worker), ...route.args, ...(instructions && INSTRUCTION_ARGUMENTS[harness] ? INSTRUCTION_ARGUMENTS[harness](instructions) : []), ...userHomeArguments(profile), ...reasoning, ...sandboxArguments(profile, harness), ...limitArguments(profile, worker, (level, line) => say(line))],
     env: { ...(base.env ?? {}), ...runEnv },
   };
   const mount = mountOrchestratorMcp({ root, profile, harness, surfaceKey, launch, vault, task });

package/loop.mjs

@@ -9,7 +9,7 @@ import { basename, join, dirname } from 'node:path';
 import { step, leaseId } from './reducer.mjs';
 import * as events from './events.mjs';
 import { save, retainWorld, releaseWorld } from './orchestration.mjs';
-import { INSTRUCTION_ARGUMENTS, NAME_ARGUMENTS, activationEnv, activationCwd, approvalPolicy, sandboxArguments, limitArguments, materializePersona, materializeSkills, modelArguments, turnCounter } from './activation.mjs';
+import { INSTRUCTION_ARGUMENTS, NAME_ARGUMENTS, activationEnv, activationCwd, approvalPolicy, sandboxArguments, limitArguments, materializePersona, materializeSkills, modelArguments, turnCounter, userHomeArguments, userHomePersona } from './activation.mjs';
 import { workerRoute } from './worker-route.mjs';
 import { hermesAccess, hermesApproval, untrustedServerVerdict, hermesToolEnv, memorySnapshot, mirrorSession, mirrorState, recordIncident, sealMirror } from './hermes-cli.mjs';
 import { hermesSessionKey } from './ir.mjs';
@@ -323,9 +323,11 @@ export class Orchestrator {
       const env = { ...tools, ...activationEnv({ root: this.state.root, profile, surfaceKey: keyString, vault: this.vault }), ...route.env };
       // the home's memory, as Hermes's agent carries it into a session (row 13)
       const memory = INSTRUCTION_ARGUMENTS[worker.harness] ? await memorySnapshot(profile.dir).catch((error) => { this.log('warn', `memory ${keyString}: ${error.message}`); return ''; }) : '';
-      const instructions = memory ? INSTRUCTION_ARGUMENTS[worker.harness](memory) : [];
+      // a worker in the user's own home carries its persona there too (its config home's CLAUDE.md is the user's)
+      const instructionText = [userHomePersona(profile), memory].filter(Boolean).join('\n\n');
+      const instructions = instructionText && INSTRUCTION_ARGUMENTS[worker.harness] ? INSTRUCTION_ARGUMENTS[worker.harness](instructionText) : [];
       const naming = NAME_ARGUMENTS[worker.harness]?.(basename(this.state.root)) ?? [];
-      launch = await this.resolveLaunch(profile, { ...worker, model: route.model }, env, [...route.args, ...instructions, ...naming]);
+      launch = await this.resolveLaunch(profile, { ...worker, model: route.model }, env, [...route.args, ...instructions, ...naming, ...userHomeArguments(profile)]);
     } catch (error) {
       this.enqueue(events.worker({ profile: profileName, keyString, runtime_id: null, ev: { kind: 'error', message: `start failed: ${error.message}` }, at: this.clock() }));
       return;

package/orchestration.mjs

@@ -116,6 +116,17 @@ function readVault(orchestration) {
   return vault;
 }
 
+/**
+ * Read every profile's `.env` into `vault` again, in place, so each reader holding it (a channel adapter) sees a
+ * credential replaced there without a restart. True when a value changed.
+ */
+export function refreshVault(state, vault) {
+  const fresh = readVault(state);
+  let changed = false;
+  for (const [k, v] of fresh) if (vault.get(k) !== v) { vault.set(k, v); changed = true; }
+  return changed;
+}
+
 /** An orchestration value as the loop's state: the persisted half plus an empty runtime half. */
 export function stateOf(orchestration) {
   return { ...orchestration, runtime: emptyRuntime() };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {