agent-embassy 2.0.1 → 3.1.0

package/dist/src/gateway/service-agent.d.ts

@@ -0,0 +1,187 @@
+export declare const SERVICE_AGENT_LABEL = "com.agent-embassy.broker";
+export type LaunchAgentPlistOptions = Readonly<{
+    label: string;
+    programArguments: readonly string[];
+    logPath: string;
+    /** Already-captured, already-validated agent environment (see captureAgentEnvironment). */
+    environment: Readonly<Record<string, string>>;
+}>;
+/**
+ * Render the launchd agent plist.
+ *
+ * `KeepAlive` is `{ Crashed: true }`, never plain `true`. Per launchd.plist(5)
+ * `Crashed` relaunches the job only when it died from a signal typically
+ * associated with a crash — SIGSEGV, SIGBUS, SIGILL, SIGABRT. Nothing else
+ * brings it back: not a clean exit, not a non-zero exit, not a plain `kill`
+ * (SIGTERM), and not one of the broker's deliberate boot refusals (an
+ * unsupported state schema, another instance already holding the lease).
+ * Under plain `KeepAlive` every one of those refusals would relaunch forever,
+ * throttled to once every 5 seconds, into one log file that nothing rotates.
+ * A refusal now exits once and stays down, where `embassy service status` and
+ * the log can explain it. ThrottleInterval still bounds a genuine crash loop.
+ *
+ * EnvironmentVariables carries exactly the captured configuration keys and
+ * nothing else — see captureAgentEnvironment for the rule. PATH is not
+ * needed (every child process this broker spawns — the codex standalone
+ * binary, /bin/ps, /usr/bin/lockf, /bin/cat — is invoked by an absolute path
+ * already; see codex-local-transport.ts, claude-peer.ts, and
+ * instance-lease.ts).
+ */
+export declare function renderLaunchAgentPlist(options: LaunchAgentPlistOptions): string;
+export type RunLaunchctlResult = Readonly<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export type RunLaunchctl = (args: readonly string[]) => RunLaunchctlResult | Promise<RunLaunchctlResult>;
+export type ServiceAgentDependencies = Readonly<{
+    homeDir: string;
+    runLaunchctl: RunLaunchctl;
+    env: NodeJS.ProcessEnv;
+    execPath: string;
+    cliPath: string;
+    uid: number;
+    /** Bounded waits for launchd to finish unloading; injected by tests. */
+    delay?: (milliseconds: number) => Promise<void>;
+    now?: () => number;
+    /**
+     * The host-lease probe. The default spawns /usr/bin/lockf through
+     * instance-lease.ts and so only answers on macOS; tests inject a fake.
+     */
+    probeHostLease?: ProbeHostLease;
+}>;
+export type ServiceAgentPaths = Readonly<{
+    launchAgentsDir: string;
+    logsDir: string;
+    plistPath: string;
+    logPath: string;
+}>;
+export declare function serviceAgentPaths(homeDir: string): ServiceAgentPaths;
+/**
+ * stderr only, trimmed, and capped — never launchctl's stdout. Everything the
+ * service path puts on the CLI's stderr goes through this, including the
+ * errno text of a filesystem failure the CLI itself renders.
+ */
+export declare function boundedServiceDetail(text: string): string;
+/**
+ * The environment the installed agent runs with. launchd agents inherit
+ * almost nothing, so Embassy's own configuration has to be copied into the
+ * plist: every `EMBASSY_*` variable (EMBASSY_STATE_DIR included) plus
+ * XDG_STATE_HOME, which decides the state root when EMBASSY_STATE_DIR is
+ * unset. These are configuration, not secrets — but nothing else is copied,
+ * so an inherited API key or token cannot reach the plist.
+ *
+ * Both state roots must be absolute here, before capture: a relative value
+ * resolves against the installing shell's working directory, and the agent
+ * would silently resolve it somewhere else.
+ */
+export declare function captureAgentEnvironment(env: NodeJS.ProcessEnv): Readonly<Record<string, string>>;
+/**
+ * Read the lease holder's pid under the same discipline instance-lease.ts
+ * applies in readPrivateFile: lstat first, regular file only, this user's
+ * own, size-bounded, opened O_NOFOLLOW and re-verified against the same
+ * inode. This value only decorates a refusal message, but it is read out of
+ * a file another process writes, so it gets the same care.
+ */
+/**
+ * Read a small private record this user owns, or nothing at all. Never
+ * throws, and never follows anything: the path is lstat'd, refused unless it
+ * is a regular file this uid owns within the byte bound, opened O_NOFOLLOW,
+ * and re-verified through the open handle by (dev, ino, uid, size) so the
+ * file that was checked is the file that was read. A uid of `undefined` — a
+ * platform with no `getuid` — skips only the ownership half.
+ *
+ * Both readers of a private record go through here: the host lease's pid
+ * below, and `readGatewayControllerPid` in cli.ts.
+ */
+export declare function readOwnedSmallFile(filePath: string, uid: number | undefined, maximumBytes: number): Promise<string | undefined>;
+/** The pid recorded in a JSON record, or nothing when it names none. */
+export declare function recordedPid(raw: string | undefined): number | undefined;
+/**
+ * What the host-wide lease says right now. `pid` is present only when a
+ * *live* holder was identified; `message` is the lease's own words for why it
+ * could not be taken.
+ */
+export type HostLeaseProbe = Readonly<{
+    held: false;
+}> | Readonly<{
+    held: true;
+    pid?: number;
+    message: string;
+}>;
+export type ProbeHostLease = (homeDir: string, uid: number) => Promise<HostLeaseProbe>;
+/**
+ * The production probe, and the reason this is an injected dependency at all.
+ * It reuses the exact detection the broker relies on for single-instance
+ * correctness — a non-blocking acquire of the host-wide advisory lease
+ * (acquireGatewayInstanceLease, unmodified), released immediately when nobody
+ * holds it. That helper spawns /usr/bin/lockf, which exists only on macOS, so
+ * on any other platform it reports contention that is really a missing
+ * binary. The product is macOS-only and that is correct in production, but it
+ * makes every install path untestable off darwin; tests inject a fake probe
+ * and one darwin-only test drives this default.
+ *
+ * `GATEWAY_INSTANCE_IN_USE` is not only contention: instance-lease.ts throws
+ * it for roughly ten conditions that have nothing to do with another broker
+ * (a symlinked path component, a non-empty unmarked lease root, a mode or
+ * owner drift). So its message is always carried out of here unchanged, and a
+ * pid is reported only when the recorded holder is genuinely alive — the lock
+ * record keeps the *last* holder, and a successful probe writes its own pid
+ * there, so an unchecked pid is routinely stale. Never tell someone to stop
+ * a dead process.
+ */
+export declare function defaultProbeHostLease(homeDir: string, uid: number): Promise<HostLeaseProbe>;
+export type ServiceAgentInstallResult = Readonly<{
+    label: string;
+    plistPath: string;
+    logPath: string;
+    /** Names only: the configuration keys copied into the plist at install time. */
+    capturedEnv: readonly string[];
+}>;
+/**
+ * Register the broker as this user's launchd agent. Re-running it over a
+ * prior install — including one that is loaded and running right now — is
+ * the supported way to change what the agent runs with.
+ */
+export declare function installServiceAgent(deps: ServiceAgentDependencies): Promise<ServiceAgentInstallResult>;
+export type ServiceAgentUninstallResult = Readonly<{
+    label: string;
+    plistPath: string;
+    logPath: string;
+}>;
+/**
+ * Boot the agent out, confirm that launchctl reports the label as *not
+ * found*, and only then unlink the plist. The confirmation must be that exact
+ * answer: treating any launchctl error (a missing binary, a gui domain that
+ * is not up, a timeout) as "gone" would unlink the plist while the agent is
+ * still loaded — invisible to `install`, unstoppable by `uninstall`. Logs are
+ * left in place.
+ */
+export declare function uninstallServiceAgent(deps: ServiceAgentDependencies): Promise<ServiceAgentUninstallResult>;
+export type ServiceAgentStatusState = "loaded" | "not loaded" | "unknown";
+export type ServiceAgentStatus = Readonly<{
+    label: string;
+    plistPath: string;
+    logPath: string;
+    plistExists: boolean;
+    state: ServiceAgentStatusState;
+    pid?: number;
+    launchdState?: string;
+    lastExitStatus?: number;
+    /** ProgramArguments[0]/[1] that are no longer on disk (a version manager moved node). */
+    programMissing?: readonly string[];
+    /** launchctl's stderr, trimmed and capped at 512 bytes; its stdout is never quoted. */
+    launchctlStderr?: string;
+    note: string;
+}>;
+/**
+ * Report what is actually knowable. A launchctl that cannot run, or output
+ * this version does not recognize, is `unknown` with the reason quoted — not
+ * "not loaded", and not "loaded" with blank fields. The plist's own
+ * ProgramArguments are checked against the filesystem too: a node binary
+ * under a version manager can be removed out from under an installed agent,
+ * which launchd otherwise reports only as a repeated spawn failure.
+ */
+export declare function serviceAgentStatus(deps: ServiceAgentDependencies): Promise<ServiceAgentStatus>;
+/** The one production launchctl call site; every other reference to it in this module is through this runner. */
+export declare function defaultRunLaunchctl(args: readonly string[]): Promise<RunLaunchctlResult>;