@a5c-ai/agent-runtime 5.0.1-staging.07d877d5a3d1 → 5.0.1-staging.40aef9d16aae

package/README.md

@@ -4,6 +4,52 @@ Agent runtime layer (L5) for the Babysitter monorepo.
 
 Provides daemon lifecycle, session management, resource management, and telemetry infrastructure.
 
+The runtime observability surface includes compatible daemon JSONL logging policy
+helpers, run-health latency percentiles, pure diagnostics renderers for health,
+metrics, config, and queue state, and optional telemetry trace/export helpers.
+Remote telemetry exporters are opt-in; local and no-op behavior remains the
+default.
+
+## Execution Policy
+
+Execution configs accept an optional `policy` field that describes environment,
+filesystem, network, resource, sandbox, Docker, SSH, and Kubernetes-compatible
+execution constraints.
+
+Secure defaults are intentionally conservative:
+
+- Local and background execution do not inherit `process.env` by default.
+  Pass explicit `env` values, use `policy.environment.allow` for selected
+  parent variables, or set `policy.environment.inheritParentEnv: true` as an
+  explicit legacy opt-in.
+- Local execution validates filesystem roots and fails fast when asked to
+  enforce network, namespace, chroot, seccomp, capability, CPU, memory, pids,
+  or open-file guarantees it cannot provide. Use Docker or Kubernetes for
+  enforceable isolation, or set `policy.sandbox.allowUnsupportedLocal: true`
+  only for trusted host-process execution.
+- Docker execution emits hardened defaults: read-only root filesystem, `ALL`
+  capabilities dropped, `no-new-privileges`, a non-root user, and `--network
+  none` unless a network is explicitly configured. Host network and writable
+  root filesystem require `policy.docker.insecureAllowPrivilegedOptions: true`.
+- SSH execution uses strict host-key checking by default. `StrictHostKeyChecking=no`
+  is emitted only when `policy.ssh.insecureSkipHostKeyChecking: true` is set.
+- Kubernetes manifests include policy environment, resources, and a restricted
+  container `securityContext` where structurally supported by the manifest
+  builder.
+- Background processes use the same environment and cwd policy semantics and
+  can cap retained stdout/stderr with `policy.resources.maxOutputBytes`.
+  Snapshots and completion events include retained and dropped byte counts so
+  truncation is explicit.
+- Background process lifecycle controls support opt-in process-group signaling
+  on POSIX, direct-child fallback, grace-period SIGKILL escalation, timeout
+  status, platform-gated pause/resume, dependency queueing, and lifecycle hook
+  diagnostics. These controls are separate from daemon start/stop and session
+  pause policy.
+
+The policy layer records OS resource intent through `ResourceManagerImpl` but
+does not claim direct kernel enforcement. Concrete executors translate supported
+limits into their own runtime arguments.
+
 ## Install
 
 ```bash

package/dist/background/state.d.ts

@@ -4,11 +4,17 @@ import { BackgroundProcessRegistry } from "../backgroundProcessRegistry";
  * that state.ts actually consumes.  Defined locally to avoid a circular
  * dependency between agent-runtime and agent-core.
  */
-interface BackgroundRegistryOwner {
+export interface BackgroundRegistryOwner {
     backgroundRegistry?: BackgroundProcessRegistry;
     maxBackgroundProcesses?: number;
+    /**
+     * Stable identifier for the owner.  When provided, the registry is stored
+     * in a string-keyed Map in addition to the WeakMap.  This prevents orphaning
+     * when the caller recreates the options object (new object identity) but
+     * logically refers to the same owner.
+     */
+    registryId?: string;
 }
 export declare function getBackgroundRegistry(options: BackgroundRegistryOwner): BackgroundProcessRegistry;
 export declare function disposeBackgroundRegistry(options: BackgroundRegistryOwner): void;
-export {};
 //# sourceMappingURL=state.d.ts.map

package/dist/background/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/background/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAEzE;;;;GAIG;AACH,UAAU,uBAAuB;IAC/B,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAID,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,uBAAuB,GAAG,yBAAyB,CAWjG;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAOhF"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/background/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAcD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,uBAAuB,GAAG,yBAAyB,CA8BjG;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAWhF"}

package/dist/background/state.js

@@ -3,15 +3,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getBackgroundRegistry = getBackgroundRegistry;
 exports.disposeBackgroundRegistry = disposeBackgroundRegistry;
 const backgroundProcessRegistry_1 = require("../backgroundProcessRegistry");
+/**
+ * Primary store — keyed by object identity (auto-collected when owner is GC'd).
+ */
 const scopedRegistries = new WeakMap();
+/**
+ * Secondary store — keyed by `registryId` string so that a new options object
+ * with the same registryId finds the existing registry instead of creating a
+ * new one (which would orphan any background processes tracked by the old one).
+ */
+const namedRegistries = new Map();
 function getBackgroundRegistry(options) {
     if (options.backgroundRegistry) {
         return options.backgroundRegistry;
     }
+    // Try the WeakMap first (cheapest path for stable object references).
     let registry = scopedRegistries.get(options);
-    if (!registry) {
-        registry = new backgroundProcessRegistry_1.BackgroundProcessRegistry({ maxConcurrent: options.maxBackgroundProcesses });
-        scopedRegistries.set(options, registry);
+    if (registry) {
+        return registry;
+    }
+    // Try the string-keyed secondary map when a registryId is provided.
+    if (options.registryId) {
+        registry = namedRegistries.get(options.registryId);
+        if (registry) {
+            // Re-attach to the WeakMap so subsequent lookups with this object are fast.
+            scopedRegistries.set(options, registry);
+            return registry;
+        }
+    }
+    // No existing registry found — create a new one.
+    registry = new backgroundProcessRegistry_1.BackgroundProcessRegistry({ maxConcurrent: options.maxBackgroundProcesses });
+    scopedRegistries.set(options, registry);
+    if (options.registryId) {
+        namedRegistries.set(options.registryId, registry);
     }
     return registry;
 }
@@ -22,4 +46,7 @@ function disposeBackgroundRegistry(options) {
     }
     registry.dispose();
     scopedRegistries.delete(options);
+    if (options.registryId) {
+        namedRegistries.delete(options.registryId);
+    }
 }

package/dist/backgroundProcessRegistry.d.ts

@@ -5,17 +5,44 @@
  * stdout/stderr, fires completion callbacks, and enforces a concurrency limit.
  */
 import * as childProcess from "node:child_process";
+import type { ExecutionPolicy } from "./execution";
 /** Snapshot of a tracked background process. */
+export type BackgroundTaskStatus = "queued" | "running" | "paused" | "completed" | "exited" | "cancelled" | "killed" | "timed_out" | "skipped" | "failed";
+export interface BackgroundStreamMetadata {
+    retainedBytes: number;
+    droppedBytes: number;
+    truncated: boolean;
+}
+export interface BackgroundHookError {
+    hook: keyof BackgroundLifecycleHooks;
+    message: string;
+}
+export interface BackgroundLifecycleHooks {
+    preSpawn?: (record: BackgroundTaskRecord) => void;
+    postSpawn?: (record: BackgroundTaskRecord) => void;
+    preDestroy?: (record: BackgroundTaskRecord) => void;
+    postDestroy?: (record: BackgroundTaskRecord) => void;
+    onTimeout?: (record: BackgroundTaskRecord) => void;
+}
 export interface BackgroundTaskRecord {
     backgroundTaskId: string;
     pid: number;
     command: string;
     description?: string;
     startedAt: string;
-    status: "running" | "completed" | "exited" | "cancelled" | "killed";
+    status: BackgroundTaskStatus;
     exitCode: number | null;
     stdout: string;
     stderr: string;
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
+    stdoutRetainedBytes?: number;
+    stderrRetainedBytes?: number;
+    stdoutDroppedBytes?: number;
+    stderrDroppedBytes?: number;
+    dependsOn?: string[];
+    dependencyFailure?: string;
+    hookErrors?: BackgroundHookError[];
     durationMs: number | null;
 }
 /** Payload delivered to `onComplete` callbacks. */
@@ -24,10 +51,19 @@ export interface BackgroundCompletionEvent {
     pid: number;
     command: string;
     description?: string;
-    status: "completed" | "exited";
+    status: BackgroundTaskStatus;
     exitCode: number;
     stdout: string;
     stderr: string;
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
+    stdoutRetainedBytes?: number;
+    stderrRetainedBytes?: number;
+    stdoutDroppedBytes?: number;
+    stderrDroppedBytes?: number;
+    dependsOn?: string[];
+    dependencyFailure?: string;
+    hookErrors?: BackgroundHookError[];
     durationMs: number;
 }
 /** Options for spawning a background process. */
@@ -35,22 +71,33 @@ export interface SpawnOptions {
     command: string;
     cwd: string;
     env?: Record<string, string>;
+    executionPolicy?: ExecutionPolicy;
     description?: string;
+    dependsOn?: string[];
+    hooks?: BackgroundLifecycleHooks;
+    hookTimeoutMs?: number;
+    terminationGraceMs?: number;
+    terminateProcessGroup?: boolean;
     onComplete?: (event: BackgroundCompletionEvent) => void;
 }
 export declare class BackgroundProcessRegistry {
     private readonly processes;
     private readonly maxConcurrent;
     private readonly spawnFn;
+    private readonly processKillFn;
+    private readonly platform;
     constructor(options?: {
         maxConcurrent?: number;
         spawnFn?: typeof childProcess.spawn;
+        processKillFn?: typeof process.kill;
+        platform?: NodeJS.Platform;
     });
     /**
      * Spawn a command in the background and begin tracking it.
      * Returns a snapshot of the initial record.
      */
     spawn(opts: SpawnOptions): BackgroundTaskRecord;
+    private startTrackedProcess;
     /** Get a snapshot of a tracked process by ID, or undefined. */
     get(backgroundTaskId: string): BackgroundTaskRecord | undefined;
     /** List snapshots of all tracked processes. */
@@ -61,6 +108,17 @@ export declare class BackgroundProcessRegistry {
     killAll(): void;
     /** Kill all processes and clear tracking state. */
     dispose(): void;
+    pause(backgroundTaskId: string): boolean;
+    resume(backgroundTaskId: string): boolean;
     private snapshot;
+    private completionEvent;
+    private terminate;
+    private canSignal;
+    private sendSignal;
+    private shouldSignalProcessGroup;
+    private isStillRunning;
+    private resolveDependents;
+    private resolveQueuedProcess;
+    private runHook;
 }
 //# sourceMappingURL=backgroundProcessRegistry.d.ts.map

package/dist/backgroundProcessRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backgroundProcessRegistry.d.ts","sourceRoot":"","sources":["../src/backgroundProcessRegistry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAC;AAOnD,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,mDAAmD;AACnD,MAAM,WAAW,yBAAyB;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,CAAC;CACzD;AA4BD,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,YAAY,CAAC,KAAK,CAAA;KAAE;IAKrF;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,oBAAoB;IAuF/C,+DAA+D;IAC/D,GAAG,CAAC,gBAAgB,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAM/D,+CAA+C;IAC/C,IAAI,IAAI,oBAAoB,EAAE;IAI9B,4EAA4E;IAC5E,MAAM,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO;IAczC,kCAAkC;IAClC,OAAO,IAAI,IAAI;IAcf,mDAAmD;IACnD,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,QAAQ;CAcjB"}
+{"version":3,"file":"backgroundProcessRegistry.d.ts","sourceRoot":"","sources":["../src/backgroundProcessRegistry.ts"],"names":[],"mappings":"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"}