@dbx-tools/appkit 0.9.70 → 0.9.71

package/package.json

@@ -20,7 +20,7 @@
   },
   "devDependencies": {
     "@databricks/appkit": "0.81.0",
-    "@dbx-tools/projen": "^0.9.70",
+    "@dbx-tools/projen": "^0.9.71",
     "@types/node": "^24.6.0",
     "typescript": "^5.9.3",
     "vitest": "3.2.4"
@@ -30,11 +30,11 @@
   },
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17.0",
-    "@dbx-tools/auth": "^0.9.70",
-    "@dbx-tools/core": "^0.9.70",
-    "@dbx-tools/lakebase": "^0.9.70",
-    "@dbx-tools/postgres": "^0.9.70",
-    "@dbx-tools/shared-core": "^0.9.70",
+    "@dbx-tools/auth": "^0.9.71",
+    "@dbx-tools/core": "^0.9.71",
+    "@dbx-tools/lakebase": "^0.9.71",
+    "@dbx-tools/postgres": "^0.9.71",
+    "@dbx-tools/shared-core": "^0.9.71",
     "zod": "4.3.6"
   },
   "main": "./lib/index.js",
@@ -115,7 +115,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.70",
+  "version": "0.9.71",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [

package/src/appkit.ts

@@ -103,8 +103,8 @@ export type CreateAppConfig<T extends AppKitPlugins = AppKitPlugins> = Omit<
   /**
    * One or many {@link Interceptor}s handed an {@link InterceptorContext} once
    * auto-configuration has computed the env. Each receives the resolved env, an
-   * AppKit-lifecycle hook, and `bindProcess` for concurrently-style supervision -
-   * see `./interceptor`. The tunnel is the primary consumer.
+   * AppKit lifecycle hook. See `./interceptor`. The tunnel is the primary
+   * consumer.
    */
   interceptor?: Interceptor | Interceptor[];
 };
@@ -293,7 +293,7 @@ function interceptorList(interceptor: CreateAppConfig["interceptor"]): Intercept
  * When {@link CreateAppConfig.interceptor}s are given, each is invoked with an
  * {@link InterceptorContext} AFTER auto-configuration computes the env and BEFORE
  * AppKit boots - so an interceptor can read the resolved connection, register
- * lifecycle handlers, and `bindProcess` a child. A hidden {@link lifecycleBridge}
+ * lifecycle handlers, and start auxiliary work. A hidden {@link lifecycleBridge}
  * plugin is injected so those `onLifecycle` handlers fire on the genuine AppKit
  * events; it has no exports, so the returned {@link PluginMap} is unchanged.
  *

package/src/child-process.ts

@@ -4,20 +4,44 @@
  * @module
  */
 import * as exec from "@dbx-tools/core/exec";
+import { asyncUtils } from "@dbx-tools/shared-core";
+
+const DEFAULT_HEALTH_CHECK_INTERVAL_MS = 200;
+const DEFAULT_HEALTH_CHECK_TIMEOUT_MS = 30_000;
+const DEFAULT_RUN_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
 
 /** Spawn arguments accepted by {@link AppKitChildProcess}. */
 export type AppKitSpawnArgs = exec.SpawnArgs<exec.ExecOptions>;
 
