@naswerks/periscope 1.0.0

package/dist/bin/reconfigure.js

@@ -0,0 +1,195 @@
+import { isAbsolutePath, normalizePath } from '../core/paths.js';
+import { ok, refuse } from '../core/result.js';
+import { claudeTranscriptResolver, defaultAgentHome, transcriptsRootUnder, } from '../host/claude-transcripts.js';
+import { RESTART_KEYS, WIRE_CONFIGURABLE_KEYS, isWireConfigurableKey, readConfigFile, withConfigFallback, writeConfigEntries, } from '../host/config-file.js';
+import { hostConfigurationOf, workspaceCapabilitiesOf, workspacePostureProblem, workspacesFor, } from './workspaces.js';
+function setOrNull(value) {
+    return value === undefined || value === '' ? null : value;
+}
+function postureOf(merged) {
+    return {
+        workspaceRoot: setOrNull(merged['PERISCOPE_WORKSPACE_ROOT']),
+        repositoryRoot: setOrNull(merged['PERISCOPE_REPOSITORY_ROOT']),
+        branchScheme: setOrNull(merged['PERISCOPE_BRANCH_SCHEME']),
+        workspaceKey: setOrNull(merged['PERISCOPE_WORKSPACE_KEY']),
+        agentHome: setOrNull(merged['PERISCOPE_AGENT_HOME']),
+        controllerUrl: setOrNull(merged['PERISCOPE_CONTROLLER_URL']),
+        decisionUrl: setOrNull(merged['PERISCOPE_DECISION_URL']),
+    };
+}
+/**
+ * Why a control-plane address cannot be written, or null. The link is dialled as a WebSocket and
+ * the decision endpoint is POSTed to, so each key takes the schemes its act can use and nothing
+ * else: a value that fits the other key would fail at the first act after the restart it waits for.
+ */
+/**
+ * The first thing wrong with ONE value for ONE key, or null: the per-key half of `candidateProblem`,
+ * shared with `periscope config` and the daemon's start-up read so a value the wire would refuse is
+ * refused wherever it is typed. A key this screen does not know passes; the closed key set is
+ * checked by the writer.
+ */
+export function configValueProblem(key, value) {
+    switch (key) {
+        case 'PERISCOPE_CONTROLLER_URL':
+            return addressProblem(key, value, ['ws:', 'wss:']);
+        case 'PERISCOPE_DECISION_URL':
+            return addressProblem(key, value, ['http:', 'https:']);
+        case 'PERISCOPE_WORKSPACE_ROOT':
+        case 'PERISCOPE_REPOSITORY_ROOT':
+        case 'PERISCOPE_AGENT_HOME':
+            return isAbsolutePath(value) ? null : `${key} must be an absolute path — got '${value}'`;
+        case 'PERISCOPE_BRANCH_SCHEME':
+            return value.includes('{key}')
+                ? null
+                : `PERISCOPE_BRANCH_SCHEME '${value}' has no {key} placeholder — every workspace would render the same branch`;
+        default:
+            return null;
+    }
+}
+function addressProblem(key, value, schemes) {
+    if (value === null)
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return `${key} must be an absolute URL — got '${value}'`;
+    }
+    if (!schemes.includes(parsed.protocol)) {
+        return `${key} must use ${schemes.map((scheme) => scheme.slice(0, -1)).join(' or ')} — got '${value}'`;
+    }
+    return null;
+}
+function sameRoot(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return normalizePath(a).toLowerCase() === normalizePath(b).toLowerCase();
+}
+/** The wire-settable keys the environment sets: their file values are unreachable. */
+export function overriddenByEnvironment(raw) {
+    return WIRE_CONFIGURABLE_KEYS.filter((key) => {
+        const value = raw[key];
+        return value !== undefined && value !== '';
+    });
+}
+/**
+ * The first thing wrong with a candidate posture, or null. The same screen start-up runs
+ * (`workspacePostureProblem`) plus the rules the wire needs that start-up gets from the shell: a
+ * root must be absolute, and a scheme must render distinct branches (contain `{key}`).
+ */
+export function candidateProblem(posture) {
+    for (const [key, value] of [
+        ['PERISCOPE_WORKSPACE_ROOT', posture.workspaceRoot],
+        ['PERISCOPE_REPOSITORY_ROOT', posture.repositoryRoot],
+        ['PERISCOPE_AGENT_HOME', posture.agentHome],
+    ]) {
+        if (value !== null && !isAbsolutePath(value))
+            return `${key} must be an absolute path — got '${value}'`;
+    }
+    if (posture.branchScheme !== null && !posture.branchScheme.includes('{key}')) {
+        return `PERISCOPE_BRANCH_SCHEME '${posture.branchScheme}' has no {key} placeholder — every workspace would render the same branch`;
+    }
+    const controller = addressProblem('PERISCOPE_CONTROLLER_URL', posture.controllerUrl, ['ws:', 'wss:']);
+    if (controller !== null)
+        return controller;
+    const decision = addressProblem('PERISCOPE_DECISION_URL', posture.decisionUrl, ['http:', 'https:']);
+    if (decision !== null)
+        return decision;
+    return workspacePostureProblem({
+        workspaceRoot: posture.workspaceRoot,
+        repositoryRoot: posture.repositoryRoot,
+        branchScheme: posture.branchScheme,
+        workspaceKey: posture.workspaceKey,
+    });
+}
+/**
+ * Apply the entries: screen every key, screen the candidate posture as a whole, refuse a roots
+ * change while busy, write the file once, and rebuild what the host swaps in.
+ */
+export function reconfigureHost(raw, entries, hostBusy, live) {
+    const seen = new Set();
+    for (const entry of entries) {
+        if (!isWireConfigurableKey(entry.key)) {
+            return refuse('config-key-unknown', `'${entry.key}' is not a key this host takes over the wire — the settable keys are ${WIRE_CONFIGURABLE_KEYS.join(', ')}`);
+        }
+        if (seen.has(entry.key)) {
+            return refuse('config-value-invalid', `'${entry.key}' is named twice in one ask`);
+        }
+        seen.add(entry.key);
+    }
+    const file = readConfigFile(raw);
+    if (file.problem !== null) {
+        return refuse('config-write-failed', `${file.problem} — fix or remove it before writing`);
+    }
+    const before = postureOf(withConfigFallback(raw, file.values));
+    // The candidate: the file with the entries applied, under the environment. An empty value is the
+    // documented twin of unset everywhere this package reads, so it removes the key like null does.
+    const nextValues = { ...file.values };
+    const writes = [];
+    for (const entry of entries) {
+        const value = entry.value === null || entry.value === '' ? null : entry.value;
+        if (value === null)
+            delete nextValues[entry.key];
+        else
+            nextValues[entry.key] = value;
+        writes.push({ key: entry.key, value });
+    }
+    // A written address is screened on its own, before the merge: the environment may shadow it today,
+    // and a bad value would still be the one the next start reads once the shadow lifts.
+    for (const write of writes) {
+        if (write.value === null)
+            continue;
+        const problem = write.key === 'PERISCOPE_CONTROLLER_URL'
+            ? addressProblem(write.key, write.value, ['ws:', 'wss:'])
+            : write.key === 'PERISCOPE_DECISION_URL'
+                ? addressProblem(write.key, write.value, ['http:', 'https:'])
+                : null;
+        if (problem !== null)
+            return refuse('config-value-invalid', problem);
+    }
+    const merged = withConfigFallback(raw, nextValues);
+    const after = postureOf(merged);
+    const problem = candidateProblem(after);
+    if (problem !== null)
+        return refuse('config-value-invalid', problem);
+    const rootsChange = !sameRoot(before.workspaceRoot, after.workspaceRoot) ||
+        !sameRoot(before.repositoryRoot, after.repositoryRoot);
+    if (rootsChange && hostBusy) {
+        return refuse('config-host-busy', 'a workspace root cannot change while a session is live or opening on this host — close every session and ask again');
+    }
+    const written = writeConfigEntries(raw, writes);
+    if (written !== null)
+        return refuse('config-write-failed', written);
+    const workspaceConfig = {
+        workspaceRoot: after.workspaceRoot,
+        repositoryRoot: after.repositoryRoot,
+        branchScheme: after.branchScheme,
+    };
+    const agentHome = after.agentHome ?? defaultAgentHome(raw);
+    const transcriptsRoot = agentHome === null ? null : transcriptsRootUnder(agentHome);
+    // The addresses in effect are what the host dialled at start; absent a caller's word, the merged
+    // view before this ask is the closest thing to it. A key whose file value differs is pending.
+    const dialled = live ?? {
+        controllerUrl: before.controllerUrl,
+        decisionUrl: before.decisionUrl,
+    };
+    const pendingRestart = RESTART_KEYS.filter((key) => key === 'PERISCOPE_CONTROLLER_URL'
+        ? after.controllerUrl !== dialled.controllerUrl
+        : after.decisionUrl !== dialled.decisionUrl);
+    return ok({
+        workspaces: workspacesFor(workspaceConfig) ?? undefined,
+        transcriptsRoot: transcriptsRoot ?? undefined,
+        bulk: transcriptsRoot === null ? undefined : claudeTranscriptResolver(transcriptsRoot),
+        linkCapabilities: workspaceCapabilitiesOf(workspaceConfig),
+        configuration: hostConfigurationOf(workspaceConfig, {
+            transcriptsRoot,
+            controllerUrl: after.controllerUrl,
+            decisionUrl: after.decisionUrl,
+            agentHome,
+        }),
+        overriddenByEnvironment: overriddenByEnvironment(raw),
+        pendingRestart,
+    });
+}
+//# sourceMappingURL=reconfigure.js.map

