@volter/supercode-orchestrator 0.4.160 → 0.5.1

package/README.md

@@ -301,11 +301,22 @@ platforms:
       key: ${API_SERVER_KEY}
 ```
 
-RH2 integration attaches through an admin-consented app installation. A hand-written
-`platforms: rh2` block grants no integration authority and the runtime reports it as
-unsupported. The reusable RH2 transport remains in `adapters/rh2.mjs`; the Room-chat
-module supplies its app-owned settings and credentials when that module is installed.
-Native Hermes channel configuration remains the worker's configuration.
+RH2 Room chat is an installed app ([ADR 0017](../../docs/adr/0017-room-chat-is-an-installed-app.md)).
+Register the Room-chat app in the RH2 organization (`organization.read`, `room.read`; a Room's
+manager seats its principal where it should answer), have an admin install it, and exchange the
+code the install returns:
+
+```sh
+supercode orchestrator apps install room-chat --origin https://pilot.runhuman.com \
+  --client-id app_… --client-secret-file ./room-chat.secret --code … --profile default
+supercode orchestrator apps list
+supercode orchestrator apps remove room-chat
+```
+
+The record (with the installation's token) is kept owner-only under `<home>/apps/`; the next
+daemon start attaches the `rh2` channel for that profile. Uninstalling in RH2 revokes the token and
+the channel stops. A `platforms: rh2` block grants no integration authority and the runtime reports
+it as unsupported. Native Hermes channel configuration remains the worker's configuration.
 
 **The Chat SDK sidecar** mounts `chat@4.39.0` (npm package `chat`, repo `vercel/chat`; a
 devDependency of this package, installed alongside `@chat-adapter/state-memory@4.39.0`). The

package/adapters/chat-sdk.mjs

@@ -196,7 +196,10 @@ export class ChatSdkAdapter {
   async credentials() {
     const slug = String(this.extra('slug', this.platform));
     const hermes = HERMES_PLATFORMS[slug];
-    if (hermes && !Object.keys(this.channel?.credentials ?? {}).length) {
+    // A block naming only Hermes's own variables (as the loader fills them in) is Hermes's block: Hermes's transport
+    // and its whole variable set, never a partial credential set in the package's default mode.
+    const refs = Object.values(this.channel?.credentials ?? {});
+    if (hermes && refs.every((ref) => Object.values(hermes.env).includes(ref.dotenv ?? ref.env))) {
       // Hermes's own variables, from the owning profile's own .env only (a
       // named profile's token never serves the root's block, Hermes #59739)
       const file = this.profileDir ? join(this.profileDir, '.env') : null;

package/adapters/rh2.mjs

@@ -16,9 +16,8 @@
 //   PATCH /rooms/:room/conversations/:c/messages/:id        {body} — a streamed reply grows, a progress line updates, by edit
 //   POST /rooms/:room/conversations/:c/presence            {state: "typing"} — best effort, forgotten on 404
 //
-// This is reusable transport code. The daemon does not attach it from a
-// platforms block; an installed integration module owns its settings and token.
-// See docs/adr/0006-teams-installable-apps.md (C1) and the Room-chat module (M4).
+// The Room-chat app (docs/adr/0017-room-chat-is-an-installed-app.md) attaches it with its RH2 installation's
+// origin, organization, principal and token; a `platforms:` block never does.
 //
 // The surface key is `{platform: 'rh2', kind: 'channel', chat_id: '<roomId>'}`: a Room is one surface, so the agent it
 // seats is one session however many of the Room's conversations it takes part in. A line wakes it where RH2 says the bot
@@ -67,31 +66,24 @@ export class Rh2Adapter {
     return e[`extra.${name}`] ?? e[name] ?? fallback;
   }
 
-  /** The bearer: `credentials.token` resolved from the vault (a ref, never a value in the model). */
+  /** The bearer: the installation's token. */
   token() {
-    const ref = this.channel?.credentials?.token ?? this.channel?.credentials?.['extra.token'];
-    if (ref) {
-      const name = ref.dotenv ?? ref.env;
-      const value = this.vault.get(name) ?? (ref.env ? process.env[ref.env] : undefined);
-      if (value === undefined) throw new Error(`platforms.${this.platform}.token: ref ${name} is not in the vault`);
-      return value;
-    }
-    const direct = this.extra('token') ?? process.env.RH2_SESSION_TOKEN;
-    if (!direct) throw new Error(`platforms.${this.platform}: no token (credentials.token or RH2_SESSION_TOKEN)`);
+    const direct = this.extra('token');
+    if (!direct) throw new Error(`${this.platform}: the installation carries no token`);
     return direct;
   }
 
-  apiUrl() { return String(this.extra('api_url') ?? process.env.RH2_API_URL ?? '').replace(/\/+$/, ''); }
-  organization() { return String(this.extra('organization') ?? process.env.RH2_ORGANIZATION ?? ''); }
-  principalId() { return String(this.extra('principal_id') ?? process.env.RH2_PRINCIPAL_ID ?? ''); }
-  pollMs() { const n = Number(this.extra('poll_seconds', process.env.RH2_POLL_SECONDS)); return Number.isFinite(n) && n > 0 ? Math.max(500, n * 1000) : DEFAULT_POLL_MS; }
+  apiUrl() { return String(this.extra('api_url') ?? '').replace(/\/+$/, ''); }
+  organization() { return String(this.extra('organization') ?? ''); }
+  principalId() { return String(this.extra('principal_id') ?? ''); }
+  pollMs() { const n = Number(this.extra('poll_seconds')); return Number.isFinite(n) && n > 0 ? Math.max(500, n * 1000) : DEFAULT_POLL_MS; }
   followedRooms() {
-    const raw = this.extra('rooms') ?? process.env.RH2_ROOMS ?? '';
+    const raw = this.extra('rooms') ?? '';
     return (Array.isArray(raw) ? raw : String(raw).split(',')).map((s) => String(s).trim()).filter(Boolean);
   }
   headers() {
     let extra = {};
-    const raw = this.extra('headers') ?? process.env.RH2_API_HEADERS;
+    const raw = this.extra('headers');
     if (raw) {
       try { extra = typeof raw === 'string' ? JSON.parse(raw) : raw; } catch { this.log('warn', `${this.platform}: headers is not a JSON object; ignored`); }
     }
@@ -125,7 +117,7 @@ export class Rh2Adapter {
 
   async connect(emit) {
     this.emit = emit;
-    if (!this.apiUrl() || !this.organization()) throw new Error(`platforms.${this.platform}: api_url and organization are required`);
+    if (!this.apiUrl() || !this.organization()) throw new Error(`${this.platform}: the installation names no origin or organization`);
     this.token();
     await this.refreshRooms();
     this.running = true;
@@ -208,6 +200,12 @@ export class Rh2Adapter {
         await this.sleep(this.pollMs());
       } catch (error) {
         if (!this.running) return;
+        // The installation's token refused for good: the app was uninstalled in RH2, and its channel stops.
+        if (error.status === 401) {
+          this.running = false;
+          this.log('error', `${this.platform}: the installation's token was refused (uninstalled in RH2?); the channel stops: ${error.message}`);
+          return;
+        }
         failures += 1;
         const delay = Math.min(60_000, 2000 * 2 ** Math.min(failures, 5));
         this.log('warn', `${this.platform}: poll error ${error.message}; retrying in ${delay / 1000}s`);