-/** Graceful and forced shutdown policy for an AppKit child process. */
-export interface AppKitChildProcessOptions {
-  /** Signal sent when shutdown starts. Defaults to `SIGTERM`. */
-  gracefulSignal?: NodeJS.Signals;
-  /** Time to wait after the graceful signal. Defaults to 7 seconds. */
-  gracefulTimeoutMs?: number;
-  /** Signal sent when graceful shutdown times out. Defaults to `SIGKILL`. */
-  forceSignal?: NodeJS.Signals;
-  /** Time to wait after the force signal. Defaults to 1 second. */
-  forceTimeoutMs?: number;
+/** Context passed to one child-process readiness probe. */
+export interface AppKitChildProcessHealthCheckContext {
+  /** Spawned process being checked. */
+  readonly process: exec.ChildProcessResult;
+  /** Aborts when shutdown begins or the readiness timeout expires. */
+  readonly signal: AbortSignal;
+  /** Zero-based readiness attempt. */
+  readonly attempt: number;
+}
+
+/** Return `true` when the spawned process is ready to serve callers. */
+export type AppKitChildProcessHealthCheck = (
+  context: AppKitChildProcessHealthCheckContext,
+) => boolean | PromiseLike<boolean>;
+
+/** Readiness and tree-shutdown policy for an AppKit child process. */
+export interface AppKitChildProcessOptions extends exec.KillOptions {
+  /** Optional readiness probe polled after the process is spawned. */
+  healthCheck?: AppKitChildProcessHealthCheck;
+  /** Delay between readiness probes. Defaults to 200 milliseconds. */
+  healthCheckIntervalMs?: number;
+  /** Maximum time allowed for readiness. Defaults to 30 seconds. */
+  healthCheckTimeoutMs?: number;
+}
+
+/** Foreground signal policy for {@link AppKitChildProcess.run}. */
+export interface AppKitChildProcessRunOptions {
+  /** Parent signals that trigger tree shutdown before being re-raised. */
+  signals?: readonly NodeJS.Signals[];
 }
 
 /**
@@ -25,26 +49,36 @@ export interface AppKitChildProcessOptions {
  *
  * The spawn arguments use {@link exec.ExecOptions}, including core exec's
  * stdin, output capture, line handlers, exit checking, and trim policy.
- * Shutdown is idempotent and escalates from the graceful signal to the force
- * signal when the child does not exit within the configured timeouts.
+ * When configured, {@link AppKitChildProcessOptions.healthCheck} is polled
+ * until ready before {@link start} resolves. Shutdown aborts any active probe
+ * and delegates process-tree termination to {@link exec.kill}.
  */
 export class AppKitChildProcess {
   readonly #spawnArgs: AppKitSpawnArgs;
-  readonly #options: Required<AppKitChildProcessOptions>;
-  readonly #detached: boolean;
+  readonly #killOptions: exec.KillOptions;
+  readonly #healthCheck?: AppKitChildProcessHealthCheck;
+  readonly #healthCheckIntervalMs: number;
+  readonly #healthCheckTimeoutMs: number;
 
   #child?: exec.ChildProcessResult;
+  #healthCheckController?: AbortController;
   #shutdownPromise?: Promise<void>;
 
   constructor(spawnArgs: AppKitSpawnArgs, options: AppKitChildProcessOptions = {}) {
     this.#spawnArgs = spawnArgs;
-    this.#options = {
-      gracefulSignal: options.gracefulSignal ?? "SIGTERM",
-      gracefulTimeoutMs: options.gracefulTimeoutMs ?? 7_000,
-      forceSignal: options.forceSignal ?? "SIGKILL",
-      forceTimeoutMs: options.forceTimeoutMs ?? 1_000,
-    };
-    this.#detached = spawnOptions(spawnArgs)?.detached === true;
+    const {
+      healthCheck,
+      healthCheckIntervalMs = DEFAULT_HEALTH_CHECK_INTERVAL_MS,
+      healthCheckTimeoutMs = DEFAULT_HEALTH_CHECK_TIMEOUT_MS,
+      ...killOptions
+    } = options;
+    this.#healthCheck = healthCheck;
+    this.#healthCheckIntervalMs = positiveMilliseconds(
+      healthCheckIntervalMs,
+      "healthCheckIntervalMs",
+    );
+    this.#healthCheckTimeoutMs = positiveMilliseconds(healthCheckTimeoutMs, "healthCheckTimeoutMs");
+    this.#killOptions = killOptions;
   }
 
   /** Current child handle, or `undefined` when no child is running. */
@@ -57,101 +91,148 @@ export class AppKitChildProcess {
     return this.#child !== undefined && !hasExited(this.#child);
   }
 