package/dist/bin/serve.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `periscope serve`: dial the controller and serve sessions. The daemon every supervisor starts.
+ *
+ * Two views of the environment arrive, and the split is deliberate. Configuration (`readConfig`)
+ * comes from the merged view, where the config file fills absences. Credential material, the
+ * environment sessions are filtered from, and the home directory come from the raw view: nothing
+ * outside the closed config key set may arrive from a file, and the credential files are found by
+ * the same `PERISCOPE_CONFIG_DIR` that says where the config file itself is.
+ *
+ * Every process-level edge is a dependency: where lines go, how the exit code is latched, how the
+ * process is exited, how signals are subscribed. The link and the agent process are injectable for
+ * the same reason, so the whole start-up sequence runs in a test with no socket and no agent.
+ */
+import type { ControllerCredential } from '../control/credential.js';
+import type { LinkHandlers } from '../control/link.js';
+import type { HostEvent } from '../host/index.js';
+import type { HostLink } from '../host/host.js';
+import { PeriscopeHost } from '../host/index.js';
+import type { AgentProcess, AgentProcessRequest } from '../host/agent-process.js';
+import type { EscalationTransport } from '../gate/escalate.js';
+/**
+ * How long the fatal-credential path holds the event loop open before exiting explicitly.
+ *
+ * Long enough for the stdout trace and the stderr remedy to flush through their pipes, short enough
+ * that a supervisor sees the exit promptly. It is not a grace period for work in flight; the host
+ * is already stopped by the time this runs.
+ */
+export declare const FATAL_EXIT_FLUSH_MS = 50;
+/** The two environments the daemon reads. See the module header for which reads which. */
+export interface ServeViews {
+    /** The process environment as received. Credentials, the session base env and the home read it. */
+    readonly raw: NodeJS.ProcessEnv;
+    /**
+     * The environment with the config file filling absences, or the problem that made the file
+     * unusable. Checked after the root refusal, so a host that cannot run at all is told that first.
+     */
+    readonly merged: NodeJS.ProcessEnv | string;
+}
+/** The edges. Every one has a production default in `main.ts`; a test replaces them all. */
+export interface ServeDeps {
+    /** One stdout line, without its newline: the trace. */
+    readonly log: (line: string) => void;
+    /** One stderr line, without its newline: refusals and the fatal remedy. */
+    readonly stderr: (line: string) => void;
+    readonly setExitCode: (code: number) => void;
+    /** Ends the process now. Called only on the fatal-credential path, after the flush delay. */
+    readonly exit: (code: number) => void;
+    readonly onSignal: (signal: 'SIGTERM' | 'SIGINT', handler: () => void) => void;
+    /** The decision POST's transport. Defaults to global fetch. */
+    readonly transport?: EscalationTransport;
+    /** How the link is built. Defaults to the real `ControllerLink`. */
+    readonly link?: (handlers: LinkHandlers) => HostLink;
+    /** The effective uid, or null where the platform has none (win32). Defaults to the process's. */
+    readonly getuid?: (() => number) | null;
+    /** How an agent process is started. Defaults to the real one. */
+    readonly startProcess?: (request: AgentProcessRequest) => AgentProcess;
+}
+export type ServeOutcome = {
+    readonly ok: true;
+    readonly host: PeriscopeHost;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+/** One trace line: `<clock> [channel] message — detail`. */
+export type Logger = (channel: string, message: string, detail: string | null) => void;
+/** What `readCredential` decided: the credential (or none), and, when the paired branch chose, the
+ * host id the credential is bound to, which overrides the configured one at `link_hello`. */
+export interface CredentialPosture {
+    readonly credential: ControllerCredential | null;
+    readonly pairedHostId: string | null;
+}
+/**
+ * Which credential this host presents, or null when it presents none.
+ *
+ * The paired credential is preferred over the OIDC cache, and the preference is the point of
+ * pairing: an OIDC refresh token can expire after a period of inactivity, the paired credential has
+ * no clock. A machine that has run `periscope pair` dials on the paired credential even when a
+ * token cache also exists. A missing paired file falls through to the OIDC postures; a corrupt one
+ * is fatal rather than a fallback, because silently degrading to a maybe-dead refresh token would
+ * put the host back in exactly the ambiguous posture pairing exists to end.
+ *
+ * The OIDC three-way decision itself lives in `identity/config.ts` and is tested there; this is the
+ * wiring. A misconfiguration returns a string, which `runServe` treats as fatal: a host that was
+ * told to use identity and cannot must not come up looking healthy while authenticating as nobody.
+ *
+ * The `absent` posture returns null rather than a refusing credential, which is the whole
+ * difference between "no identity" and "no tool calls". `UnconfiguredCredential` refuses by name on
+ * every call, and `escalatingDecider` treats a refusing credential as an outage and does not send
+ * the request, so handing one to it would turn every escalation in every session into
+ * `permission-decision-unavailable`. That is the exact outcome `readConfig` above refuses to ship
+ * for the missing-URL case, in the same file, for the same stated reason: a host that comes up
+ * healthy, accepts sessions, and blocks every tool call reads to an operator as the agent being
+ * broken. Null means the option is omitted, which `EscalationOptions.credential` documents as the
+ * supported no-identity mode; the placeholder stays the exported shape for an embedder that wants a
+ * credential that says no out loud.
+ */
+export declare function readCredential(env: NodeJS.ProcessEnv, log: Logger): CredentialPosture | string;
+/** Start the daemon. Returns the running host, or the refusal already written to stderr. */
+export declare function runServe(views: ServeViews, deps: ServeDeps): ServeOutcome;
+/** Every named thing the host reports, as one line each. The only output this process produces. */
+export declare function report(event: HostEvent, log: Logger): void;
+//# sourceMappingURL=serve.d.ts.map