@volter/editor-core 0.5.57

package/server/coding-inference-launch.ts

@@ -0,0 +1,237 @@
+/**
+ * A CODING HARNESS IS NOT A PROVIDER (owner ruling, 2026-09-21; docs/ARCHITECTURE-CORE.md
+ * §Managed services). Claude Code, Codex, Grok and every harness Supercode runs are
+ * programs the person has ALREADY signed into, so the DEFAULT launch injects nothing —
+ * no model key, no base URL, no provider config — and a harness that is not signed in is
+ * refused BY NAME with its own login command instead of being routed to a metered key.
+ *
+ * `managedInferenceLaunch` below is the ONE opt-in exception: the OpenRouter provider
+ * table a person reaches only by choosing managed or BYOK coding inference for
+ * themselves in the account panel. Its single caller is `withCodingInference` at the
+ * bottom of this file, which reads that explicit `preferredRoute` and passes the backend
+ * params through untouched for every other value — `'auto'` is not a choice.
+ * `scripts/validate-harness-launch.mjs` refuses any provider credential or provider
+ * config written outside that one function, and refuses it gaining a second caller.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import type { ResolvedCodingInference } from './account-service';
+
+export interface HarnessRuntimeLaunch {
+  program: string;
+  arguments: string[];
+  env: Record<string, string>;
+}
+
+/** What Supercode's own inventory says about a harness the person would run on their
+ * own login. `repair` is Supercode's registry text — the login or install command for
+ * that exact harness — and is quoted verbatim rather than restated here. */
+export interface HarnessReadiness {
+  id: string;
+  label: string;
+  installed: boolean;
+  auth: 'ready' | 'configured' | 'required' | 'unknown';
+  reason: string | null;
+  repair: string | null;
+}
+
+interface RuntimeBackendParams {
+  harness?: unknown;
+  launch?: unknown;
+  [key: string]: unknown;
+}
+
+/** The opt-in sentence every refusal ends with: the other way out is the account panel. */
+const OPT_IN_HINT =
+  'or choose managed inference for this harness in the account panel (Account → Generation routing → Preferred route).';
+
+function toml(value: string): string {
+  return JSON.stringify(value);
+}
+
+function openCodeModel(model: string): string {
+  return `openrouter/${model}`;
+}
+
+/**
+ * THE OPT-IN, AND THE ONLY PLACE IN THE ESTATE THAT MAY WRITE A PROVIDER CREDENTIAL OR
+ * PROVIDER CONFIG INTO A HARNESS LAUNCH. Everything the table needs — the process token
+ * name, the Pi extension it materializes — lives inside this function so the guard's
+ * span is exactly this function and nothing leaks to module scope.
+ *
+ * Reached only by a person who chose managed or BYOK coding inference for themselves
+ * because they have no subscription for this harness. Returns `undefined` for a harness
+ * whose CLI takes no provider configuration at all — Grok is the measured case
+ * (`grok --help`, 1.0.40: `login`/`logout` subcommands and `--model`, but no provider,
+ * base-URL or API-root option; Supercode's own `runtime_launch`, `HarnessId::GROK` in
+ * `crates/harness/src/harness_service.rs`, starts it as `grok … agent … stdio` with only
+ * `GROK_AGENT_DASHBOARD=0` in its env) — so Grok is device-login only and the caller
+ * refuses the opt-in for it by name.
+ */
+export async function managedInferenceLaunch(
+  harness: string,
+  inference: ResolvedCodingInference,
+  piExtensionPath: string,
+): Promise<HarnessRuntimeLaunch | undefined> {
+  const PROCESS_TOKEN = 'VGAI_OPENROUTER_TOKEN';
+  const commonEnv = {
+    [PROCESS_TOKEN]: inference.apiKey,
+    OPENROUTER_API_KEY: inference.apiKey,
+  };
+  if (harness === 'codex') {
+    const provider = 'vgai-openrouter';
+    return {
+      program: 'codex',
+      arguments: [
+        '--dangerously-bypass-approvals-and-sandbox',
+        '--dangerously-bypass-hook-trust',
+        '-c',
+        `model_provider=${toml(provider)}`,
+        '-c',
+        `model=${toml(inference.model)}`,
+        '-c',
+        `model_providers.${provider}.name=${toml('OpenRouter via Volter Editor')}`,
+        '-c',
+        `model_providers.${provider}.base_url=${toml(inference.baseUrl)}`,
+        '-c',
+        `model_providers.${provider}.env_key=${toml(PROCESS_TOKEN)}`,
+        '-c',
+        `model_providers.${provider}.wire_api=${toml('responses')}`,
+        'app-server',
+      ],
+      env: commonEnv,
+    };
+  }
+  if (harness === 'claude-code') {
+    return {
+      program: 'claude',
+      arguments: [
+        '--dangerously-skip-permissions',
+        '--model',
+        inference.model,
+        '--print',
+        '--input-format',
+        'stream-json',
+        '--output-format',
+        'stream-json',
+        '--verbose',
+      ],
+      env: {
+        ...commonEnv,
+        ANTHROPIC_BASE_URL: inference.baseUrl.replace(/\/v1$/, ''),
+        ANTHROPIC_AUTH_TOKEN: inference.apiKey,
+        ANTHROPIC_API_KEY: '',
+      },
+    };
+  }
+  if (harness === 'opencode') {
+    return {
+      program: 'opencode',
+      arguments: ['--model', openCodeModel(inference.model), 'serve'],
+      env: {
+        ...commonEnv,
+        OPENCODE_CONFIG_CONTENT: JSON.stringify({
+          provider: {
+            openrouter: {
+              options: {
+                apiKey: `{env:${PROCESS_TOKEN}}`,
+                baseURL: inference.baseUrl,
+              },
+              models: { [inference.model]: {} },
+            },
+          },
+        }),
+      },
+    };
+  }
+  if (harness === 'pi') {
+    const managed = inference.route === 'managed';
+    if (managed) {
+      await mkdir(dirname(piExtensionPath), { recursive: true, mode: 0o700 });
+      await writeFile(
+        piExtensionPath,
+        `export default function vgaiOpenRouter(pi) {
+  const baseUrl = process.env.VGAI_OPENROUTER_BASE_URL;
+  if (!baseUrl) throw new Error('VGAI_OPENROUTER_BASE_URL is required.');
+  pi.registerProvider('openrouter', { baseUrl, apiKey: '$OPENROUTER_API_KEY' });
+}\n`,
+        { encoding: 'utf8', mode: 0o600 },
+      );
+    }
+    return {
+      program: 'pi',
+      arguments: [
+        '--approve',
+        '--provider',
+        'openrouter',
+        '--model',
+        inference.model,
+        ...(managed ? ['--extension', piExtensionPath] : []),
+        '--mode',
+        'rpc',
+      ],
+      env: {
+        ...commonEnv,
+        VGAI_OPENROUTER_BASE_URL: inference.baseUrl,
+      },
+    };
+  }
+  return undefined;
+}
+
+/**
+ * The sentence a person sees instead of a silently metered harness. `null` means start
+ * it on the login they already did.
+ *
+ * `'required'` is the only auth state that means NOT SIGNED IN: Supercode sets it when
+ * it either found no native credential or watched the handshake fail with an auth error.
+ * `'unknown'` is Supercode explicitly declining to give a verdict — measured 2026-09-21,
+ * OpenCode reads `unknown` passively and `ready` under a handshake — so it is never a
+ * refusal here; the caller escalates the probe first, and a harness that still cannot be
+ * classified starts and reports its own error rather than being convicted on silence.
+ */
+export function harnessReadinessRefusal(readiness: HarnessReadiness): string | null {
+  if (!readiness.installed) {
+    const repair = readiness.repair ?? `Install ${readiness.label} and put its command on PATH`;
+    return `${readiness.label} is not installed on this machine, so there is nothing to sign in to. ${repair} — ${OPT_IN_HINT}`;
+  }
+  if (readiness.auth !== 'required') return null;
+  const repair =
+    readiness.repair ?? `Run \`supercode harness login ${readiness.id}\` and complete sign-in`;
+  return `${readiness.label} is not signed in on this machine, and Volter Editor never starts a harness on an account credential. ${repair} — ${OPT_IN_HINT}`;
+}
+
+/**
+ * The launch seam. By default it hands Supercode the backend params UNCHANGED so the
+ * stock CLI starts on the login the person already did, after asking Supercode whether
+ * that harness is ready; only an explicit `preferredRoute` of `'managed'` or `'byok'`
+ * reaches `managedInferenceLaunch`.
+ */
+export async function withCodingInference(
+  params: unknown,
+  resolveInference: () => Promise<ResolvedCodingInference | null>,
+  piExtensionPath: string,
+  readHarnessReadiness: (harness: string) => Promise<HarnessReadiness | null>,
+): Promise<unknown> {
+  if (!params || typeof params !== 'object' || Array.isArray(params)) return params;
+  const backend = params as RuntimeBackendParams;
+  if (backend.launch !== undefined || typeof backend.harness !== 'string') return params;
+  const harness = backend.harness;
+  const inference = await resolveInference();
+  const preferredRoute = inference?.preferredRoute ?? 'auto';
+  if (preferredRoute !== 'managed' && preferredRoute !== 'byok') {
+    const readiness = await readHarnessReadiness(harness);
+    const refusal = readiness ? harnessReadinessRefusal(readiness) : null;
+    if (refusal) throw new Error(refusal);
+    return params;
+  }
+  if (!inference) return params;
+  const launch = await managedInferenceLaunch(harness, inference, piExtensionPath);
+  if (!launch) {
+    throw new Error(
+      `${harness} takes no provider configuration — it runs on its own device login only. Sign in with \`supercode harness login ${harness}\`, or pick a harness managed inference can configure (Codex, Claude Code, OpenCode, Pi).`,
+    );
+  }
+  return { ...backend, launch };
+}

