@polycore/runner 0.4.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycore/runner",
-  "version": "0.4.0",
+  "version": "1.0.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.4.0"
+    "@polycore/protocol": "^1.0.0"
   },
   "devDependencies": {
     "@types/node": "25.6.2",

package/src/action.ts

@@ -3,20 +3,20 @@ import type { z } from "zod";
 /**
  * Blessed **actions** are the second execution lane: durable, customer-authored
  * operations (e.g. "customer 360", "refund user") that live in the customer's
- * own repo and are loaded by the runner. Unlike connectors — generic,
- * read-only transports that ship inside the runner — an action is a named,
+ * own repo and are loaded by the runner. Unlike connectors (generic,
+ * read-only transports that ship inside the runner), an action is a named,
  * parameterized unit of work with its own input/output contract.
  *
- * This is the same authoring shape as the desktop SDK's `defineAction`, minus
- * the UI/page concern: a Slack/agent caller consumes the structured `output`,
- * not a React page. An action reaches into the customer's own backend (their
- * Firestore, Stripe, internal APIs) using `secrets` the runner resolves from
- * its environment — the credential never leaves the runner's host.
+ * An action is a headless RPC with no UI/page concern: a Slack/agent/web caller
+ * consumes the structured `output`, not a rendered page. It reaches into the
+ * customer's own backend (their Firestore, Stripe, internal APIs) using
+ * `secrets` the runner resolves from its environment; the credential never
+ * leaves the runner's host.
  */
 
 export type ActionHazard = "read" | "write";
 
-/** Human-facing progress sink, mirroring the desktop SDK's `ctx.log`. */
+/** Human-facing progress sink for an action's `run` (info/warn/error/success). */
 export interface ActionLogger {
   info(message: string): void;
   warn(message: string): void;
@@ -39,7 +39,7 @@ export interface Action<Input = unknown, Output = unknown> {
   readonly description: string;
   readonly tags?: readonly string[];
   /**
-   * Hazard class. Defaults to `write` — 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.
    */

package/src/connect.ts

@@ -26,6 +26,9 @@ export function describeConnectors(
     hazard: capability.hazard,
     kind: capability.kind,
     params: z.toJSONSchema(capability.params),
+    ...(capability.output === undefined
+      ? {}
+      : { result: z.toJSONSchema(capability.output) }),
   }));
 }
 

package/src/connector.ts

@@ -93,6 +93,8 @@ export interface RegisteredCapability {
   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>;
 }
 
@@ -203,6 +205,7 @@ export class ConnectorRegistry {
       hazard: action.hazard ?? "write",
       kind: "action",
       params: action.input,
+      output: action.output,
       run: (args, ctx) =>
         Promise.resolve(
           action.run({

package/src/index.ts

@@ -113,7 +113,7 @@ export {
 // The pinned Zod, re-exported so action authors share the runner's exact
 // instance, schemas must be introspectable by the runner's `z.toJSONSchema`.
 // Authors import `{ defineAction, z }` from "@polycore/runner", never from a
-// desktop package or a second `zod` copy.
+// second `zod` copy.
 export { z } from "zod";
 
 /** All built-in (Lane 1) connectors; SQL/HTTP families register here as they land. */
@@ -174,9 +174,9 @@ export const ACTIONS_DIRNAME = "actions";
  * file's directory (`baseDir`): a project's actions live in `actions/<slug>/`,
  * and when the runner serves a single project they may live directly in
  * `actions/`. Returns `undefined` when neither exists (a project with no
- * actions, or an env-driven config with no file directory) — the runner then
+ * actions, or an env-driven config with no file directory); the runner then
  * serves only the built-in connectors. There is no `actionsDir` config field:
- * the layout is a fixed convention, exactly like the desktop `src/actions/`.
+ * the layout is a fixed convention (`actions/<slug>/`).
  */
 export function resolveActionsDir(
   baseDir: string,
@@ -198,7 +198,7 @@ export function resolveActionsDir(
  *
  * `actionsBaseDir` is the config file's directory; actions are discovered from
  * the `actions/` convention under it (see {@link resolveActionsDir}). Omit it
- * for an env-driven config with no file location — the runner then serves only
+ * for an env-driven config with no file location; the runner then serves only
  * the built-in connectors.
  */
 export async function buildProjectRegistries(

package/src/load-actions.ts

@@ -13,8 +13,7 @@ import type { Action, LoadedAction } from "./action.js";
  * is recursed into.
  *
  * Modules are loaded via tsx's programmatic importer so the runner can load
- * raw `.ts` regardless of how its own process was started, exactly like the
- * desktop runtime's loader.
+ * raw `.ts` regardless of how its own process was started.
  */
 export async function loadActions(dir: string): Promise<LoadedAction[]> {
   const loaded: LoadedAction[] = [];