@volter/supercode-orchestrator 0.4.8 → 0.4.10

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/apply/doors.mjs

@@ -72,7 +72,7 @@ export function differs(want, live) {
  */
 function declaredOnly(spec, inference, rename) {
   const want = { schedule: spec.schedule };
-  for (const field of ['prompt', 'skills', 'deliver', 'workdir', 'repeat', 'script', 'no_agent', 'monitor_script', 'monitor_url', 'toolsets', 'context_from']) {
+  for (const field of ['prompt', 'skills', 'deliver', 'attach_to_session', 'workdir', 'repeat', 'script', 'no_agent', 'monitor_script', 'monitor_url', 'toolsets', 'context_from']) {
     if (spec[field] !== undefined) want[rename[field] ?? field] = spec[field];
   }
   if (spec.model !== undefined) Object.assign(want, namedModel(spec, inference));
@@ -152,7 +152,7 @@ export function hermesDoor({ home, python = null, source = null, runner = null,
     id: job.id,
     name: job.name ?? null,
     managed: {
-      schedule: job.schedule ?? null, prompt: job.prompt ?? null, skills: job.skills ?? null, deliver: job.deliver ?? null,
+      schedule: job.schedule ?? null, prompt: job.prompt ?? null, skills: job.skills ?? null, deliver: job.deliver ?? null, attach_to_session: job.attach_to_session ?? null,
       model: job.model ?? null, provider: job.provider ?? null, workdir: job.workdir ?? null, repeat: job.repeat?.times ?? null,
       script: job.script ?? null, no_agent: Boolean(job.no_agent), monitor_script: job.monitor_script ?? null,
       monitor_url: job.monitor_url ?? null, enabled_toolsets: job.enabled_toolsets ?? null, context_from: job.context_from ?? null,
@@ -234,7 +234,7 @@ export async function orchestratorDoor({ root, profile = 'default', load, socket
     id: job.id,
     name: job.residue?.name ?? null,
     managed: {
-      schedule: job.schedule ?? null, prompt: job.prompt ?? null, skills: job.skills ?? null, deliver: deliver(job.deliver),
+      schedule: job.schedule ?? null, prompt: job.prompt ?? null, skills: job.skills ?? null, deliver: deliver(job.deliver), attach_to_session: job.attach_to_session ?? null,
       model: job.model ?? null, workdir: job.workdir ?? null, repeat: job.repeat?.times ?? null,
       script: job.residue?.script ?? null, no_agent: job.residue?.no_agent === true, monitor_script: job.residue?.monitor_script ?? null,
       monitor_url: job.residue?.monitor_url ?? null, context_from: job.context_from ?? null,
@@ -254,7 +254,7 @@ export async function orchestratorDoor({ root, profile = 'default', load, socket
     return row;
   };
   /** What jobs.update can change; a change to anything else is refused per record, never dropped. */
-  const UPDATABLE = new Set(['schedule', 'prompt', 'deliver', 'model', 'workdir', 'script', 'no_agent', 'monitor_script', 'monitor_url']);
+  const UPDATABLE = new Set(['schedule', 'prompt', 'deliver', 'attach_to_session', 'model', 'workdir', 'script', 'no_agent', 'monitor_script', 'monitor_url']);
   return {
     target: 'orchestrator',
     list,
@@ -289,4 +289,4 @@ export async function orchestratorDoor({ root, profile = 'default', load, socket
 }
 
 /** The job fields the applier owns: the union both doors read (a door that has no such field reads null). */
-export const MANAGED_JOB_FIELDS = Object.freeze(['schedule', 'prompt', 'skills', 'deliver', 'model', 'provider', 'workdir', 'repeat', 'script', 'no_agent', 'monitor_script', 'monitor_url', 'enabled_toolsets', 'context_from']);
+export const MANAGED_JOB_FIELDS = Object.freeze(['schedule', 'prompt', 'skills', 'deliver', 'attach_to_session', 'model', 'provider', 'workdir', 'repeat', 'script', 'no_agent', 'monitor_script', 'monitor_url', 'enabled_toolsets', 'context_from']);

package/cron.mjs

@@ -12,7 +12,7 @@
 
 import { surfaceKeyString } from './ir.mjs';
 import { homeChannel } from './ir.mjs';
-import { endBinding, ensureRuntime, leaseId, newObligation, permissionResponse, reply } from './reducer.mjs';
+import { endBinding, ensureRuntime, leaseId, newObligation, permissionResponse, reply, startWorker } from './reducer.mjs';
 
 /** Retry delays after the 1st, 2nd and 3rd send attempt (§4.3 "retry pending obligations"). */
 export const BACKOFF_MINUTES = Object.freeze([1, 2, 4]);
@@ -799,6 +799,7 @@ function launchFire(state, profile, job, fire, prompt, now, effects) {
     deliverResult(state, profile, { job, fire }, fire.error, true, now, effects);
     return;
   }
+  if (job.attach_to_session === true && attachFire(state, profile, job, fire, prompt, now, effects)) return;
   const rt = ensureRuntime(state);
 
   const key = { platform: 'cron', kind: 'dm', chat_id: job.id };
@@ -819,6 +820,42 @@ function launchFire(state, profile, job, fire, prompt, now, effects) {
   effects.push({ type: 'save' });
 }
 
+/**
+ * `attach_to_session`: the fire is a turn in the live session of the conversation it delivers to, taken the way an
+ * inbound message there is: it steers the running turn where the worker takes input mid-turn, waits behind it
+ * otherwise, and reopens the conversation's own session when its worker is gone. The conversation's reply is the
+ * delivery, so the fire is done once it is handed over. False (a session of its own) when that conversation has
+ * no live binding.
+ */
+function attachFire(state, profile, job, fire, prompt, now, effects) {
+  const target = resolveTarget(job, profile);
+  if (!target?.platform) return false;
+  const found = Object.entries(profile.bindings).find(([ks, b]) => !b.ended_at && !ks.includes('#')
+    && b.key.platform === target.platform && String(b.key.chat_id ?? '') === String(target.chat_id ?? '')
+    && String(b.key.thread_id ?? '') === String(target.thread_id ?? ''));
+  if (!found) return false;
+  const [keyString, binding] = found;
+  const rt = ensureRuntime(state);
+  const lid = leaseId(profile.name, keyString);
+  if (!rt.leases[lid] && !rt.turns[lid] && !rt.starting[lid]) {
+    if (binding.worker.session_id) binding.residue.resume_runtime_id ??= binding.residue.runtime_id ?? binding.worker.session_id;
+    startWorker(state, profile, keyString, effects);
+  }
+  binding.last_activity_at = now;
+  const text = `[scheduled: ${job.name ?? job.id}] ${prompt}`;
+  if (rt.turns[lid] && rt.leases[lid]?.steer) effects.push({ type: 'steer_input', profile: profile.name, keyString, text });
+  else if (rt.turns[lid] || !rt.leases[lid]) (rt.queues[lid] ??= []).push({ text, at: now, job_id: job.id });
+  else {
+    rt.turns[lid] = { started_at: now, buffer: '' };
+    effects.push({ type: 'send_input', profile: profile.name, keyString, text });
+  }
+  fire.started_at = now;
+  fire.residue = { ...(fire.residue ?? {}), attached_to: keyString };
+  finishFire(profile, fire, job, 'succeeded', now, null, effects);
+  effects.push({ type: 'save' });
+  return true;
+}
+
 function retryObligations(state, profile, now, effects) {
   const rt = ensureRuntime(state);
   const t = Date.parse(now);

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 }>;

package/index.mjs

@@ -7,7 +7,7 @@ export { load, save, compile, importFrom, exportTo, closeWorld, retainWorld, rel
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "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": {

package/reducer.mjs

@@ -228,7 +228,7 @@ function handleInbound(state, ev, effects) {
  * a burst of messages before the lease exists queues behind ONE start (the
  * `started`/`error` worker events clear the mark).
  */
-function startWorker(state, profile, keyString, effects) {
+export function startWorker(state, profile, keyString, effects) {
   const rt = ensureRuntime(state);
   rt.starting[leaseId(profile.name, keyString)] = true;
   // A binding whose runtime went away with the daemon reopens that same session where its harness can, so the