package/server/collaboration-account-client.ts

@@ -0,0 +1,202 @@
+import type { CollaborationAccountSession } from './account-service';
+import {
+  type ShareAccountProjection,
+  type ShareGrantRedemption,
+  ShareGrantServiceError,
+} from './share-session-gateway';
+
+function accountOrganizations(
+  value: unknown,
+): NonNullable<ShareAccountProjection['organizations']> {
+  if (!Array.isArray(value) || value.length > 100) {
+    throw new Error('Volter Editor collaboration grant returned invalid organization membership.');
+  }
+  return value.map((candidate) => {
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+      throw new Error('Volter Editor collaboration grant returned invalid organization membership.');
+    }
+    const organization = candidate as Record<string, unknown>;
+    const domains = organization['domains'];
+    if (
+      typeof organization['id'] !== 'string' ||
+      typeof organization['name'] !== 'string' ||
+      typeof organization['role'] !== 'string' ||
+      !Array.isArray(domains) ||
+      domains.length > 50
+    ) {
+      throw new Error('Volter Editor collaboration grant returned invalid organization membership.');
+    }
+    return {
+      id: organization['id'],
+      name: organization['name'],
+      ...(typeof organization['slug'] === 'string' ? { slug: organization['slug'] } : {}),
+      role: organization['role'],
+      domains: domains.map((domainValue) => {
+        if (!domainValue || typeof domainValue !== 'object' || Array.isArray(domainValue)) {
+          throw new Error('Volter Editor collaboration grant returned an invalid organization domain.');
+        }
+        const domain = domainValue as Record<string, unknown>;
+        const enrollmentMode = domain['enrollmentMode'];
+        if (
+          typeof domain['name'] !== 'string' ||
+          typeof domain['verified'] !== 'boolean' ||
+          ![
+            'manual_invitation',
+            'automatic_invitation',
+            'automatic_suggestion',
+            'enterprise_sso',
+          ].includes(String(enrollmentMode))
+        ) {
+          throw new Error('Volter Editor collaboration grant returned an invalid organization domain.');
+        }
+        return {
+          name: domain['name'],
+          verified: domain['verified'],
+          enrollmentMode: enrollmentMode as NonNullable<
+            ShareAccountProjection['organizations']
+          >[number]['domains'][number]['enrollmentMode'],
+        };
+      }),
+    };
+  });
+}
+
+export async function createCollaborationAccountHandoff(
+  account: CollaborationAccountSession,
+  binding: { callbackUrl: string; sessionId: string; invitationId: string },
+): Promise<{ authorizationUrl: string; deliveryAuthorization: string; expiresAt: number }> {
+  const response = await fetch(`${account.authUrl}/collaboration/handoff`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${account.accessToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(binding),
+  });
+  const body = (await response.json().catch(() => undefined)) as
+    | {
+        authorizationUrl?: unknown;
+        deliveryAuthorization?: unknown;
+        expiresAt?: unknown;
+        error?: unknown;
+      }
+    | undefined;
+  if (
+    !response.ok ||
+    typeof body?.authorizationUrl !== 'string' ||
+    typeof body.deliveryAuthorization !== 'string' ||
+    typeof body.expiresAt !== 'number'
+  ) {
+    throw new Error(
+      typeof body?.error === 'string'
+        ? body.error
+        : `Volter Editor collaboration authorization failed (${response.status}).`,
+    );
+  }
+  return {
+    authorizationUrl: body.authorizationUrl,
+    deliveryAuthorization: body.deliveryAuthorization,
+    expiresAt: body.expiresAt,
+  };
+}
+
+export async function deliverCollaborationInvitation(
+  account: CollaborationAccountSession,
+  input: {
+    emailAddress: string;
+    redirectUrl: string;
+    callbackUrl: string;
+    sessionId: string;
+    invitationId: string;
+    deliveryAuthorization: string;
+    expiresAt: number;
+  },
+): Promise<{ id: string; status: string; emailAddress: string }> {
+  const response = await fetch(`${account.authUrl}/collaboration/invitations`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${account.accessToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(input),
+  });
+  const body = (await response.json().catch(() => undefined)) as
+    | { id?: unknown; status?: unknown; emailAddress?: unknown; error?: unknown }
+    | undefined;
+  if (
+    !response.ok ||
+    typeof body?.id !== 'string' ||
+    typeof body.status !== 'string' ||
+    typeof body.emailAddress !== 'string'
+  ) {
+    throw new Error(
+      typeof body?.error === 'string'
+        ? body.error
+        : `Volter Editor collaboration invitation delivery failed (${response.status}).`,
+    );
+  }
+  return { id: body.id, status: body.status, emailAddress: body.emailAddress };
+}
+
+export async function redeemCollaborationAccountGrant(
+  authUrl: string,
+  binding: { grant: string; sessionId: string; invitationId: string },
+): Promise<ShareGrantRedemption> {
+  // The gateway may try several live invitations against one grant, so
+  // "this invitation does not own that grant" (4xx) has to stay separable from
+  // "the account service never answered" — the second must not be reported as
+  // a rejected grant to the person waiting on the callback page.
+  let response: Response;
+  try {
+    response = await fetch(`${authUrl.replace(/\/$/, '')}/collaboration/redeem`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(binding),
+    });
+  } catch (error) {
+    throw new ShareGrantServiceError(
+      `Volter Editor collaboration grant redemption could not reach the account service: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  if (response.status >= 500) {
+    throw new ShareGrantServiceError(
+      `Volter Editor collaboration grant redemption failed (${response.status}).`,
+    );
+  }
+  const body = (await response.json().catch(() => undefined)) as
+    | {
+        jti?: unknown;
+        participant?: {
+          id?: unknown;
+          email?: unknown;
+          name?: unknown;
+          organizations?: unknown;
+        };
+        error?: unknown;
+      }
+    | undefined;
+  if (
+    !response.ok ||
+    typeof body?.jti !== 'string' ||
+    typeof body.participant?.id !== 'string' ||
+    typeof body.participant.email !== 'string' ||
+    (body.participant.name !== undefined && typeof body.participant.name !== 'string') ||
+    !Array.isArray(body.participant.organizations)
+  )
+    throw new Error(
+      typeof body?.error === 'string'
+        ? body.error
+        : `Volter Editor collaboration grant redemption failed (${response.status}).`,
+    );
+  return {
+    jti: body.jti,
+    participant: {
+      id: body.participant.id,
+      email: body.participant.email,
+      ...(body.participant.name ? { name: body.participant.name } : {}),
+      organizations: accountOrganizations(body.participant.organizations),
+    },
+  };
+}

package/server/collaboration-attribution.ts

@@ -0,0 +1,122 @@
+/**
+ * WHO a change is attributed to, and what a participant is allowed to be.
+ *
+ * The agent-author lease is the load-bearing piece: a filesystem write made
+ * while an agent turn is running is that agent's, and a turn that has ended
+ * keeps a grace window so the write that lands a beat after the turn does not
+ * get filed as the human's. `running` closes on the observed turn and stays
+ * closed, so a later idle snapshot cannot re-open it.
+ */
+
+import type { CollaborationRole } from '@volter/editor-sdk/session/collaboration-types';
+import type { CollaborationSession } from './collaboration-session';
+import type { ShareHost } from './share-host';
+import { isShareRole } from './share-session-gateway';
+
+/**
+ * How long an agent's authorship survives its turn. Long enough to cover the
+ * write that lands a beat after the turn ends; short enough that the next
+ * human edit is not filed as the agent's.
+ */
+export const AGENT_AUTHOR_LEASE_MS = 60_000;
+
+export interface AgentAuthorLease {
+  participantId: string;
+  until: number;
+  /** Open on an observed running turn; false once the turn's grace window is
+   * all that is left, so a later idle snapshot cannot re-close it. */
+  running: boolean;
+}
+
+/** The lease a freshly-observed running turn opens. */
+export function agentAuthorLease(
+  participantId: string,
+  now: number = Date.now(),
+): AgentAuthorLease {
+  return { participantId, until: now + AGENT_AUTHOR_LEASE_MS, running: true };
+}
+
+/** Who a host-side filesystem write is credited to. `'host'` is the floor: an
+ * expired lease is indistinguishable from no agent having been here at all. */
+export function filesystemMutationAuthor(
+  lease: Pick<AgentAuthorLease, 'participantId' | 'until'> | null,
+  now: number = Date.now(),
+): string {
+  return lease && lease.until >= now ? lease.participantId : 'host';
+}
+
+/**
+ * The role a LOOPBACK page joins (or rejoins) the room with.
+ *
+ * A remote participant never reaches this: its invitation role is a
+ * connection-scoped ceiling supplied by the gateway. A loopback page is the
+ * editor's owner — it already holds the checkout on disk — which is why it, and
+ * only it, is the recovery for a room that has lost its last maintainer. That
+ * room is otherwise unmanageable forever: handing 'maintain' back requires
+ * 'maintain', and the last-maintainer guard only refuses DEMOTION, not the sole
+ * maintainer closing their tab.
+ */
+export function localCollaborationRole(
+  hasMaintainer: boolean,
+  recalledRole: CollaborationRole | null,
+): CollaborationRole {
+  if (!hasMaintainer) return 'maintainer';
+  return recalledRole ?? 'editor';
+}
+
+/**
+ * THE role write for a participant who reached this editor through the share
+ * gateway — used by `/__editor/share-control/participants/:id/role` and by
+ * `/__editor/collaboration/role` alike.
+ *
+ * A gateway participant has exactly one durable role, and the gateway holds
+ * it: `shareRoleAllows` gates every proxied request on the gateway's copy, and
+ * the gateway's assigned-role map is what a re-redemption restores. The
+ * session's copy is a projection for the UI — writing only the session moves
+ * the badge while the tunnel keeps authorizing the old capabilities, and the
+ * participant's next ephemeral re-join puts the old badge back.
+ *
+ * Order matters: the actor's authority is checked BEFORE the gateway is
+ * touched, so an unauthorized caller cannot demote anyone by having the
+ * session write fail afterwards.
+ *
+ * Everything that can refuse the change is therefore checked before EITHER
+ * store moves. Past that point the gateway's write is the outcome, and the
+ * session's projection can still fall behind it — most easily through the
+ * session's own ephemeral ceiling, which is a snapshot of the gateway role the
+ * participant last CONNECTED with, not of the invitation. Reporting that as a
+ * failure would tell the caller nothing happened about a change that did
+ * happen, so it returns a warning instead: the projection re-derives from the
+ * gateway on the participant's next connection.
+ */
+export function setGatewayParticipantRole(input: {
+  shareHost: Pick<ShareHost, 'setParticipantRole'>;
+  collaboration: CollaborationSession | null;
+  /** The participant performing the change, or null when the caller is the
+   * local owner acting through private session control (no session actor). */
+  actorId: string | null;
+  participantId: string;
+  role: CollaborationRole;
+}): { warning: string | null } {
+  const { shareHost, collaboration, actorId, participantId, role } = input;
+  if (actorId !== null && collaboration && !collaboration.allows(actorId, 'maintain')) {
+    throw new Error(`${actorId} does not have 'maintain' permission.`);
+  }
+  if (!isShareRole(role)) {
+    throw new Error('The requested role exceeds this participant invitation ceiling.');
+  }
+  shareHost.setParticipantRole(participantId, role);
+  // A gateway participant that redeemed but never opened the editor has no
+  // session record to mirror into; the gateway's own role still moved.
+  if (actorId === null || !collaboration?.allows(participantId, 'view')) return { warning: null };
+  try {
+    collaboration.setRole(actorId, participantId, role);
+  } catch (error) {
+    return {
+      warning: `The share role is now ${role}, but this editor session still shows ${
+        collaboration.roleFor(participantId) ?? 'no role'
+      } until the participant reconnects: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  return { warning: null };
+}