-  /** Start the configured child process. */
-  start(): exec.ChildProcessResult {
+  /** Spawn the child and resolve only after its optional readiness probe succeeds. */
+  start(): Promise<void> {
     if (this.running) throw new Error("Child process is already running");
     if (this.#shutdownPromise) {
       throw new Error("Child process is shutting down or has been shut down");
     }
 
     const child = exec.spawn(...this.#spawnArgs);
+    const controller = new AbortController();
     this.#child = child;
+    this.#healthCheckController = controller;
     void child.once("close", () => {
       if (this.#child === child) this.#child = undefined;
     });
-    return child;
+    return this.#completeStart(child, controller);
   }
 
-  /** Stop the child once, escalating when graceful shutdown times out. */
-  shutdown(): Promise<void> {
-    this.#shutdownPromise ??= this.#performShutdown();
+  /**
+   * Start, await, and shut down one foreground child while preserving parent
+   * termination signals.
+   */
+  async run(options: AppKitChildProcessRunOptions = {}): Promise<exec.ExecResult> {
+    const signals = options.signals ?? DEFAULT_RUN_SIGNALS;
+    if (signals.includes("SIGKILL")) {
+      throw new Error("SIGKILL cannot be intercepted by a Node process");
+    }
+    const handlers = new Map<NodeJS.Signals, () => void>();
+    let stopping = false;
+    const removeHandlers = () => {
+      for (const [signal, handler] of handlers) process.off(signal, handler);
+    };
+    for (const signal of signals) {
+      const handler = () => {
+        if (stopping) return;
+        stopping = true;
+        removeHandlers();
+        void this.shutdown()
+          .finally(() => process.kill(process.pid, signal))
+          .catch(() => undefined);
+      };
+      handlers.set(signal, handler);
+      process.once(signal, handler);
+    }
+
+    try {
+      await this.start();
+      const child = this.#child;
+      if (!child) throw new Error("Child process exited after startup");
+      return await child;
+    } finally {
+      removeHandlers();
+      await this.shutdown();
+    }
+  }
+
+  /**
+   * Abort readiness and stop the process tree once.
+   *
+   * An explicit non-`SIGKILL` signal runs only the graceful polling phase.
+   * Explicit `SIGKILL` skips directly to forced polling. Omitting the signal
+   * uses the configured graceful and forced policy.
+   */
+  shutdown(signal?: NodeJS.Signals): Promise<void> {
+    this.#healthCheckController?.abort(
+      new DOMException("Child process shutdown requested", "AbortError"),
+    );
+    const killOptions: exec.KillOptions =
+      signal === undefined
+        ? this.#killOptions
+        : signal === "SIGKILL"
+          ? { ...this.#killOptions, gracefulSignal: false, forceSignal: signal }
+          : { ...this.#killOptions, gracefulSignal: signal, forceSignal: false };
+    this.#shutdownPromise ??= this.#performShutdown(killOptions);
     return this.#shutdownPromise;
   }
 
-  async #performShutdown(): Promise<void> {
-    const child = this.#child;
-    if (!child || hasExited(child)) {
-      this.#child = undefined;
-      return;
+  async #completeStart(child: exec.ChildProcessResult, controller: AbortController): Promise<void> {
+    try {
+      if (this.#healthCheck) {
+        await Promise.race([
+          this.#waitUntilHealthy(child, controller.signal),
+          child.then((result) => {
+            throw new Error(
+              `Child process ${child.pid ?? "<unknown>"} exited before becoming ready ` +
+                `(exit ${result.exitCode})`,
+            );
+          }),
+        ]);
+      }
+    } catch (error) {
+      try {
+        await this.shutdown();
+      } catch (shutdownError) {
+        throw new AggregateError(
+          [error, shutdownError],
+          `Child process ${child.pid ?? "<unknown>"} failed readiness and shutdown`,
+        );
+      }
+      throw error;
+    } finally {
+      if (this.#healthCheckController === controller) {
+        this.#healthCheckController = undefined;
+      }
     }
+  }
 
-    signalChild(child, this.#options.gracefulSignal, this.#detached);
-    if (await waitForExit(child, this.#options.gracefulTimeoutMs)) {
-      if (this.#child === child) this.#child = undefined;
-      return;
+  async #waitUntilHealthy(child: exec.ChildProcessResult, signal: AbortSignal): Promise<void> {
+    const healthCheck = this.#healthCheck;
+    if (!healthCheck) return;
+    for await (const healthy of asyncUtils.poll(
+      ({ attempt, signal: pollSignal }) =>
+        healthCheck({ process: child, signal: pollSignal, attempt }),
+      {
+        intervalMs: this.#healthCheckIntervalMs,
+        timeoutMs: this.#healthCheckTimeoutMs,
+        signal,
+        predicate: (healthy) => !healthy,
+      },
+    )) {
+      if (healthy) return;
     }
+  }
 
-    signalChild(child, this.#options.forceSignal, this.#detached);
-    if (!(await waitForExit(child, this.#options.forceTimeoutMs))) {
-      throw new Error(`Child process ${child.pid ?? "<unknown>"} did not terminate`);
+  async #performShutdown(options: exec.KillOptions): Promise<void> {
+    const child = this.#child;
+    if (!child) {
+      this.#child = undefined;
+      return;
     }
+
+    await exec.kill(child, options);
     if (this.#child === child) this.#child = undefined;
   }
 }
 
-function spawnOptions(args: AppKitSpawnArgs): exec.ExecOptions | undefined {
-  const value = args.at(-1);
-  return isExecOptions(value) ? value : undefined;
-}
-
-function isExecOptions(value: unknown): value is exec.ExecOptions {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 function hasExited(child: exec.ChildProcessResult): boolean {
   return child.exitCode !== null || child.signalCode !== null;
 }
 
-function signalChild(
-  child: exec.ChildProcessResult,
-  signal: NodeJS.Signals,
-  detached: boolean,
-): void {
-  if (detached && process.platform !== "win32" && child.pid) {
-    try {
-      process.kill(-child.pid, signal);
-      return;
-    } catch {
-      // Fall back to the direct child when the process group already exited.
-    }
+function positiveMilliseconds(value: number, name: string): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(`${name} must be a finite positive number`);
   }
-  child.kill(signal);
-}
-
-function waitForExit(child: exec.ChildProcessResult, timeoutMs: number): Promise<boolean> {
-  if (hasExited(child)) return Promise.resolve(true);
-
-  return new Promise((resolve) => {
-    let timer: NodeJS.Timeout | undefined;
-    let settled = false;
-
-    const finish = (exited: boolean) => {
-      if (settled) return;
-      settled = true;
-      if (timer) clearTimeout(timer);
-      void child.off("exit", onExit);
-      void child.off("error", onError);
-      resolve(exited);
-    };
-    const onExit = () => finish(true);
-    const onError = () => finish(true);
-
-    void child.once("exit", onExit);
-    void child.once("error", onError);
-    if (hasExited(child)) {
-      finish(true);
-      return;
-    }
-    timer = setTimeout(() => finish(false), timeoutMs);
-  });
+  return value;
 }

package/src/interceptor.ts

@@ -1,8 +1,7 @@
 /**
  * The `createApp` INTERCEPTOR context: an in-process handle an app hands to
  * add-ons (the tunnel, chiefly) so they can read the env auto-configuration
- * computed, hook AppKit's lifecycle, and supervise sibling child processes as one
- * unit - concurrently-style, where any death takes the whole set down.
+ * computed and hook AppKit's lifecycle.
  *
  * An interceptor is a plain function `(ctx) => void | Promise<void>` passed to
  * `appkit.createApp`'s `interceptor` option ("one or many"). `appkit.createApp`
@@ -20,7 +19,6 @@
  * @module
  */
 
-import type { ChildProcess } from "node:child_process";
 import { Plugin, toPlugin, type BasePluginConfig, type PluginManifest } from "@databricks/appkit";
 import { log } from "@dbx-tools/shared-core";
 import type { LakebaseConnection } from "./lakebase-resolver.ts";
@@ -60,14 +58,6 @@ export interface ResolvedAppEnv {
   readonly databricksHost?: string;
 }
 
-/**
- * A process {@link InterceptorContext.bindProcess} can supervise. A bare
- * `node:child_process` `ChildProcess` (e.g. portr) satisfies this, and so does
- * `@dbx-tools/core`'s `spawn()` result (a `ChildProcessResult` IS a
- * `ChildProcess`) - one code path handles both.
- */
-export type BindableProcess = Pick<ChildProcess, "pid" | "kill" | "killed" | "once">;
-
 /**
  * The handle passed to each interceptor.
  *
@@ -77,9 +67,8 @@ export type BindableProcess = Pick<ChildProcess, "pid" | "kill" | "killed" | "on
  * await appkit.createApp({
  *   plugins: [server()],
  *   interceptor: (ctx) => {
- *     const portr = spawnPortr(ctx.env.databricksHost);
- *     ctx.bindProcess(portr);            // app <-> portr live/die together
- *     ctx.onLifecycle("shutdown", () => portr.kill("SIGTERM"));
+ *     const auxiliary = startAuxiliary(ctx.env.databricksHost);
+ *     ctx.onLifecycle("shutdown", () => auxiliary.stop());
  *   },
  * });
  */
@@ -93,66 +82,11 @@ export interface InterceptorContext {
    * retroactively (same semantics as AppKit).
    */
   onLifecycle(event: LifecycleEvent, fn: LifecycleHandler): void;
-  /** Register synchronous cleanup that runs before any bound process is killed. */
-  onTeardown(fn: () => void): void;
-  /**
-   * Broadcast a termination signal from the main app to every bound process.
-   * Called automatically when this process receives `SIGINT`/`SIGTERM`/`SIGHUP`;
-   * exposed so an interceptor can trigger teardown itself.
-   */
-  broadcastSignal(signal: NodeJS.Signals): void;
-  /**
-   * Supervise a child process alongside the app, concurrently-style: signals pass
-   * through, and if EITHER the child or the app dies the whole set comes down.
-   * Safe to call for several children; teardown is idempotent.
-   */
-  bindProcess(child: BindableProcess): void;
 }
 
 /** A single interceptor, or several. The `createApp` `interceptor?:` option. */
 export type Interceptor = (ctx: InterceptorContext) => void | Promise<void>;
 
-/** How long bound children get to exit on `SIGTERM` before the app force-exits. */
-const TEARDOWN_GRACE_MS = 10_000;
-
-/** The signals that trigger teardown when the MAIN process receives them. */
-const TEARDOWN_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
-const boundChildren = new Set<BindableProcess>();
-const teardownHandlers = new Set<() => void>();
-let processShuttingDown = false;
-let processSignalsBound = false;
-
-function teardownProcess(code: number): void {
-  if (processShuttingDown) return;
-  processShuttingDown = true;
-  for (const handler of teardownHandlers) handler();
-  teardownHandlers.clear();
-  const children = [...boundChildren];
-  for (const child of children) {
-    if (!child.killed) child.kill("SIGTERM");
-  }
-  boundChildren.clear();
-  setTimeout(() => {
-    for (const child of children) child.kill("SIGKILL");
-    process.exit(code);
-  }, TEARDOWN_GRACE_MS).unref();
-}
-
-function broadcastProcessSignal(signal: NodeJS.Signals): void {
-  for (const child of boundChildren) {
-    if (!child.killed) child.kill(signal);
-  }
-  teardownProcess(0);
-}
-
-function bindProcessSignals(): void {
-  if (processSignalsBound) return;
-  processSignalsBound = true;
-  for (const signal of TEARDOWN_SIGNALS) {
-    process.on(signal, () => broadcastProcessSignal(signal));
-  }
-}
-
 /**
  * The mutable machinery behind an {@link InterceptorContext}. Split out so
  * {@link createInterceptorContext} can hand the public context to interceptors
@@ -167,31 +101,9 @@ export interface InterceptorRuntime {
 
 /**
  * Build an {@link InterceptorContext} + its {@link InterceptorRuntime}.
- *
- * Teardown is the generalized `superviseExit`: the first child exit or main-process
- * termination signal flips a one-shot guard, `SIGTERM`s the other bound children,
- * then `process.exit`s after {@link TEARDOWN_GRACE_MS} (an `unref`'d timer, so it
- * never itself holds the loop open). The process-signal listeners are installed
- * lazily on the first `bindProcess` so an app that binds nothing is untouched.
  */
 export function createInterceptorContext(env: ResolvedAppEnv): InterceptorRuntime {
   const handlers = new Map<LifecycleEvent, LifecycleHandler[]>();
-  if (processShuttingDown && boundChildren.size === 0) processShuttingDown = false;
-  if (
-    processSignalsBound &&
-    TEARDOWN_SIGNALS.every((signal) => process.listenerCount(signal) === 0)
-  ) {
-    processSignalsBound = false;
-  }
-
-  const bindProcess = (child: BindableProcess): void => {
-    bindProcessSignals();
-    boundChildren.add(child);
-    child.once("exit", (code) => {
-      logger.warn("bound process exited; tearing down the app", { code });
-      teardownProcess(typeof code === "number" ? code : 1);
-    });
-  };
 
   const onLifecycle = (event: LifecycleEvent, fn: LifecycleHandler): void => {
     const list = handlers.get(event);
@@ -216,12 +128,6 @@ export function createInterceptorContext(env: ResolvedAppEnv): InterceptorRuntim
   const context: InterceptorContext = {
     env,
     onLifecycle,
-    onTeardown: (fn) => {
-      bindProcessSignals();
-      teardownHandlers.add(fn);
-    },
-    broadcastSignal: broadcastProcessSignal,
-    bindProcess,
   };
 
   return { context, emitLifecycle };

package/src/tool-provider.ts

@@ -9,6 +9,16 @@ import {
   type ToolRegistry,
 } from "@databricks/appkit/beta";
 
+/** Optional request state supplied by an agent host when dispatching a plugin tool. */
+export interface AgentToolExecutionContext {
+  /** Resource identity associated with the current agent turn. */
+  readonly resourceId?: string;
+  /** Model endpoint selected for the current agent turn. */
+  readonly model?: string;
+  /** Best-effort progress sink validated by the hosting integration. */
+  readonly writeProgress?: (event: unknown) => Promise<void>;
+}
+
 /**
  * Implements AppKit's `ToolProvider` contract from one native tool registry.
  *
@@ -28,7 +38,12 @@ export abstract class ToolRegistryPlugin<TConfig extends BasePluginConfig = Base
   }
 
   /** Validate and dispatch one AppKit agent tool call. */
-  executeAgentTool(name: string, args: unknown, signal?: AbortSignal): Promise<unknown> {
+  executeAgentTool(
+    name: string,
+    args: unknown,
+    signal?: AbortSignal,
+    _context?: AgentToolExecutionContext,
+  ): Promise<unknown> {
     return executeFromRegistry(this.toolRegistry, name, args, signal);
   }
 }