@kindgi/handler-runtime 0.1.4 → 0.1.5-rc.0

package/src/pack-service/records.ts

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * The pack service's log: `@kindgi/log` records on stderr, subsystem
+ * `pack` (the runtime writes the same schema). Two streams share the sink:
+ *
+ *   - **`log`**: calls, and `ctx.log` beneath them (`pack.tool`,
+ *     `pack.check`). `KINDGI_LOG_LEVEL` / `KINDGI_LOG_LEVELS` apply.
+ *   - **`event`**: the lifecycle (`listening`, `boot-failed`, …), written
+ *     whatever the levels, because a supervisor reads it to know the
+ *     service is up. Its records carry the event's name as `event`, and as
+ *     `kind` too, so a supervisor from before records (which reads bare
+ *     `{"kind": …}` lines) still sees `listening`. `kind` stays through
+ *     0.1.x.
+ *
+ * The format is `KINDGI_LOG_FORMAT`'s, but `auto` is pretty only on a
+ * terminal: a supervisor pipes stderr, and dev mode (`KINDGI_DEV`) doesn't
+ * make it pretty, so a supervisor always gets JSON unless told otherwise.
+ */
+
+import {
+  type LogFields,
+  type Logger,
+  createLogger,
+  loggerFromEnv,
+  resolveLogFormat,
+} from '@kindgi/log';
+
+/** Lifecycle events: always written, the supervisor's to read. */
+export const PACK_SERVICE_EVENTS = [
+  'listening',
+  'boot-failed',
+  'config-invalid',
+  'draining',
+  'stopped',
+] as const;
+export type PackServiceEventKind = (typeof PACK_SERVICE_EVENTS)[number];
+
+const EVENT_LEVEL = {
+  listening: 'info',
+  'boot-failed': 'error',
+  'config-invalid': 'error',
+  draining: 'info',
+  stopped: 'info',
+} as const satisfies Record<PackServiceEventKind, 'info' | 'error'>;
+
+export interface PackServiceLogs {
+  /** Calls, and `ctx.log` beneath them; the levels apply. */
+  readonly log: Logger;
+  /** A lifecycle event, written whatever the levels. */
+  event(kind: PackServiceEventKind, message: string, fields?: LogFields): void;
+}
+
+export type PackServiceLogsOutcome =
+  | { readonly kind: 'ok'; readonly logs: PackServiceLogs; readonly problems: readonly string[] }
+  | { readonly kind: 'err'; readonly message: string };
+
+/** The pack service's logs from `KINDGI_LOG_*`; a bad setting is an error naming it. */
+export function packServiceLogs(input: {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** One line, no newline. Default stderr. */
+  readonly write?: (line: string) => void;
+  readonly isTTY?: boolean;
+}): PackServiceLogsOutcome {
+  // Dev mode doesn't make the service's records pretty: its supervisor reads them.
+  const { KINDGI_DEV: _dev, ...env } = input.env;
+  const write = input.write ?? ((line: string) => void process.stderr.write(`${line}\n`));
+  const isTTY = input.isTTY ?? false;
+  // No unknown-subsystem check: pack code logs under its own names too
+  // (`kindgi.log.get_logger("billing")`, its own `@kindgi/log` loggers).
+  const built = loggerFromEnv({ env, write, isTTY });
+  if (built.kind === 'err') return built;
+  const format = resolveLogFormat(env.KINDGI_LOG_FORMAT, { isTTY }) ?? 'json';
+  const always = createLogger({
+    level: 'trace',
+    format,
+    color: format === 'pretty' && isTTY && (env.NO_COLOR ?? '') === '',
+    write,
+    subsystem: 'pack',
+  });
+  return {
+    kind: 'ok',
+    problems: built.problems,
+    logs: {
+      log: built.logger.child({ subsystem: 'pack' }),
+      event(kind, message, fields = {}) {
+        always[EVENT_LEVEL[kind]](message, { ...fields, event: kind, kind });
+      },
+    },
+  };
+}
+
+/** Logs for a caller that passes none: records on stderr, at the defaults. */
+export function defaultPackServiceLogs(): PackServiceLogs {
+  const built = packServiceLogs({ env: {}, isTTY: false });
+  if (built.kind === 'err') throw new Error(built.message);
+  return built.logs;
+}

package/src/pack-service/service.ts