package/agent-home.mjs

@@ -0,0 +1,35 @@
+// Configuration is a profile's template; Hermes's mutable memory and sessions belong to one agent.
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { linkTo, skillSources } from './hermes-home.mjs';
+
+/** The immutable agent id keeps one home across sessions, profile changes and its move from local to an Org.
+ * Ids are minted globally unique, so the Org is checked but not part of the key. */
+export function agentStateHome(root, org, id) {
+  if (!org || !id) throw new Error('agent state requires an Org and an immutable agent id');
+  const key = createHash('sha256').update(JSON.stringify(['agent', id])).digest('hex');
+  return join(resolve(root), '.agent-state', key, 'hermes');
+}
+
+/** Refresh only declared inputs. Never copy a profile's memories, session database or environment. */
+export function materializeAgentHome(root, org, id, profile) {
+  const home = agentStateHome(root, org, id);
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  for (const name of ['config.yaml', 'AGENTS.md', '.mcp.json']) {
+    const source = join(profile.dir, name), target = join(home, name);
+    const contents = existsSync(source) ? readFileSync(source) : Buffer.from(name === 'AGENTS.md' ? '' : '{}\n');
+    if (existsSync(target) && readFileSync(target).equals(contents)) continue;
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, contents, { mode: 0o600 });
+    renameSync(temporary, target);
+  }
+  linkTo(join(home, 'SOUL.md'), 'AGENTS.md');
+  const skills = join(home, '.agents', 'skills');
+  mkdirSync(skills, { recursive: true, mode: 0o700 });
+  // These are template inputs. The agent's mutable state directories are never linked to a profile.
+  const inputs=skillSources(profile.dir);
+  for(const entry of readdirSync(skills,{withFileTypes:true}))if(entry.isSymbolicLink()&&!inputs.has(entry.name))unlinkSync(join(skills,entry.name));
+  for (const [name, source] of inputs) linkTo(join(skills, name), resolve(source));
+  return home;
+}

