@xeonr/runner-sdk

Minimal SDK for upl-im pipeline JS steps. Step authors import defineStep to wrap a handler that runs inside the JS runner pod and talks to the side-car over the pod's /work/upl.sock Unix socket.

import { defineStep } from "@xeonr/runner-sdk";

export default defineStep(async (ctx) => {
  const source = ctx.inputBlob("source");
  const res = await fetch(source.url);
  const bytes = new Uint8Array(await res.arrayBuffer());

  // KV: lands as UploadMetadataKV on the upload
  await ctx.outputKV("dimensions.width", "1920");

  // Blob: lands as UploadMetadata, stored in the storage bucket
  await ctx.outputBlob("common:thumbnail_light", bytes, "image/png");

  ctx.log.info("done", { bytes: bytes.byteLength });
});

The runner image entrypoint awaits the returned function. Errors are forwarded to CompleteStep with userExitCode=1 so the coordinator sees the step as failed.

Environment

The side-car sets these in the pod env; the SDK reads them on init:

| Var | Purpose | | ------------------------- | ---------------------------------------- | | UPL_RUN_ID | PipelineRun id | | UPL_STEP_ID | PipelineStep id | | UPL_SIDECAR_SOCKET | Unix socket path (default /work/upl.sock) | | UPL_INPUTS_PATH | Resolved inputs JSON (default /work/inputs.json) |

UPL_INTERNAL_TOKEN + UPL_COORDINATOR_ENDPOINT are side-car-only — user code never sees them.

Wire protocol

The SDK uses Connect-RPC's JSON binding over HTTP/1.1 against the Unix socket. No proto codegen at install time — request bodies are JSON objects matching uplim.workflow.v1.PipelineRunnerService message shapes. Adding fields server-side is non-breaking as long as the JSON field names stay stable.

Limitations (v1)

• ctx.outputLocal calls SetStepLocal which returns Unimplemented on the coordinator until the StepRun.local_outputs_json migration lands. Use ctx.outputKV with hidden_from_users=true on the key registration as a workaround.
• Number inputs to outputKV are serialised as strings — register the key with value_type=STRING and parse on read.
• Logs are flushed per-call (no batching). Will batch when the side-car exposes the AppendLogs stream end-to-end.