@@ -29,7 +29,9 @@ import { timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { pathToFileURL } from 'node:url';
 
-import type { HandlerError } from '../handler-runner.js';
+import { type Logger, childSpan, noopLogger, parseTraceparent } from '@kindgi/log';
+
+import type { HandlerContext, HandlerError } from '../handler-runner.js';
 import { runCheck, runHandler } from '../handler-runner.js';
 import type { Index, IndexedGuardrail, IndexedTool } from '../kindgi-index.js';
 import { type PackEnvCheck, missingPackEnv } from '../pack-env.js';
@@ -37,6 +39,7 @@ import {
   type CheckInvokeMessage,
   PACK_HEADERS,
   PACK_PROTOCOL_VERSION,
+  type PackCallContext,
   type PackErrorCode,
   type PackErrorMessage,
   type PackResponse,
@@ -59,6 +62,12 @@ export interface PackServiceOptions {
   /** Deadline when a call sends no `kindgi-timeout-ms`. Default 120 s. */
   readonly defaultTimeoutMs?: number;
   readonly logger?: (event: PackServiceLogEvent) => void;
+  /**
+   * Where the service's records go (`@kindgi/log`, subsystem `pack`): a
+   * record per call, with the call's ids and trace, and each handler's
+   * `ctx.log` beneath it. Default: none. `logger` still gets its events.
+   */
+  readonly log?: Logger;
   /**
    * The process environment the index's `env.required` names are checked
    * against, once, at creation. Default `process.env`.
@@ -115,6 +124,7 @@ export function createPackService(options: PackServiceOptions): PackService {
   const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
   const defaultTimeoutMs = options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
   const logger = options.logger ?? (() => undefined);
+  const log = options.log ?? noopLogger;
   const importModule =
     options.importModule ?? ((p: string) => import(pathToFileURL(p).href) as Promise<unknown>);
   const expectedToken = Buffer.from(options.token);
@@ -138,7 +148,13 @@ export function createPackService(options: PackServiceOptions): PackService {
 
   const envCheck = options.envCheck ?? 'strict';
   const missingEnv = missingPackEnv(options.index.env, options.env ?? process.env);
-  if (missingEnv.length > 0) logger({ kind: 'missing-env', check: envCheck, names: missingEnv });
+  if (missingEnv.length > 0) {
+    logger({ kind: 'missing-env', check: envCheck, names: missingEnv });
+    log.warn(
+      `The pack's env.required ${missingEnv.length === 1 ? 'name has' : 'names have'} no value: ${missingEnv.join(', ')}`,
+      { event: 'missing-env', kind: 'missing-env', check: envCheck, names: missingEnv },
+    );
+  }
 
   /** Why the service can't take calls now, or `undefined` when it can. */
   function notReady(): Reply | undefined {
@@ -239,7 +255,11 @@ export function createPackService(options: PackServiceOptions): PackService {
     };
   }
 
-  function callTool(message: ToolInvokeMessage, signal: AbortSignal): Promise<PackResponse> {
+  function callTool(
+    message: ToolInvokeMessage,
+    signal: AbortSignal,
+    callLog: Logger,
+  ): Promise<PackResponse> {
     const found = toolFor(message.tool);
     if ('refused' in found) return Promise.resolve(found.refused);
     const { tool } = found;
@@ -251,7 +271,7 @@ export function createPackService(options: PackServiceOptions): PackService {
         outputSchema: tool.output,
       },
       input: message.input,
-      ctx: { ...message.ctx, abortSignal: signal },
+      ctx: handlerContext(message.ctx, signal, callLog),
       importHandler: (p) => importModule(p) as never,
     }).then((r) =>
       r.kind === 'ok'
@@ -270,7 +290,11 @@ export function createPackService(options: PackServiceOptions): PackService {
       );
     }
     return runCheck({
-      check: { id: message.check.id, modulePath: options.resolveModule(guardrail.checkModulePath) },
+      check: {
+        id: message.check.id,
+        modulePath: options.resolveModule(guardrail.checkModulePath),
+        ...(guardrail.configSchema !== undefined && { configSchema: guardrail.configSchema }),
+      },
       config: message.config,
       trace: message.trace,
       abortSignal: signal,
@@ -349,24 +373,38 @@ export function createPackService(options: PackServiceOptions): PackService {
     });
 
     const started = Date.now();
+    // The call's ids and trace, on its record and on the handler's `ctx.log`.
+    const call = log.child({
+      ...callIds(message.kind === 'invoke' ? message.ctx : undefined),
+      ...callTrace(req.headers[PACK_HEADERS.traceparent]),
+      target,
+      ...(message.kind === 'invoke' ? { toolId: id } : { checkId: id }),
+    });
     const work =
       message.kind === 'invoke'
-        ? callTool(message, controller.signal)
+        ? callTool(message, controller.signal, call.child({ subsystem: `pack.${target}` }))
         : callCheck(message, controller.signal);
     const outcome = await Promise.race([work, aborted(controller.signal, id, target)]);
     clearTimeout(timer);
     if (controller.signal.aborted) {
-      void work.then(() =>
-        logger({ kind: 'handler-finished-late', target, id, afterMs: Date.now() - started }),
-      );
+      void work.then(() => {
+        const afterMs = Date.now() - started;
+        logger({ kind: 'handler-finished-late', target, id, afterMs });
+        call.warn(`${target} ${id} finished ${afterMs} ms after its call ended`, {
+          event: 'handler-finished-late',
+          kind: 'handler-finished-late',
+          afterMs,
+        });
+      });
     }
-    logger({
-      kind: 'call',
-      target,
-      id,
-      durationMs: Date.now() - started,
-      outcome: outcome.kind === 'error' ? outcome.code : 'ok',
-    });
+    const durationMs = Date.now() - started;
+    const result = outcome.kind === 'error' ? outcome.code : 'ok';
+    logger({ kind: 'call', target, id, durationMs, outcome: result });
+    call[result === 'ok' ? 'info' : 'warn'](
+      `${target} ${id} ${result} ${durationMs}ms`,
+      { event: 'call', kind: 'call', id, outcome: result, durationMs },
+      { inMessage: ['target', 'id', 'outcome', 'durationMs'] },
+    );
     return outcome;
   }
 
@@ -509,3 +547,45 @@ function describe(cause: unknown): string {
 function toolKey(id: string, version: string | undefined): string {
   return version === undefined ? id : `${id}@${version}`;
 }
+
+/**
+ * The context a handler gets: the call's own (`PackCallContext`) and its
+ * abort signal, with `log` and `secrets` there but not enumerable, so
+ * printing, spreading or serializing a context never shows a secret.
+ */
+function handlerContext(wire: PackCallContext, signal: AbortSignal, log: Logger): HandlerContext {
+  const { secrets, ...rest } = wire;
+  const ctx = { ...rest, abortSignal: signal };
+  if (secrets !== undefined) {
+    Object.defineProperty(ctx, 'secrets', { value: secrets, enumerable: false });
+  }
+  Object.defineProperty(ctx, 'log', { value: log, enumerable: false });
+  return ctx as HandlerContext;
+}
+
+/** The ids a call's records carry, from its context. */
+function callIds(ctx: PackCallContext | undefined): Record<string, string> {
+  if (ctx === undefined) return {};
+  const ids: Record<string, string> = {};
+  for (const key of ['tenantId', 'projectId', 'orgId', 'runId', 'requestId'] as const) {
+    const value: unknown = ctx[key];
+    if (typeof value === 'string' && value !== '') ids[key] = value;
+  }
+  return ids;
+}
+
+/**
+ * The call's trace: the caller's trace id, and a span of this call's own
+ * whose parent is the caller's. None when the caller sent no
+ * `traceparent` (an older runtime): a fresh trace would join nothing.
+ */
+function callTrace(header: string | string[] | undefined): Record<string, string> {
+  const incoming = parseTraceparent(Array.isArray(header) ? header[0] : header);
+  if (incoming === undefined) return {};
+  const span = childSpan({
+    traceId: incoming.traceId,
+    spanId: incoming.parentSpanId,
+    flags: incoming.flags,
+  });
+  return { traceId: span.traceId, spanId: span.spanId };
+}

package/src/pack-service/supervisor.ts

@@ -50,6 +50,7 @@ export interface PackServiceSupervisorOptions {
    *
    *   - Node: `[process.execPath, '--enable-source-maps', <@kindgi/handler-runtime/pack-service-main>]`
    *   - Python: `[<the pack's python>, '-m', 'kindgi.pack', 'serve']`
+   *   - Java and Scala: `['sh', <kindgi-pack-java>, '-cp', <classpath> (or `@<argfile>`), 'com.kindgi.pack.Main', 'serve']`
    */
   readonly command: readonly [string, ...string[]];
   /** Where the index's module paths resolve — the pack directory. */
@@ -102,8 +103,16 @@ export type PackServiceSupervisorEvent =
   | { readonly kind: 'exited'; readonly code: number | null; readonly signal: string | null }
   | { readonly kind: 'restarting'; readonly attempt: number }
   | { readonly kind: 'gave-up'; readonly attempts: number }
-  /** One of the service's own JSON log lines (a call, draining, …). */
-  | { readonly kind: 'log'; readonly event: Readonly<Record<string, unknown>> };
+  /**
+   * A record the service wrote (a call, draining, an author's `ctx.log`
+   * line, …), or a bare event from an older service: `event` as
+   * `serviceEvent` reads it, `line` as written.
+   */
+  | {
+      readonly kind: 'log';
+      readonly event: Readonly<Record<string, unknown>>;
+      readonly line: string;
+    };
 
 export interface BootFailure {
   readonly problems: readonly string[];
@@ -122,7 +131,7 @@ export interface PackRelayCall {
   readonly requestId?: string;
   /** The caller's protocol version (`kindgi-protocol`), passed on as is. */
   readonly protocol?: string;
-  /** The caller's W3C trace context (`traceparent`), passed on as is. */
+  /** The caller's W3C trace context (`traceparent`), passed on as is, so the child's records carry its trace. */
   readonly traceparent?: string;
 }
 
@@ -225,7 +234,13 @@ export function createPackServiceSupervisor(
   let front: { readonly server: Server; readonly url: string; readonly port: number } | undefined;
 
   async function boot(indexPath: string): Promise<Result<Child, BootFailure>> {
-    const env = { ...(await options.env()), KINDGI_PACK_SERVICE_TOKEN: token, PORT: '0' };
+    // JSON whatever the pack's env says: this process reads the child's records.
+    const env = {
+      ...(await options.env()),
+      KINDGI_PACK_SERVICE_TOKEN: token,
+      PORT: '0',
+      KINDGI_LOG_FORMAT: 'json',
+    };
     const [program, ...args] = options.command;
     const child = spawn(
       program,
@@ -265,7 +280,7 @@ export function createPackServiceSupervisor(
         } else if (event.kind === 'boot-failed' || event.kind === 'config-invalid') {
           problems.push(...problemsOf(event));
         } else {
-          emit({ kind: 'log', event });
+          emit({ kind: 'log', event, line });
         }
       });
       child.once('error', (cause) => fail([cause.message]));
@@ -625,21 +640,58 @@ function problemsOf(event: Readonly<Record<string, unknown>>): readonly string[]
   return Array.isArray(event.problems) ? event.problems.map(String) : [];
 }
 
-/** The service's own log lines are JSON objects with a `kind`. */
-function serviceEvent(
+/** What a pack service from before records wrote as bare `{"kind": …}` lines. */
+const LEGACY_EVENTS: ReadonlySet<string> = new Set([
+  'listening',
+  'boot-failed',
+  'config-invalid',
+  'missing-env',
+  'draining',
+  'stopped',
+  'call',
+  'handler-finished-late',
+]);
+
+/**
+ * One of the service's own log lines, as an event with a `kind`:
+ *
+ *   - a record (`@kindgi/log`: `time`, `level`, `subsystem`, `message`).
+ *     The service's own, subsystem `pack`, carry their event as `event`
+ *     (`listening`, `call`, …), which becomes `kind`. Any other record, an
+ *     author's `ctx.log` (`pack.tool`) say, comes back with `kind: 'record'`,
+ *     to show, never to act on;
+ *   - a bare `{"kind": …}` line from a pack service from before records,
+ *     for the events it wrote. Any other JSON line is the pack's own
+ *     output, shown as it is.
+ */
+export function serviceEvent(
   line: string,
 ): (Record<string, unknown> & { readonly kind: string }) | undefined {
   if (!line.startsWith('{')) return undefined;
+  let parsed: unknown;
   try {
-    const parsed = JSON.parse(line) as unknown;
-    return parsed !== null &&
-      typeof parsed === 'object' &&
-      typeof (parsed as { kind?: unknown }).kind === 'string'
-      ? (parsed as Record<string, unknown> & { readonly kind: string })
-      : undefined;
+    parsed = JSON.parse(line);
   } catch {
     return undefined;
   }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined;
+  const fields = parsed as Record<string, unknown>;
+  if (isRecord(fields)) {
+    const own = fields.subsystem === 'pack' && typeof fields.event === 'string';
+    return { ...fields, kind: own ? (fields.event as string) : 'record' };
+  }
+  return typeof fields.kind === 'string' && LEGACY_EVENTS.has(fields.kind)
+    ? (fields as Record<string, unknown> & { readonly kind: string })
+    : undefined;
+}
+
+function isRecord(fields: Record<string, unknown>): boolean {
+  return (
+    typeof fields.time === 'string' &&
+    typeof fields.level === 'string' &&
+    typeof fields.subsystem === 'string' &&
+    typeof fields.message === 'string'
+  );
 }
 
 function describe(cause: unknown): string {

package/src/protocol.ts

@@ -32,8 +32,13 @@ export interface PackCallContext {
   readonly orgId?: string;
   /** The individual call — e.g. the model's tool-call id. */
   readonly requestId?: string;
+  /**
+   * The env values the tool declares (`needsSpec.env`), resolved for this
+   * call: project, else org, else tenant (protocol 2.5.0). Strings.
+   */
   readonly env?: Readonly<Record<string, unknown>>;
   readonly secrets?: Readonly<Record<string, unknown>>;
+  /** Reserved: no runtime sends it yet. */
   readonly config?: Readonly<Record<string, unknown>>;
   /** The calling agent version's settings blocks' values, by block id (protocol 2.4.0). */
   readonly settings?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;