@ours.network/fleet 1.2.0-nightly.43 → 1.2.0-nightly.45

package/dist/managed-cli.d.ts

@@ -0,0 +1,253 @@
+import { type FleetConfig, type ManagedCliWorkflowId, type ResolvedRole } from './config.js';
+import type { SessionPrep } from './harness/types.js';
+/** Capability-gated by the installer; see src/capabilities.ts. */
+export declare const MANAGED_CONFIGURATION_FLAG = "--managed-configuration";
+/** What the last launch of a role actually prepared. Lives in the role's state dir. */
+export declare const MANAGED_CLI_RECORD = ".managed-cli.json";
+/** Quoted path tokens were refused by Codex 0.159.0 (#231) and granted by 0.160.0. */
+export declare const CODEX_QUOTED_PATH_MINIMUM = "0.160.0";
+export interface ManagedCliForm {
+    /** Argv tokens after the pin, matched exactly. */
+    tokens: readonly string[];
+    /** `lifecycle` forms create, change or retire tasks, rooms and agents. */
+    effect: 'help' | 'read' | 'lifecycle';
+    /** Whether the command itself takes -c/--configuration, where the pin is injected. */
+    configuration: boolean;
+}
+export interface ManagedCliWorkflow {
+    description: string;
+    forms: readonly ManagedCliForm[];
+    /** Named so nobody reads their absence as an oversight. */
+    excluded: readonly string[];
+}
+export declare const MANAGED_CLI_WORKFLOWS: Readonly<Record<ManagedCliWorkflowId, ManagedCliWorkflow>>;
+export type ManagedEntry = {
+    kind: 'none';
+} | {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'pinned';
+    configuration: string;
+    form: ManagedCliForm;
+    argv: string[];
+};
+/**
+ * Recognise the pinned entry form in `argv` (process.argv.slice(2)) and return
+ * the ordinary argv Commander should parse.
+ *
+ * The pin must be the first argument: that is the only position a native prefix
+ * rule can fix. For a command that takes `--configuration`, the pinned file is
+ * injected directly after the command tokens; a later, different value is
+ * refused by `assertPinnedConfiguration` on the PARSED option, so `-c`,
+ * `-cFILE`, `--configuration=FILE` and repeats need no token heuristics here.
+ */
+export declare function parseManagedEntry(argv: readonly string[]): ManagedEntry;
+/** Refuse a parsed `--configuration` that is not the pinned file. Throws a plain Error. */
+export declare function assertPinnedConfiguration(pinned: string, parsed: unknown): void;
+export interface ManagedCliPaths {
+    node: string;
+    cli: string;
+    configuration: string;
+}
+/** The exact tokens a rule fixes: this process's node, this installation's CLI, this configuration. */
+export declare function managedCliPaths(configPath?: string, overrides?: Partial<ManagedCliPaths>): ManagedCliPaths;
+/** The canonical shell spelling of one path token, or undefined when none is qualified. */
+export declare function shellSpelling(token: string): string | undefined;
+export declare const needsQuoting: (paths: ManagedCliPaths) => boolean;
+/** The argv prefix every prepared invocation starts with. */
+export declare function managedCliPrefix(paths: ManagedCliPaths): string[];
+/** The same prefix as the agent must type it. Undefined when a path cannot be spelled. */
+export declare function managedCliCommandPrefix(paths: ManagedCliPaths): string | undefined;
+/** Codex execution rules: one `prefix_rule` per form. JSON strings are valid Starlark strings. */
+export declare function renderCodexRules(paths: ManagedCliPaths, workflows: readonly ManagedCliWorkflowId[]): string;
+export interface ClaudeManagedCliSettings {
+    permissions: {
+        allow: string[];
+    };
+    sandbox: {
+        excludedCommands: string[];
+    };
+}
+/**
+ * Claude needs BOTH halves: `permissions.allow` authorizes the Bash call and
+ * `sandbox.excludedCommands` places it outside the OS sandbox when one is
+ * enabled. Each form is listed bare and with ` *` because the wildcard form
+ * alone is not relied on to match an invocation without arguments.
+ */
+export declare function claudeManagedCliSettings(paths: ManagedCliPaths, workflows: readonly ManagedCliWorkflowId[]): ClaudeManagedCliSettings | undefined;
+/**
+ * Merge the fragment into Fleet's own per-role settings overlay. Entries from a
+ * previous launch are dropped first, so a moved node, CLI or configuration
+ * leaves nothing stale behind. `sandbox.enabled` is never written: whether
+ * Claude's OS sandbox is on stays the operator's setting.
+ */
+export declare function mergeClaudeOverlay(base: Record<string, unknown>, fragment: ClaudeManagedCliSettings | undefined): Record<string, unknown>;
+export type ManagedCliMechanism = 'codex-workspace-rules' | 'claude-session-settings';
+export interface ManagedCliAnalysis {
+    role: string;
+    harness: string;
+    session: string;
+    workflows: ManagedCliWorkflowId[];
+    state: 'not-declared' | 'not-required' | 'unsupported' | 'supported';
+    mechanism?: ManagedCliMechanism;
+    /** Why the state is not-required or unsupported. Actionable, one per line. */
+    reasons: string[];
+    /** What the prepared policy actually grants, for disclosure. */
+    scope: string[];
+    workspace: string;
+    paths: ManagedCliPaths;
+    /** The prefix the agent types; absent unless supported. */
+    commandPrefix?: string;
+}
+export interface ManagedCliDeps {
+    platform?: NodeJS.Platform;
+    paths?: Partial<ManagedCliPaths>;
+    /** Codex version for the quoted-path qualification; read from the role's Codex when omitted. */
+    codexVersion?: string;
+}
+export declare function roleWorkspace(role: ResolvedRole, temp?: boolean): string;
+/** Decide, without touching the filesystem, what Fleet prepares for one role. */
+export declare function analyzeManagedCli(role: ResolvedRole, configPath: string | undefined, options?: ManagedCliDeps & {
+    temp?: boolean;
+    workspace?: string;
+}): ManagedCliAnalysis;
+export declare function codexRulesPath(workspace: string, configuration: string): string;
+export type RulesAction = 'created' | 'updated' | 'unchanged' | 'removed' | 'conflict';
+export interface RulesResult {
+    path: string;
+    action: RulesAction;
+    detail?: string;
+}
+/** Write this workspace's rules file and record `holder` as needing it. */
+export declare function acquireCodexRules(workspace: string, paths: ManagedCliPaths, workflows: readonly ManagedCliWorkflowId[], holder: string): RulesResult;
+/**
+ * Drop `holder` from every rules file except `keep`. A file left without a
+ * holder is removed when Fleet still owns it; a file other agents hold is left
+ * exactly as it is. This is what a launch does when the role stopped declaring
+ * the workflow, lost support, or moved to another workspace or configuration.
+ */
+export declare function releaseCodexRules(holder: string, keep?: string): RulesResult[];
+/**
+ * Bring every registered rules file of `configuration` in line with `expected`
+ * (path → persistent holders). Temporary holders stay while their state dir
+ * exists. A file nobody holds is removed if — and only if — Fleet still owns
+ * it; a file whose configuration no longer exists is obsolete and goes too.
+ */
+export declare function reconcileCodexRules(configuration: string, expected: ReadonlyMap<string, readonly string[]>, write: boolean): RulesResult[];
+/** Static comparison of the rules file with what this installation would generate. */
+export declare function inspectCodexRules(workspace: string, paths: ManagedCliPaths, workflows: readonly ManagedCliWorkflowId[]): {
+    path: string;
+    state: 'prepared' | 'missing' | 'stale' | 'conflict';
+    detail: string;
+};
+/** Whether Codex treats the workspace as trusted, which is what loads project rules. */
+export declare function codexWorkspaceTrust(workspace: string, env?: NodeJS.ProcessEnv): {
+    state: 'trusted' | 'untrusted' | 'unknown';
+    source: string;
+};
+export interface ClaudeSettingsInspection {
+    /** `unknown` when no readable source states it; Claude's default is then off. */
+    sandbox: 'enabled' | 'disabled' | 'unknown';
+    sources: string[];
+    /** Bash deny rules, which take precedence over Fleet's allow entries. */
+    bashDeny: string[];
+    unreadable: string[];
+}
+export declare function inspectClaudeSettings(workspace: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): ClaudeSettingsInspection;
+export interface ManagedCliRecord {
+    version: 1;
+    state: ManagedCliAnalysis['state'] | 'conflict';
+    mechanism?: ManagedCliMechanism;
+    workflows: ManagedCliWorkflowId[];
+    paths: ManagedCliPaths;
+    workspace: string;
+    /** Hash of everything that decides the generated policy; equal digests mean the same policy. */
+    digest: string;
+    /** When a policy with this digest was first loaded into a launch. */
+    preparedAt: string;
+    artifact?: string;
+    reasons: string[];
+}
+export declare function managedCliDigest(analysis: ManagedCliAnalysis): string;
+export declare function readManagedCliRecord(stateDir: string): ManagedCliRecord | undefined;
+/**
+ * Prepare the native policy for one launch and return the session prep to use.
+ * Never throws: a role whose policy cannot be prepared still launches, exactly
+ * as sandboxed as it was, and the reason is logged and recorded.
+ */
+export declare function prepareManagedCliLaunch(role: ResolvedRole, options: {
+    stateDir: string;
+    runCwd: string;
+    configPath?: string;
+    temp?: boolean;
+    prep: SessionPrep;
+    log(line: string): void;
+    deps?: ManagedCliDeps;
+    now?(): Date;
+}): SessionPrep;
+export interface ManagedCliObservation {
+    /** Per form, the best completed pinned invocation recorded after the current policy was loaded. */
+    current: {
+        form: string;
+        effect: ManagedCliForm['effect'];
+        at: string;
+        class: string;
+    }[];
+    /** Pinned invocations that predate the current policy: history, not verification. */
+    historical: number;
+    /** Rows pinned to a configuration other than the one this policy was prepared for. */
+    foreign: number;
+    summary: string;
+}
+/** Read the role's audit ledger without mutating or recovering it. */
+export declare function observeManagedCli(stateDir: string, record: ManagedCliRecord | undefined): ManagedCliObservation;
+export interface ManagedCliRoleReport {
+    role: string;
+    harness: string;
+    session: string;
+    workflows: ManagedCliWorkflowId[];
+    /** Generated configuration compared with this installation. Static. */
+    setup: {
+        state: 'not-declared' | 'not-required' | 'unsupported' | 'prepared' | 'missing' | 'stale' | 'conflict' | 'generated-at-launch';
+        mechanism?: ManagedCliMechanism;
+        artifact?: string;
+        action?: RulesAction;
+        detail: string;
+    };
+    /** Whether the session that is (or was last) running loaded the current policy. */
+    session_policy: 'not-applicable' | 'never-launched' | 'current' | 'restart-required';
+    /** From the audit ledger. Never inferred from `setup`. */
+    observed: ManagedCliObservation;
+    commandPrefix?: string;
+    scope: string[];
+    warnings: string[];
+}
+export interface ManagedCliReport {
+    version: 1;
+    configuration: string;
+    node: string;
+    cli: string;
+    platform: {
+        os: NodeJS.Platform;
+        declared: boolean;
+    };
+    wrote: boolean;
+    roles: ManagedCliRoleReport[];
+    removed: RulesResult[];
+    disclosure: string[];
+}
+export declare function managedCliReport(cfg: Pick<FleetConfig, 'roles'>, configPath: string | undefined, options: ManagedCliDeps & {
+    write: boolean;
+    env?: NodeJS.ProcessEnv;
+}): ManagedCliReport;
+/**
+ * Add a workflow to an existing Agent file, and nothing else. Comments, key
+ * order and every other setting — permissions included — are preserved.
+ */
+export declare function enableManagedCli(configPath: string | undefined, agent: string, workflow: ManagedCliWorkflowId): {
+    file: string;
+    changed: boolean;
+};
+/** The briefing section for a role, or nothing when it declares no workflow. */
+export declare function managedCliBriefing(role: ResolvedRole, configPath: string | undefined, temp?: boolean): string[];