@polycore/runner 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycore/runner",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Polycore runner: executes governed, read-only-constrained connectors against a customer's datastores. Runs in the customer's own infrastructure; holds scoped credentials and connects outbound to the control plane.",
   "type": "module",
@@ -30,7 +30,7 @@
     "tsx": "4.21.0",
     "ws": "8.18.3",
     "zod": "4.4.3",
-    "@polycore/protocol": "^0.3.0"
+    "@polycore/protocol": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "25.6.2",

package/src/action.ts

@@ -14,7 +14,7 @@ import type { z } from "zod";
  * its environment — the credential never leaves the runner's host.
  */
 
-export type ActionEffect = "read" | "mutate";
+export type ActionHazard = "read" | "write";
 
 /** Human-facing progress sink, mirroring the desktop SDK's `ctx.log`. */
 export interface ActionLogger {
@@ -39,11 +39,11 @@ export interface Action<Input = unknown, Output = unknown> {
   readonly description: string;
   readonly tags?: readonly string[];
   /**
-   * Hazard class. Defaults to `mutate` — the safe default, since an
+   * Hazard class. Defaults to `write` — the safe default, since an
    * unclassified operation must be treated as dangerous and routed through
    * the approval gate. Declare `read` for idempotent, side-effect-free work.
    */
-  readonly effect?: ActionEffect;
+  readonly hazard?: ActionHazard;
   readonly input: z.ZodType<Input>;
   readonly output: z.ZodType<Output>;
   /** Secret keys this action needs, mapped to a human description. */

package/src/cli.ts

@@ -156,7 +156,7 @@ async function main(): Promise<void> {
     for (const [slug, registry] of registries) {
       for (const capability of registry.list()) {
         process.stdout.write(
-          `[${slug}] ${capability.name}  [${capability.kind}/${capability.effect}]  ${capability.description}\n`,
+          `[${slug}] ${capability.name}  [${capability.kind}/${capability.hazard}]  ${capability.description}\n`,
         );
       }
     }

package/src/connect.ts

@@ -23,9 +23,12 @@ export function describeConnectors(
   return registry.list().map((capability) => ({
     name: capability.name,
     description: capability.description,
-    effect: capability.effect,
+    hazard: capability.hazard,
     kind: capability.kind,
     params: z.toJSONSchema(capability.params),
+    ...(capability.output === undefined
+      ? {}
+      : { result: z.toJSONSchema(capability.output) }),
   }));
 }
 

package/src/connector.ts

@@ -4,14 +4,23 @@ import type { Action, ActionLogger, LoadedAction } from "./action.js";
 import type { EnvironmentConfig, ProjectConfig } from "./config.js";
 
 /**
- * Hazard class for a connector. Lane 1 connectors are always `read`: * they exist precisely because they are mutation-incapable, which is what
- * lets them run with no human approval. Mutating operations are modeled as
- * blessed *actions*, not connectors, and run behind the approval gate.
+ * Hazard class for a connector. Lane 1 connectors are always `read`: they exist
+ * precisely because they are mutation-incapable, which is what lets them run
+ * with no human approval. Mutating operations are modeled as blessed *actions*,
+ * not connectors, and run behind the approval gate.
  */
-export type ConnectorEffect = "read";
+export type ConnectorHazard = "read";
 
-/** Hazard class of any capability (connector or action). */
-export type CapabilityEffect = "read" | "mutate";
+/**
+ * Hazard class of any capability, the honest description of what it can do and
+ * therefore how it must be gated:
+ * - `read`: no side effects, runs with no approval.
+ * - `write`: a known, human-declared mutation, runs behind one human approval.
+ * - `unknown`: arbitrary code whose effect cannot be established from a trusted
+ *   declaration (a delegated workload). A human must review the code before it
+ *   runs; it is never auto-run and is never labeled a "mutation".
+ */
+export type Hazard = "read" | "write" | "unknown";
 
 /**
  * Whether a capability is a built-in connector, a customer-authored action,
@@ -42,8 +51,8 @@ export interface Connector<Args = unknown, Result = unknown> {
   readonly name: string;
   /** One-line description for catalogs and the agent. */
   readonly description: string;
-  /** Always `read`: see {@link ConnectorEffect}. */
-  readonly effect: ConnectorEffect;
+  /** Always `read`: see {@link ConnectorHazard}. */
+  readonly hazard: ConnectorHazard;
   /**
    * Which environment-config family this connector needs (e.g. `firestore`).
    * A built-in connector is registered for a project only when at least one
@@ -81,9 +90,11 @@ export function connectorAvailableFor(
 export interface RegisteredCapability {
   readonly name: string;
   readonly description: string;
-  readonly effect: CapabilityEffect;
+  readonly hazard: Hazard;
   readonly kind: CapabilityKind;
   readonly params: z.ZodType;
+  /** The result schema, when the capability declares one (actions do). */
+  readonly output?: z.ZodType;
   run(args: unknown, ctx: ConnectorContext): Promise<unknown>;
 }
 
@@ -158,7 +169,7 @@ export class ConnectorRegistry {
     this.add({
       name: connector.name,
       description: connector.description,
-      effect: connector.effect,
+      hazard: connector.hazard,
       kind: "connector",
       params: connector.params,
       run: (args, ctx) => connector.run(args, ctx),
@@ -174,7 +185,7 @@ export class ConnectorRegistry {
   /**
    * Register a pre-built capability directly. Used for capabilities that are
    * neither a read-only `Connector` nor a folder-loaded action, e.g. the
-   * `workload.execute` executor, whose `effect` is `mutate` and whose `run`
+   * `workload.execute` executor, whose `hazard` is `unknown` and whose `run`
    * bridges into a sandbox backend.
    */
   public registerCapability(capability: RegisteredCapability): void {
@@ -191,9 +202,10 @@ export class ConnectorRegistry {
     this.add({
       name: id,
       description: action.description,
-      effect: action.effect ?? "mutate",
+      hazard: action.hazard ?? "write",
       kind: "action",
       params: action.input,
+      output: action.output,
       run: (args, ctx) =>
         Promise.resolve(
           action.run({

package/src/connectors/firestore.ts

@@ -100,7 +100,7 @@ const firestoreQuery: Connector<z.infer<typeof queryParams>, unknown> = {
   name: "firestore.query",
   description:
     "Read documents from a Firestore collection with optional where filters, ordering, and a limit. Returns at most `limit` documents (a capped page for inspection); do NOT use it to count or total; use firestore.count for that. Read-only.",
-  effect: "read",
+  hazard: "read",
   configKey: "firestore",
   params: queryParams,
   async run(args, ctx) {
@@ -133,7 +133,7 @@ const firestoreGet: Connector<z.infer<typeof getParams>, unknown> = {
   name: "firestore.get",
   description:
     "Read a single Firestore document by collection and id. Read-only.",
-  effect: "read",
+  hazard: "read",
   configKey: "firestore",
   params: getParams,
   async run(args, ctx) {
@@ -156,7 +156,7 @@ const firestoreCount: Connector<z.infer<typeof countParams>, number> = {
   name: "firestore.count",
   description:
     "Count documents in a Firestore collection (optionally filtered) using a server-side aggregation. It counts EVERY matching document, so it is the correct, exact tool for any 'how many' / total question. For 'how many <record>s', count the <record> collection (e.g. users → the \"users\" collection) with NO filter unless a subset is explicitly asked for; if unsure of the exact collection name, call firestore.listCollections first. Read-only.",
-  effect: "read",
+  hazard: "read",
   configKey: "firestore",
   params: countParams,
   async run(args, ctx) {
@@ -172,7 +172,7 @@ const listCollections: Connector<Record<string, never>, string[]> = {
   name: "firestore.listCollections",
   description:
     "List the top-level Firestore collection ids. Call this FIRST to ground yourself whenever you are not certain which collection holds the kind of record the question is about, then count/query that collection. Map the record asked about (a 'user', an 'order', a 'workspace') to its collection. The name of an organization, product, team, or environment is NEVER a collection: it only identifies whose system you are querying, so never treat it as a collection, id, or filter. Read-only.",
-  effect: "read",
+  hazard: "read",
   configKey: "firestore",
   params: z.object({}),
   async run(_args, ctx) {

package/src/index.ts

@@ -22,7 +22,7 @@ import type {
 
 export type {
   Action,
-  ActionEffect,
+  ActionHazard,
   ActionLogger,
   ActionRunContext,
   LoadedAction,
@@ -62,12 +62,12 @@ export {
   RunnerClient,
 } from "./connect.js";
 export type {
-  CapabilityEffect,
   CapabilityKind,
   Connector,
   ConnectorContext,
-  ConnectorEffect,
+  ConnectorHazard,
   DispatchResult,
+  Hazard,
   RegisteredCapability,
   SecretSource,
 } from "./connector.js";

package/src/workload/capability.ts

@@ -21,13 +21,15 @@ const WORKLOAD_DESCRIPTION =
   "Run a short program you author, in an isolated sandbox on the runner host, " +
   "when no other connector or action covers the task. Use this for arbitrary " +
   "computation and multi-step work: parsing files, reconciling systems, batch " +
-  "operations, calling an API no connector exposes. Provide `files` (source, " +
-  "at least the entrypoint; include a package.json to use npm libraries), " +
-  "`entrypoint` (the file to run; .ts runs under tsx), `secrets` (keys of the " +
-  "credentials the code needs, injected as env vars), and set `egress: true` " +
-  "to allow network access or dependency installs. It ALWAYS pauses for human " +
-  "review of the exact code before running, so propose the workload directly " +
-  "rather than asking the user for permission first. Read its stdout for the result.";
+  "operations, calling an API no connector exposes. Provide `title` (a short " +
+  'human-readable label for what the program does, e.g. "Credit top 10 active ' +
+  'users $5", shown to the human reviewer), `files` (source, at least the ' +
+  "entrypoint; include a package.json to use npm libraries), `entrypoint` (the " +
+  "file to run; .ts runs under tsx), `secrets` (keys of the credentials the " +
+  "code needs, injected as env vars), and set `egress: true` to allow network " +
+  "access or dependency installs. It ALWAYS pauses for a human to review the " +
+  "exact code before running, so propose the workload directly rather than " +
+  "asking the user for permission first. Read its stdout for the result.";
 
 /** Build the container backend the runner uses to execute workloads. */
 export function createSandboxBackend(config: SandboxConfig): SandboxBackend {
@@ -72,10 +74,11 @@ export interface WorkloadCapabilityOptions {
 /**
  * The `workload.execute` capability: validate the spec, resolve exactly the
  * requested credentials, clamp the limits, and run it in the sandbox backend.
- * It is `mutate` unconditionally, so the control plane always routes it through
- * human approval, the trust transition that turns agent-authored code into
- * trusted-for-one-run code. The full spec (including the source) is the
- * approved artifact; its digest is returned for audit.
+ * Its hazard is `unknown` (not `write`): its effect can't be established from a
+ * trusted declaration, only from the code itself, so the control plane always
+ * routes it through human *code* review, the trust transition that turns
+ * agent-authored code into trusted-for-one-run code. The full spec (including
+ * the source) is the approved artifact; its digest is returned for audit.
  */
 export function createWorkloadCapability(
   backend: SandboxBackend,
@@ -85,7 +88,7 @@ export function createWorkloadCapability(
   return {
     name: WORKLOAD_CAPABILITY_NAME,
     description: WORKLOAD_DESCRIPTION,
-    effect: "mutate",
+    hazard: "unknown",
     kind: "workload",
     params: workloadSpecSchema,
     run: async (rawArgs: unknown, ctx: ConnectorContext) => {

package/src/workload/container-backend.ts

@@ -53,14 +53,16 @@ function shellSingleQuote(value: string): string {
 /**
  * The in-container command. `.ts`/`.tsx` entrypoints run under `tsx`, others
  * under `node`. When `install` is set, dependencies are installed first (this
- * requires network egress). `exec` replaces the shell so signals reach the
- * process directly for prompt timeout kills.
+ * requires network egress); its noisy output is redirected to stderr so it
+ * never contaminates the workload's stdout, which is the channel the result is
+ * read from. `exec` replaces the shell so signals reach the process directly
+ * for prompt timeout kills.
  */
 export function buildRunScript(entrypoint: string, install: boolean): string {
   const runner = /\.tsx?$/.test(entrypoint) ? "tsx" : "node";
   const run = `exec ${runner} ${shellSingleQuote(entrypoint)}`;
   if (!install) return run;
-  return `npm install --omit=dev --no-audit --no-fund && ${run}`;
+  return `npm install --omit=dev --no-audit --no-fund >&2 && ${run}`;
 }
 
 export interface ContainerArgsParams {

package/src/workload/types.ts

@@ -35,6 +35,13 @@ export type WorkloadLimits = z.infer<typeof workloadLimitsSchema>;
  * may use, whether it may reach the network, and its resource envelope.
  */
 export const workloadSpecSchema = z.object({
+  /**
+   * A short, human-readable label for what the program does (e.g. "Credit top
+   * 10 active users $5"). Shown to the human reviewer on the approval card so
+   * they see the intent before reading the code. Purely descriptive: it is not
+   * part of the artifact digest, since it does not affect what executes.
+   */
+  title: z.string().optional(),
   /** Source files of the program (at least the entrypoint). */
   files: z.array(workloadFileSchema).min(1),
   /** Which file to run; must be one of `files`, a safe relative path. */