package/agent-profiles.mjs

@@ -0,0 +1,53 @@
+// Profile intent is layered configuration. It never owns the agent's memory.
+const object=value=>value!=null&&typeof value==='object'&&!Array.isArray(value);
+const copy=value=>structuredClone(value);
+const failure=message=>{throw new Error(message);};
+
+/** Permission layers are retained separately: an evaluator must admit the action in every layer. */
+export function resolveAgentProfile(profiles, name, overlays=[]) {
+  const seen=new Set(),chain=[];
+  function visit(id) {
+    if(seen.has(id))failure(`profile inheritance cycle at ${id}`);
+    const profile=profiles[id];if(!object(profile))failure(`profile ${id} does not exist`);
+    seen.add(id);if(profile.parent)visit(profile.parent);chain.push({name:id,value:profile});seen.delete(id);
+  }
+  visit(name);
+  for(const [index,value] of overlays.entries()){
+    if(!object(value))failure('a session profile overlay must be an object');
+    chain.push({name:`session:${index}`,value});
+  }
+  let resolved={},permissionLayers=[];
+  for(const {value} of chain){
+    if(Object.hasOwn(value,'memory'))failure('memory is agent state, not profile configuration');
+    resolved=merge(resolved,Object.fromEntries(Object.entries(value).filter(([key])=>key!=='permissions'&&key!=='parent')));
+    if(value.permissions!=null)permissionLayers.push(copy(value.permissions));
+  }
+  delete resolved.parent;resolved.permissions={layers:permissionLayers};
+  return {profile:name,layers:chain.map(x=>x.name),resolved};
+}
+function merge(parent,child){
+  const result=copy(parent);
+  for(const [key,value] of Object.entries(child)){
+    result[key]=object(value)&&object(result[key])?merge(result[key],value):copy(value);
+  }
+  return result;
+}
+
+/** A difference is evidence of actual execution, never an update to the intended profile. */
+export function profileDifferences(intended, actual) {
+  const differences=[];
+  const visit=(left,right,path)=>{
+    if(object(left)&&object(right))for(const key of new Set([...Object.keys(left),...Object.keys(right)]))visit(left[key],right[key],path?`${path}.${key}`:key);
+    else if(JSON.stringify(left)!==JSON.stringify(right))differences.push({field:path,intended:left??null,actual:right??null});
+  };
+  visit(intended,actual,'');return differences;
+}
+
+/** Principal kinds never flow into an agent. A plain session remains plain absent a declaration/profile identity. */
+export function sessionAgent({starter,declared=null,asAgent=null,profileAgent=null}) {
+  if(declared)return declared;
+  if(asAgent)return asAgent;
+  if(starter?.kind==='agent')return starter.id;
+  if(starter?.kind==='session')return starter.agent??null;
+  return profileAgent??null;
+}