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

package/src/handler-runner.ts

@@ -16,7 +16,8 @@
  *   3. calls `handler(input, ctx)`;
  *   4. validates the output against the tool's output JSON Schema.
  *
- * A check imports the module, resolves its `evaluate`, and calls
+ * A check validates the config against the guardrail's `configSchema`
+ * (as sent), imports the module, resolves its `evaluate`, and calls
  * `evaluate(config, trace, bindings)`.
  *
  * Neither throws: every failure is a typed `HandlerError`. The runner
@@ -24,17 +25,19 @@
  * pack code is the team's own (trusted).
  */
 
-import type { ValidateFunction } from 'ajv';
+import type { ErrorObject, ValidateFunction } from 'ajv';
 import * as addFormatsModule from 'ajv-formats';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 
+import type { Logger } from '@kindgi/log';
 import { type ZodLikeSchema, isZodSchema, parseWithSchema } from '@kindgi/schema';
 import type { Result } from '@kindgi/types';
 
 /**
  * What a handler gets beside its input: the tenant and run it serves,
- * and its resolved "typed needs" (env, secrets, config), composed by
- * the server and sent with the call.
+ * and the "typed needs" it declares (`needsSpec.env`, `needsSpec.secrets`),
+ * resolved by the runtime for this call and sent with it. `config` is
+ * reserved: no runtime sends it yet.
  */
 export interface HandlerContext {
   readonly tenantId: string;
@@ -44,6 +47,7 @@ export interface HandlerContext {
   /** The project's org, when it has one (2.3.0). */
   readonly orgId?: string;
   readonly requestId?: string;
+  /** The declared env values: project, else org, else tenant (protocol 2.5.0). */
   readonly env?: Readonly<Record<string, unknown>>;
   readonly secrets?: Readonly<Record<string, unknown>>;
   readonly config?: Readonly<Record<string, unknown>>;
@@ -59,6 +63,12 @@ export interface HandlerContext {
    * should pass it on so they stop promptly.
    */
   readonly abortSignal?: AbortSignal;
+  /**
+   * Never on the wire; the pack service adds it: a logger bound to the
+   * call (its tenant, run, request and trace). Not enumerable, like
+   * `secrets`.
+   */
+  readonly log?: Logger;
 }
 
 /**
@@ -87,6 +97,14 @@ export interface ToolInvocationSpec {
 export interface CheckInvocationSpec {
   readonly id: string;
   readonly modulePath: string;
+  /**
+   * The guardrail's `configSchema` from the index. A call's `config` that
+   * doesn't fit it is refused (`input-validation-failed`, with the
+   * issues) before the check runs. It is checked as sent, the schema's
+   * defaults not filled in, as the indexer checks a declared config; the
+   * check's own schema fills them in.
+   */
+  readonly configSchema?: Readonly<Record<string, unknown>>;
 }
 
 /** Every way a call can fail; the pack service answers with the same code. */
@@ -367,6 +385,35 @@ export async function runCheck(options: RunCheckOptions): Promise<Result<unknown
   const { check, config, trace } = options;
   const importCheck = options.importCheck ?? defaultImportCheck;
 
+  if (check.configSchema !== undefined) {
+    let configValidator: ValidateFunction;
+    try {
+      configValidator = compileSchema(check.configSchema, 'output');
+    } catch (cause) {
+      return {
+        kind: 'err',
+        error: {
+          code: 'input-validation-failed',
+          message: `Check "${check.id}" config schema failed to compile: ${stringifyError(cause)}`,
+          toolId: check.id,
+          cause: serializeCause(cause),
+        },
+      };
+    }
+    if (!configValidator(config)) {
+      const issues = configValidator.errors ?? [];
+      return {
+        kind: 'err',
+        error: {
+          code: 'input-validation-failed',
+          message: `Check "${check.id}" config failed validation${describeFirstIssue(issues)}`,
+          toolId: check.id,
+          issues,
+        },
+      };
+    }
+  }
+
   let module_: CheckModule;
   try {
     module_ = await importCheck(check.modulePath);
@@ -414,6 +461,17 @@ export async function runCheck(options: RunCheckOptions): Promise<Result<unknown
   return { kind: 'ok', value: result };
 }
 
+/**
+ * Where the first issue is and what it says (` at /maxChars: must be >= 0`),
+ * for a message that is read without its issues: a runtime reports a
+ * check's error by its code and message alone.
+ */
+function describeFirstIssue(issues: readonly ErrorObject[]): string {
+  const first = issues[0];
+  if (first === undefined) return '';
+  return `${first.instancePath === '' ? '' : ` at ${first.instancePath}`}: ${first.message ?? 'invalid'}`;
+}
+
 function resolveCheckEvaluate(
   module_: CheckModule,
 ):

package/src/index.ts

@@ -32,17 +32,23 @@ export type {
   KindgiProviderDeclaration,
   KindgiConfigFile,
   LoadKindgiConfigOptions,
+  JvmLanguage,
   PackLanguage,
 } from './kindgi-index.js';
 export {
   DEFAULT_DISCOVERY,
+  DEFAULT_JAVA_DISCOVERY,
+  DEFAULT_SCALA_DISCOVERY,
   DEFAULT_PYTHON_DISCOVERY,
   HELP_TEXT as KINDGI_INDEX_HELP_TEXT,
   INDEX_ENVELOPE_VERSION,
   KERNEL_PAYLOAD_VERSION,
   KINDGI_CONFIG_FILENAMES,
+  KINDGI_JSON_CONFIG_FILENAME,
   PYPROJECT_FILENAME,
+  RESERVED_CHECK_IDS,
   findKindgiConfig,
+  isJvmLanguage,
   loadKindgiConfig,
   packLanguage,
   resolveDiscovery,

package/src/kindgi-index.ts

@@ -89,9 +89,17 @@ export interface DiscoveryConfig {
 /**
  * The language a pack's code (tool handlers, guardrail checks) is written
  * in — which indexer reads it and which pack service runs it. Agents and
- * flows are data in either.
+ * flows are data in any of them.
  */
-export type PackLanguage = 'node' | 'python';
+export type PackLanguage = 'node' | 'python' | 'java' | 'scala';
+
+/** The languages that run on the JVM: built by Maven (Java) or sbt (Scala), indexed and served by kindgi-pack. */
+export type JvmLanguage = Extract<PackLanguage, 'java' | 'scala'>;
+
+/** Whether a pack's code runs on the JVM (kindgi-pack's indexer and pack service). */
+export function isJvmLanguage(language: PackLanguage): language is JvmLanguage {
+  return language === 'java' || language === 'scala';
+}
 
 /**
  * The subset of `kindgi.config.ts` this indexer consumes. Other
@@ -108,7 +116,7 @@ export interface KindgiConfig {
   /**
    * The pack's code language. Absent in `kindgi.config.*`: `node`. A
    * `[tool.kindgi]` table in `pyproject.toml` is a Python pack unless it
-   * says otherwise.
+   * says otherwise. A `kindgi.config.json` says `"java"` or `"scala"`.
    */
   readonly language?: PackLanguage;
   /**
@@ -185,15 +193,53 @@ export const DEFAULT_PYTHON_DISCOVERY: Required<DiscoveryConfig> = {
   flows: 'flows/**/*.py',
 };
 
+/**
+ * Default discovery patterns of a Java pack (`com.kindgi.pack.Main index`
+ * reads the same keys from `kindgi.config.json`): the source files under
+ * any `tools`, `guardrails`, `agents` or `flows` package.
+ */
+export const DEFAULT_JAVA_DISCOVERY: Required<DiscoveryConfig> = {
+  tools: 'src/main/java/**/tools/**/*.java',
+  guardrails: 'src/main/java/**/guardrails/**/*.java',
+  agents: 'src/main/java/**/agents/**/*.java',
+  flows: 'src/main/java/**/flows/**/*.java',
+};
+
+/**
+ * Default discovery patterns of a Scala pack (kindgi-pack's indexer reads
+ * the same keys): the source files under any `tools`, `guardrails`, `agents`
+ * or `flows` package.
+ */
+export const DEFAULT_SCALA_DISCOVERY: Required<DiscoveryConfig> = {
+  tools: 'src/main/scala/**/tools/**/*.scala',
+  guardrails: 'src/main/scala/**/guardrails/**/*.scala',
+  agents: 'src/main/scala/**/agents/**/*.scala',
+  flows: 'src/main/scala/**/flows/**/*.scala',
+};
+
 /** A config's discovery patterns with the language's defaults filled in. */
 export function resolveDiscovery(
   discovery: DiscoveryConfig | undefined,
   language: PackLanguage = 'node',
 ): Required<DiscoveryConfig> {
-  const defaults = language === 'python' ? DEFAULT_PYTHON_DISCOVERY : DEFAULT_DISCOVERY;
+  const defaults =
+    language === 'python'
+      ? DEFAULT_PYTHON_DISCOVERY
+      : language === 'java'
+        ? DEFAULT_JAVA_DISCOVERY
+        : language === 'scala'
+          ? DEFAULT_SCALA_DISCOVERY
+          : DEFAULT_DISCOVERY;
   return { ...defaults, ...(discovery ?? {}) };
 }
 
+/** The command that indexes a pack of each language other than Node. */
+const OWN_INDEXER: Readonly<Record<Exclude<PackLanguage, 'node'>, string>> = {
+  python: 'python -m kindgi.pack index',
+  java: 'java -cp <classpath> com.kindgi.pack.Main index',
+  scala: 'java -cp <classpath> com.kindgi.pack.Main index',
+};
+
 // -----------------------------------------------------------------------
 // Manifest entry shapes emitted in index.json
 // -----------------------------------------------------------------------
@@ -272,6 +318,8 @@ export interface IndexedAgent {
   readonly output?: Readonly<Record<string, unknown>>;
   /** How the agent's turns retry failed tool calls (`{ maxRetries?, retryOn? }`). */
   readonly toolErrors?: Readonly<Record<string, unknown>>;
+  /** How the agent uses what it retrieves (`{ instructionTypes? }`). */
+  readonly memory?: Readonly<Record<string, unknown>>;
   readonly modulePath: string;
 }
 
@@ -329,7 +377,8 @@ export type IndexerErrorCode =
   | 'zod-conversion-failed'
   | 'manifest-validation-failed'
   | 'output-write-failed'
-  | 'language-mismatch';
+  | 'language-mismatch'
+  | 'reserved-check-id';
 
 export interface IndexerError {
   readonly code: IndexerErrorCode;
@@ -434,7 +483,7 @@ export async function runIndexer(
       kind: 'err',
       error: {
         code: 'language-mismatch',
-        message: `${packDir} is a ${packLanguage(config)} pack; index it with its own indexer (python -m kindgi.pack index)`,
+        message: `${packDir} is a ${packLanguage(config)} pack; index it with its own indexer (${OWN_INDEXER[packLanguage(config) as Exclude<PackLanguage, 'node'>]})`,
       },
     };
   }
@@ -590,6 +639,11 @@ export async function runIndexer(
           fileErrors.push(built.error);
           continue;
         }
+        const reserved = reservedCheckIn(unwrapped, module_, relPath);
+        if (reserved !== undefined) {
+          fileErrors.push(reserved);
+          continue;
+        }
         const duplicate = duplicateOf('guardrail', built.value.id, undefined, relPath);
         if (duplicate !== undefined) {
           fileErrors.push(duplicate);
@@ -937,19 +991,49 @@ export async function loadKindgiConfig(
 /** `pyproject.toml` — a Python pack keeps its config in the `[tool.kindgi]` table. */
 export const PYPROJECT_FILENAME = 'pyproject.toml';
 
+/**
+ * `kindgi.config.json` — a JVM pack's config (`"language": "java"`): the
+ * same keys as `kindgi.config.ts`, as JSON, so Maven, Gradle and sbt builds
+ * share one file.
+ */
+export const KINDGI_JSON_CONFIG_FILENAME = 'kindgi.config.json';
+
 export interface KindgiConfigFile {
   readonly path: string;
-  /** `module`: a `kindgi.config.*`; `pyproject`: the `[tool.kindgi]` table of a `pyproject.toml`. */
-  readonly format: 'module' | 'pyproject';
+  /**
+   * `module`: a `kindgi.config.*` module; `pyproject`: the `[tool.kindgi]`
+   * table of a `pyproject.toml`; `json`: a `kindgi.config.json`.
+   */
+  readonly format: 'module' | 'pyproject' | 'json';
+  /**
+   * Another config file at the same root, next to a `kindgi.config.json`:
+   * loading the config refuses the pack, naming both.
+   */
+  readonly conflictsWith?: string;
 }
 
 /**
- * Where a pack's config lives: the first `kindgi.config.*` at `packDir`
- * (`KINDGI_CONFIG_FILENAMES` order), else a `pyproject.toml` with a
- * `[tool.kindgi]` table. `undefined` when neither — a `pyproject.toml`
- * without the table is a Python project, not a pack.
+ * Where a pack's config lives: the first `kindgi.config.*` module at
+ * `packDir` (`KINDGI_CONFIG_FILENAMES` order), else a `pyproject.toml`
+ * with a `[tool.kindgi]` table; a `kindgi.config.json` when it is the only
+ * one. `undefined` when none — a `pyproject.toml` without the table is a
+ * Python project, not a pack. A `kindgi.config.json` next to another
+ * config file is returned with `conflictsWith`, and the loader refuses it.
  */
 export async function findKindgiConfig(packDir: string): Promise<KindgiConfigFile | undefined> {
+  const other = await findModuleOrPyproject(packDir);
+  const json = path.join(packDir, KINDGI_JSON_CONFIG_FILENAME);
+  if (await exists(json)) {
+    return {
+      path: json,
+      format: 'json',
+      ...(other !== undefined && { conflictsWith: other.path }),
+    };
+  }
+  return other;
+}
+
+async function findModuleOrPyproject(packDir: string): Promise<KindgiConfigFile | undefined> {
   for (const name of KINDGI_CONFIG_FILENAMES) {
     const candidate = path.join(packDir, name);
     if (await exists(candidate)) return { path: candidate, format: 'module' };
@@ -992,7 +1076,9 @@ async function loadConfig(
   if (explicitPath !== undefined) {
     const resolved = path.resolve(explicitPath);
     if (await exists(resolved)) {
-      const format = path.basename(resolved) === PYPROJECT_FILENAME ? 'pyproject' : 'module';
+      const base = path.basename(resolved);
+      const format =
+        base === PYPROJECT_FILENAME ? 'pyproject' : base.endsWith('.json') ? 'json' : 'module';
       file = { path: resolved, format };
     }
   } else {
@@ -1003,16 +1089,32 @@ async function loadConfig(
       kind: 'err',
       error: {
         code: 'config-not-found',
-        message: `No kindgi.config.{ts,mts,mjs,js,cjs}, or pyproject.toml with a [tool.kindgi] table, found at pack root ${packDir}`,
+        message: `No kindgi.config.{ts,mts,mjs,js,cjs}, pyproject.toml with a [tool.kindgi] table, or kindgi.config.json, found at pack root ${packDir}`,
+      },
+    };
+  }
+  if (file.conflictsWith !== undefined) {
+    const other = path.basename(file.conflictsWith);
+    return {
+      kind: 'err',
+      error: {
+        code: 'config-invalid',
+        message:
+          `${packDir} has two pack configs, ${KINDGI_JSON_CONFIG_FILENAME} and ${other}; a pack has one. ` +
+          `Keep ${KINDGI_JSON_CONFIG_FILENAME} for a Java or Scala pack, or ${other} for a ` +
+          `${file.conflictsWith.endsWith(PYPROJECT_FILENAME) ? 'Python' : 'TypeScript'} one, and remove the other.`,
+        filePath: file.path,
       },
     };
   }
   const read =
     file.format === 'pyproject'
       ? await readPyprojectTable(file.path)
-      : await importConfigModule(file.path, importModule);
+      : file.format === 'json'
+        ? await readJsonConfig(file.path)
+        : await importConfigModule(file.path, importModule);
   if (read.kind === 'err') return read;
-  const checked = checkConfig(read.value, file.path);
+  const checked = checkConfig(read.value, file.path, file.format);
   if (checked.kind === 'err') return checked;
   const record = checked.value;
   return {
@@ -1084,10 +1186,26 @@ async function readPyprojectTable(
   return { kind: 'ok', value: table as Record<string, unknown> };
 }
 
+async function readJsonConfig(
+  filePath: string,
+): Promise<Result<Record<string, unknown>, IndexerError>> {
+  let document: unknown;
+  try {
+    document = JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch (cause) {
+    return parseFailed(filePath, `Failed to read ${filePath}: ${stringifyError(cause)}`, cause);
+  }
+  if (!isObject(document)) {
+    return parseFailed(filePath, `Config file ${filePath}: the file must hold a JSON object`);
+  }
+  return { kind: 'ok', value: document as Record<string, unknown> };
+}
+
 /** The checks every config passes, whatever file it came from. */
 function checkConfig(
   record: Record<string, unknown>,
   filePath: string,
+  format: KindgiConfigFile['format'],
 ): Result<KindgiConfig, IndexerError> {
   const pack = record.pack;
   if (typeof pack !== 'object' || pack === null) {
@@ -1109,7 +1227,19 @@ function checkConfig(
       `Config file ${filePath}: 'pack.version' is missing or not a non-empty string`,
     );
   }
-  if (record.language !== undefined && record.language !== 'node' && record.language !== 'python') {
+  if (format === 'json') {
+    // kindgi.config.json is the JVM's config: it names its language.
+    if (record.language !== 'java' && record.language !== 'scala') {
+      return parseFailed(
+        filePath,
+        `Config file ${filePath}: ${KINDGI_JSON_CONFIG_FILENAME} is a JVM pack's config; it says "language": "java" or "scala"`,
+      );
+    }
+  } else if (
+    record.language !== undefined &&
+    record.language !== 'node' &&
+    record.language !== 'python'
+  ) {
     return parseFailed(filePath, `Config file ${filePath}: 'language' must be "node" or "python"`);
   }
   return { kind: 'ok', value: record as KindgiConfig };
@@ -1368,6 +1498,50 @@ function buildTool(
   return { kind: 'ok', value: tool };
 }
 
+/**
+ * The built-in checks' ids (`BUILT_IN_CHECK_IDS` in `@kindgi/guardrails`; a test holds the two
+ * equal). A guardrail may name one (`check: 'must-cite'`) and the runtime runs the built-in; a
+ * pack may never ship its own check under one, which the runtime would silently replace.
+ */
+export const RESERVED_CHECK_IDS: readonly string[] = [
+  'must-cite',
+  'never-call-tool',
+  'max-tool-calls',
+  'output-matches',
+  'tool-order',
+  'required-substring',
+  'forbidden-substring',
+];
+
+/**
+ * A check implementation (an object with an `id` and an `evaluate` function) under a built-in
+ * id: the guardrail's own `check`, or any check the module exports. Naming a built-in by its id
+ * (a string) is the way to use it, and is fine.
+ */
+function reservedCheckIn(
+  guardrail: unknown,
+  module_: unknown,
+  relPath: string,
+): IndexerError | undefined {
+  const candidates: unknown[] = [
+    isObject(guardrail) ? (guardrail as Record<string, unknown>).check : undefined,
+    ...(isObject(module_) ? Object.values(module_ as Record<string, unknown>) : []),
+  ];
+  for (const c of candidates) {
+    if (!isObject(c)) continue;
+    const rec = c as Record<string, unknown>;
+    if (typeof rec.id !== 'string' || typeof rec.evaluate !== 'function') continue;
+    if (!RESERVED_CHECK_IDS.includes(rec.id)) continue;
+    return {
+      code: 'reserved-check-id',
+      message: `${relPath} ships its own check under "${rec.id}", a built-in check's id: a pack can't replace a built-in. Rename your check (for example "<pack>.checks.${rec.id}"), or, to use the built-in, name it (check: '${rec.id}') and drop your implementation.`,
+      filePath: relPath,
+      field: 'check',
+    };
+  }
+  return undefined;
+}
+
 function buildGuardrail(
   raw: unknown,
   relPath: string,
@@ -1510,6 +1684,7 @@ function optionalAgentFields(rec: Record<string, unknown>): Partial<IndexedAgent
     'output',
     'toolErrors',
     'modelSettings',
+    'memory',
   ] as const) {
     if (isObject(rec[key])) out[key] = rec[key];
   }

package/src/pack-env.ts

@@ -6,7 +6,7 @@
  * libraries they import take from `process.env` (a database URL a client
  * reads at import, a bucket name). Declared once per pack, in
  * `kindgi.config` (`env: { required, optional }`; Python:
- * `[tool.kindgi.env]`), and carried in `index.json`, so the pack service
+ * `[tool.kindgi.env]`; Java and Scala: `env` in `kindgi.config.json`), and carried in `index.json`, so the pack service
  * in an image knows what it needs.
  *
  * A deployment injects exactly these names: `required` must be there for
@@ -14,8 +14,8 @@
  * has a value. Nothing else from an env file reaches the process.
  *
  * Distinct from `needsSpec.env` / `ctx.env`, the per-call values the
- * runtime resolves for a call's tenant, and from `needsSpec.secrets` /
- * `ctx.secrets`.
+ * runtime resolves for a call (its project's, else its org's, else its
+ * tenant's, from `/v1/env`), and from `needsSpec.secrets` / `ctx.secrets`.
  */
 
 /** A pack's declared process environment, as `index.json` carries it. */

package/src/pack-service/main.ts

@@ -30,8 +30,12 @@
  * broken build never becomes ready. SIGTERM drains in-flight calls
  * (readyz answers 503 meanwhile) and exits 0.
  *
- * Logs are JSON lines on stderr. The `listening` line carries the bound
- * port, for callers that start it with `PORT=0`.
+ * Logs are `@kindgi/log` records on stderr (subsystem `pack`), at
+ * `KINDGI_LOG_LEVEL` / `KINDGI_LOG_LEVELS`, in `KINDGI_LOG_FORMAT` (`auto`:
+ * JSON unless stderr is a terminal): a record per call, and the
+ * lifecycle (`listening`, `boot-failed`, `draining`, …) whatever the
+ * levels (`./records.ts`). The `listening` record carries the bound port,
+ * for callers that start it with `PORT=0`.
  */
 
 import { access, readFile } from 'node:fs/promises';
@@ -44,6 +48,7 @@ import { isProcessEntrypoint } from '../entrypoint.js';
 import type { Index } from '../kindgi-index.js';
 import { INDEX_ENVELOPE_VERSION, readBundleMap } from '../kindgi-index.js';
 import { PACK_ENV_CHECK_VAR, type PackEnvCheck, parsePackEnvCheck } from '../pack-env.js';
+import { type PackServiceLogs, defaultPackServiceLogs, packServiceLogs } from './records.js';
 import { type PackService, type PackServiceLogEvent, createPackService } from './service.js';
 
 export interface PackServiceConfig {
@@ -132,11 +137,20 @@ type StartOutcome =
   | { readonly kind: 'ok'; readonly value: RunningPackService }
   | { readonly kind: 'err'; readonly problems: readonly string[] };
 
-/** Load the index, check and prewarm every module, then listen. */
+/**
+ * Load the index, check and prewarm every module, then listen. `logs`:
+ * where its records go (default: stderr, at the default levels). A
+ * function instead gets the service's events as before records, and no
+ * records are written.
+ */
 export async function startPackService(
   config: PackServiceConfig,
-  logger: (event: PackServiceLogEvent | Record<string, unknown>) => void = logJson,
+  logs:
+    | PackServiceLogs
+    | ((event: PackServiceLogEvent | Record<string, unknown>) => void) = defaultPackServiceLogs(),
 ): Promise<StartOutcome> {
+  const legacy = typeof logs === 'function' ? logs : undefined;
+  const records = typeof logs === 'function' ? undefined : logs;
   let index: Index;
   try {
     index = JSON.parse(await readFile(config.indexPath, 'utf8')) as Index;
@@ -177,7 +191,10 @@ export async function startPackService(
     token: config.token,
     ...(config.maxConcurrency !== undefined && { maxConcurrency: config.maxConcurrency }),
     ...(config.envCheck !== undefined && { envCheck: config.envCheck }),
-    logger,
+    ...(legacy !== undefined && { logger: legacy }),
+    ...(records !== undefined && {
+      log: records.log.child({ packId: index.packId, artifactVersion: index.artifactVersion }),
+    }),
   });
   const failures = await service.prewarm();
   if (failures.length > 0) return { kind: 'err', problems: failures.map((f) => f.message) };
@@ -189,12 +206,9 @@ export async function startPackService(
       : server.listen(config.port, config.host, ready),
   );
   const port = (server.address() as AddressInfo).port;
-  logger({
-    kind: 'listening',
-    port,
-    packId: index.packId,
-    artifactVersion: index.artifactVersion,
-  });
+  const listening = { port, packId: index.packId, artifactVersion: index.artifactVersion };
+  legacy?.({ kind: 'listening', ...listening });
+  records?.event('listening', `Listening on port ${port}`, listening);
   return {
     kind: 'ok',
     value: {
@@ -219,34 +233,39 @@ export async function main(
   argv: readonly string[] = process.argv.slice(2),
   env: Readonly<Record<string, string | undefined>> = process.env,
 ): Promise<number> {
+  const built = packServiceLogs({ env, isTTY: process.stderr.isTTY === true });
+  if (built.kind === 'err') {
+    defaultPackServiceLogs().event('config-invalid', built.message, { problems: [built.message] });
+    return 1;
+  }
+  const logs = built.logs;
+  for (const problem of built.problems) logs.log.warn(problem);
   const config = readPackServiceConfig(argv, env);
   if (config.kind === 'err') {
-    logJson({ kind: 'config-invalid', problems: config.problems });
+    logs.event('config-invalid', 'The pack service configuration is invalid', {
+      problems: config.problems,
+    });
     return 1;
   }
   // The token is for the service's callers. The pack's code, loaded
   // next, runs in this process and has no use for it — and a dependency
   // that read it could call the pack's tools around the runtime.
   Reflect.deleteProperty(process.env, 'KINDGI_PACK_SERVICE_TOKEN');
-  const started = await startPackService(config.value);
+  const started = await startPackService(config.value, logs);
   if (started.kind === 'err') {
-    logJson({ kind: 'boot-failed', problems: started.problems });
+    logs.event('boot-failed', 'The pack service failed to boot', { problems: started.problems });
     return 1;
   }
   await new Promise<void>((stopped) => {
     process.once('SIGTERM', () => {
-      logJson({ kind: 'draining' });
+      logs.event('draining', 'Draining: finishing the calls in flight');
       void started.value.stop().then(stopped);
     });
   });
-  logJson({ kind: 'stopped' });
+  logs.event('stopped', 'Stopped');
   return 0;
 }
 
-function logJson(event: PackServiceLogEvent | Record<string, unknown>): void {
-  process.stderr.write(`${JSON.stringify(event)}\n`);
-}
-
 function describe(cause: unknown): string {
   return cause instanceof Error ? cause.message : String(cause);
 }