@nullplatform/plugin 0.0.3 → 0.0.4-alpha.2

package/README.md

@@ -8,7 +8,9 @@
     <br>
 </h2>
 
-TypeScript SDK for building nullplatform plugins. Handles gRPC transport (HashiCorp go-plugin protocol), action routing, `--describe`, and `--publish`.
+TypeScript SDK for building nullplatform plugins. Handles transport (gRPC
+go-plugin **and** subprocess-exec), action routing, action lifecycle reporting,
+`--describe`, and `--publish`.
 
 ## Install
 
@@ -16,6 +18,17 @@ TypeScript SDK for building nullplatform plugins. Handles gRPC transport (HashiC
 bun add @nullplatform/plugin
 ```
 
+## Layers
+
+The SDK is layered so the stable core is insulated from today's rough platform
+APIs:
+
+- **base** — the plugin runtime, transport (gRPC + subprocess-exec), and the
+  action-lifecycle *protocol*. Stable.
+- **compat** (`src/compat/`) — temporary shims for current APIs: token exchange,
+  action `PATCH` shapes. Each is deletable in isolation once the real API lands.
+- **goal layers** — `defineScope` today; `defineService`, `defineHook` next.
+
 ## Usage
 
 ### Scope plugin
@@ -36,18 +49,51 @@ defineScope({
     },
   },
 
+  // Optional — how the platform routes actions to your worker. Defaults to
+  // selector { package: <name> } and entrypoint /app/packages/<name>/entrypoint.
+  agent: {
+    selector: { package: "kubernetes-k3d" },
+  },
+
   actions: {
     "create-scope": {
       input: { type: "object" },
       handler: async (notification, emit) => {
+        emit({ stdout: "Provisioning…" });  // live message on the action + worker logs
         // provision infrastructure
-        return { domain: "app.k3d.local" };
+        return { domain: "app.k3d.local" };  // becomes the action results
       },
     },
   },
 });
 ```
 
+#### Actions
+
+`handler` is a plain `async (notification, emit) => result` (or a workflow
+chain). The SDK reports the action lifecycle automatically: `in_progress` on
+start, `success` with your returned object, or `failed` on throw. `emit({ stdout
+})` streams a live message onto the action in the UI.
+
+Well-known action slugs get their metadata (name, type, retryable, lifecycle)
+for free — `create-scope`, `delete-scope`, `update-scope`, `start-initial`,
+`start-blue-green`, `switch-traffic`, `finalize-blue-green`,
+`rollback-deployment`, `delete-deployment`, `diagnose-scope`,
+`diagnose-deployment`, `kill-instances`, `restart-pods`, `pause-autoscaling`,
+`resume-autoscaling`, `set-desired-instance-count`. For a **custom** action, use
+any slug and declare `name`/`type` inline:
+
+```ts
+"say-hello": { name: "Say Hello", type: "custom", input, handler },
+```
+
+#### Transport
+
+Agents run the compiled plugin directly (subprocess-exec): the action arrives in
+`NP_ACTION_CONTEXT`, the plugin runs it, reports status, prints the result, and
+exits. The gRPC go-plugin server is also supported for hosts that use it. You
+write handlers; the SDK picks the transport.
+
 ### Simple plugin (custom command)
 
 ```typescript
@@ -74,12 +120,17 @@ createPlugin({
 
 ## CLI integration
 
-Plugins are scaffolded with `np plugin init` and managed via mise tasks:
+Packages are scaffolded and driven with the `np package` commands, which are
+thin wrappers over the template's own tasks:
 
 ```bash
-mise run dev          # local dev with hot reload
-mise run dev:agent    # dev with np-agent attached
-mise run test         # run tests
-mise run build        # compile to standalone binary
-mise run publish      # publish to platform
+np package init       # scaffold from a git template
+np package dev        # local dev UI + hot reload   (→ mise/bun run dev)
+np package test       # run tests                   (→ mise/bun run test)
+np package build --image   # build the worker image
+np package run        # run the worker as a real local agent (docker)
+np package publish    # register on the platform (specs + channel + artifact)
 ```
+
+`publish` reads the manifest from `--describe`, so the SDK owns the manifest
+shape and the CLI stays decoupled from it. See the CLI's `docs/packages.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullplatform/plugin",
-  "version": "0.0.3",
+  "version": "0.0.4-alpha.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -9,11 +9,14 @@
     "./schema": "./src/schema.ts",
     "./scope": "./src/scope/index.ts",
     "./testing": "./src/testing/index.ts",
-    "./workflow": "./src/workflow.ts"
+    "./workflow": "./src/workflow.ts",
+    "./service": "./src/service/index.ts",
+    "./platform": "./src/platform/index.ts"
   },
   "dependencies": {
     "@grpc/grpc-js": "^1.13.0",
     "@grpc/proto-loader": "^0.7.0",
+    "config": "^4.4.2",
     "yaml": "^2.7.0"
   },
   "files": [
@@ -46,6 +49,7 @@
   },
   "devDependencies": {
     "@types/bun": "^1.2.0",
+    "@types/config": "^4.4.0",
     "json-schema-to-ts": "^3.1.1"
   }
 }

package/src/api.ts

@@ -14,13 +14,15 @@
 
 // ─── Configuration ───────────────────────────────────────────────────
 
+import { cfg } from "./config";
+
 const TIMEOUT_MS = 30_000;
 
 function getConfig() {
-  const apiUrl = process.env.NP_API_URL ?? "https://api.nullplatform.com";
-  const apiKey = process.env.NULLPLATFORM_APIKEY ?? "";
+  const apiUrl = cfg.apiUrl();
+  const apiKey = cfg.apiKey();
   if (!apiKey) {
-    throw new Error("NULLPLATFORM_APIKEY environment variable is not set");
+    throw new Error("NP_API_KEY is not set");
   }
   return { apiUrl, apiKey };
 }

package/src/compat/index.ts

@@ -0,0 +1,14 @@
+/**
+ * COMPAT LAYER — temporary shims for today's platform APIs.
+ *
+ * Anything in here exists only because a platform API is missing or awkward
+ * right now. Each shim should be deletable in isolation once the real API
+ * lands. The stable base + goal layers import from here; nothing here should
+ * depend on them.
+ */
+export {
+  patchActionStatus,
+  patchActionMessages,
+  type ActionStatus,
+  type ActionMessage,
+} from "./lifecycle";

package/src/compat/lifecycle.ts

@@ -0,0 +1,84 @@
+/**
+ * COMPAT LAYER — temporary. Delete as the platform APIs improve.
+ *
+ * Action lifecycle management, working around today's API shapes:
+ *   - PATCH /service/{serviceId}/action/{actionId} { status, results } for
+ *     in_progress / success / failed (no dedicated action-status endpoint yet).
+ *   - The API expects a Bearer *token*, so NP_API_KEY is exchanged for
+ *     an access token (POST /token) and cached (no direct api-key auth yet).
+ *
+ * Everything here is a shim for a rough edge. When the platform exposes a
+ * first-class action-lifecycle API, this whole file goes away and the base
+ * layer talks to it directly. Keep base-layer code OUT of here.
+ */
+
+import { cfg } from "../config";
+
+const API_URL = () => cfg.apiUrl();
+const API_KEY = () => cfg.apiKey();
+
+let cachedToken: string | undefined;
+
+async function getToken(): Promise<string> {
+  if (cachedToken) return cachedToken;
+  const res = await fetch(`${API_URL()}/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ apikey: API_KEY() }),
+  });
+  if (!res.ok) throw new Error(`Token exchange failed: ${res.status} ${res.statusText}`);
+  const data = (await res.json()) as { access_token?: string };
+  if (!data.access_token) throw new Error("Token exchange returned no access_token");
+  cachedToken = data.access_token;
+  return cachedToken;
+}
+
+export type ActionStatus = "in_progress" | "success" | "failed";
+export interface ActionMessage {
+  level: "info" | "warning" | "error";
+  message: string;
+}
+
+// patchAction PATCHes the action with any of status / results / messages. It's
+// the single entry point for reporting; status/messages helpers wrap it.
+async function patchAction(serviceId: string, actionId: string, body: Record<string, unknown>): Promise<void> {
+  if (!API_KEY()) return; // skip lifecycle if no API key (local dev / testing)
+  if (!serviceId || !actionId) return;
+
+  const token = await getToken();
+  const res = await fetch(`${API_URL()}/service/${serviceId}/action/${actionId}`, {
+    method: "PATCH",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Action PATCH failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : ""}`);
+  }
+}
+
+export async function patchActionStatus(
+  serviceId: string,
+  actionId: string,
+  status: ActionStatus,
+  results?: Record<string, unknown>,
+): Promise<void> {
+  const body: Record<string, unknown> = { status };
+  if (results) body.results = results;
+  return patchAction(serviceId, actionId, body);
+}
+
+// patchActionMessages appends log lines to the action (what shows in the UI as
+// the action runs) — the SDK equivalent of `np service-action exec --live-report`.
+export async function patchActionMessages(
+  serviceId: string,
+  actionId: string,
+  messages: ActionMessage[],
+): Promise<void> {
+  if (messages.length === 0) return;
+  return patchAction(serviceId, actionId, { messages });
+}

package/src/config.ts

@@ -0,0 +1,55 @@
+/**
+ * Central configuration — the ONE place the SDK reads environment.
+ *
+ * Values come from node-config (a package's `config/` dir: `default.json` for
+ * defaults + `custom-environment-variables.json` mapping env vars → keys), which
+ * is the single declarative place every env var is documented. If a package
+ * ships no config/ (or a key isn't mapped), we fall back to the raw env var and
+ * then a built-in default — so the SDK works with or without node-config.
+ *
+ * Nothing else in the SDK touches `process.env`. Import { cfg } from here.
+ */
+
+import config from "config";
+
+// read resolves a value in priority order: node-config → raw env var → default.
+// This module is the only place `process.env` is read.
+function read(key: string, envVar: string, fallback = ""): string {
+  try {
+    if (config.has(key)) {
+      const v = config.get(key);
+      if (v != null && v !== "") return String(v);
+    }
+  } catch {
+    // node-config not configured for this process (no config/ dir) — fall through.
+  }
+  return process.env[envVar] ?? fallback;
+}
+
+export const cfg = {
+  /** Platform API base URL. env: NP_API_URL */
+  apiUrl: () => read("api.url", "NP_API_URL", "https://api.nullplatform.com"),
+
+  /** Platform API key. env: NP_API_KEY */
+  apiKey: () => read("api.key", "NP_API_KEY"),
+
+  /** Executions/streaming API URL. env: NP_EXECUTIONS_API_URL */
+  executionsApiUrl: () => read("api.executionsUrl", "NP_EXECUTIONS_API_URL"),
+
+  /** Agent transport mode marker. env: NP_AGENT_PLUGIN */
+  agentMode: () => read("agent.mode", "NP_AGENT_PLUGIN"),
+
+  /**
+   * Execution mode: "dev" | "test" | "" (production/agent). Set explicitly by
+   * `np package dev` / `np package test`. When "dev" or "test" the SDK uses the
+   * in-memory platform client and NEVER touches the real API — even if an API
+   * key is present in the environment. env: NP_MODE
+   */
+  mode: () => read("mode", "NP_MODE"),
+
+  /** The action payload injected in subprocess-exec mode. env: NP_ACTION_CONTEXT */
+  actionContext: () => read("agent.actionContext", "NP_ACTION_CONTEXT"),
+
+  /** Path to a plugin manifest override. env: NP_PLUGIN_MANIFEST */
+  pluginManifest: () => read("plugin.manifest", "NP_PLUGIN_MANIFEST"),
+} as const;

package/src/internal/grpc-server.ts

@@ -22,11 +22,13 @@
 
 import * as grpc from "@grpc/grpc-js";
 import * as protoLoader from "@grpc/proto-loader";
-import { unlinkSync } from "fs";
+import { unlinkSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
-import { join, resolve, dirname } from "path";
-import { fileURLToPath } from "url";
+import { join } from "path";
 import type { PluginHandler, ExecuteRequest, PluginManifest } from "../types";
+// Embed the proto as text so it survives `bun build --compile` (a compiled
+// binary has no plugin.proto on disk next to the source). Works from source too.
+import protoSource from "./plugin.proto" with { type: "text" };
 
 const MAGIC_COOKIE_KEY = "NP_AGENT_PLUGIN";
 const MAGIC_COOKIE_VALUE = "np-agent-v1";
@@ -158,12 +160,11 @@ export function startGrpcServer(
     handler,
     manifest,
   };
-  // Resolve proto path — import.meta.dir is Bun-only; fall back to
-  // import.meta.url (standard ESM) for Node.js compatibility.
-  const protoDir = typeof import.meta.dir === "string"
-    ? import.meta.dir
-    : dirname(fileURLToPath(import.meta.url));
-  const protoPath = resolve(protoDir, "plugin.proto");
+  // @grpc/proto-loader loads from a file path, so materialize the embedded proto
+  // text to a temp file. This is the one path that works both from source and
+  // from a compiled single-file binary.
+  const protoPath = join(tmpdir(), `np-plugin-${process.pid}.proto`);
+  writeFileSync(protoPath, protoSource);
   const packageDefinition = protoLoader.loadSync(protoPath, {
     keepCase: true,
     longs: String,

package/src/internal/manifest.ts

@@ -8,6 +8,7 @@
 import { readFileSync, existsSync } from "fs";
 import { resolve } from "path";
 import YAML from "yaml";
+import { cfg } from "../config";
 import type { PluginManifest } from "../types";
 
 let registeredManifest: PluginManifest | null = null;
@@ -18,14 +19,19 @@ export function registerManifest(manifest: PluginManifest): void {
 }
 
 export function loadManifest(): PluginManifest {
-  // If a manifest was registered in-memory (by defineScope), use it
+  // Two ways a plugin declares its manifest (name/version/command_types):
+  //   1. defineScope() registers it in-memory at import time — the common path;
+  //      scope plugins never need a plugin.yaml.
+  //   2. Raw createPlugin() plugins (no defineScope) fall back to a plugin.yaml
+  //      file on disk. Override its path with NP_PLUGIN_MANIFEST.
   if (registeredManifest) {
     return registeredManifest;
   }
 
+  const manifestOverride = cfg.pluginManifest();
   const manifestPath = resolve(
-    process.env.NP_PLUGIN_MANIFEST || process.cwd(),
-    process.env.NP_PLUGIN_MANIFEST ? "" : "plugin.yaml",
+    manifestOverride || process.cwd(),
+    manifestOverride ? "" : "plugin.yaml",
   );
 
   if (!existsSync(manifestPath)) {

package/src/platform/client.ts

@@ -0,0 +1,109 @@
+/**
+ * PlatformClient — the ONE port through which a plugin talks to the control
+ * plane. A handler never calls the platform API directly; the SDK injects a
+ * client and swaps the implementation by mode:
+ *
+ *   - HttpPlatformClient   real API calls (the dockerized agent / `np package run`)
+ *   - InMemoryPlatformClient   records calls, prints locally, never networks
+ *                              (`np package dev`, `np package test`)
+ *
+ * This is the pattern every comparable system converges on (Temporal activity
+ * context, Crossplane ExternalClient, Terraform provider client, go-plugin host
+ * services): local dev is isolated by construction, not by the accident of a
+ * missing credential.
+ */
+
+import { cfg } from "../config";
+import { patchActionStatus, patchActionMessages, type ActionStatus } from "../compat";
+
+export type { ActionStatus };
+export type LogStream = "stdout" | "stderr";
+
+export interface PlatformClient {
+  /** How this client is wired — "http" hits the real API, "memory" stays local. */
+  readonly mode: "http" | "memory";
+
+  /** Report an action lifecycle transition (in_progress → success/failed). */
+  transitionAction(
+    serviceId: string,
+    actionId: string,
+    status: ActionStatus,
+    results?: Record<string, unknown>,
+  ): Promise<void>;
+
+  /** Append a log line to the action (shows live in the UI as it runs). */
+  emitLog(serviceId: string, actionId: string, line: string, stream: LogStream): Promise<void>;
+}
+
+/** Real client: talks to the nullplatform API. Used by the agent / `np package run`. */
+export class HttpPlatformClient implements PlatformClient {
+  readonly mode = "http" as const;
+
+  async transitionAction(
+    serviceId: string,
+    actionId: string,
+    status: ActionStatus,
+    results?: Record<string, unknown>,
+  ): Promise<void> {
+    await patchActionStatus(serviceId, actionId, status, results);
+  }
+
+  async emitLog(serviceId: string, actionId: string, line: string, stream: LogStream): Promise<void> {
+    const message = line.trimEnd();
+    if (!message) return;
+    // Local visibility: logs go to STDERR (stdout is reserved for the result
+    // JSON the agent parses). This is the standard data-on-stdout /
+    // logs-on-stderr split. The platform UI gets the same line as a properly
+    // leveled action message below.
+    process.stderr.write(message + "\n");
+    await patchActionMessages(serviceId, actionId, [
+      { level: stream === "stderr" ? "error" : "info", message },
+    ]);
+  }
+}
+
+/**
+ * Fake client: records every call and echoes logs to the terminal, but makes NO
+ * network calls. Used for `np package dev` and tests so a plugin runs fully
+ * local. Exposed calls are inspectable via `.calls` for assertions.
+ */
+export class InMemoryPlatformClient implements PlatformClient {
+  readonly mode = "memory" as const;
+
+  readonly calls: Array<
+    | { kind: "transition"; actionId: string; status: ActionStatus; results?: Record<string, unknown> }
+    | { kind: "log"; actionId: string; line: string; stream: LogStream }
+  > = [];
+
+  constructor(private readonly opts: { echo?: boolean } = { echo: true }) {}
+
+  async transitionAction(
+    _serviceId: string,
+    actionId: string,
+    status: ActionStatus,
+    results?: Record<string, unknown>,
+  ): Promise<void> {
+    this.calls.push({ kind: "transition", actionId, status, results });
+    if (this.opts.echo) process.stderr.write(`  • action ${status}\n`);
+  }
+
+  async emitLog(_serviceId: string, actionId: string, line: string, stream: LogStream): Promise<void> {
+    const message = line.trimEnd();
+    if (!message) return;
+    this.calls.push({ kind: "log", actionId, line: message, stream });
+    if (this.opts.echo) process.stderr.write(`  → ${message}\n`);
+  }
+}
+
+/**
+ * Pick the client for the current process. Explicit dev/test mode ALWAYS returns
+ * the in-memory fake — even when NP_API_KEY is set — so local runs can never
+ * mutate the real platform. Only a real agent run (no dev mode + a key present)
+ * gets the HTTP client.
+ */
+export function resolvePlatformClient(): PlatformClient {
+  const mode = cfg.mode();
+  if (mode === "dev" || mode === "test") return new InMemoryPlatformClient();
+  if (!cfg.apiKey()) return new InMemoryPlatformClient(); // no creds → stay local
+  return new HttpPlatformClient();
+}

package/src/platform/index.ts

@@ -0,0 +1,8 @@
+export {
+  type PlatformClient,
+  type ActionStatus,
+  type LogStream,
+  HttpPlatformClient,
+  InMemoryPlatformClient,
+  resolvePlatformClient,
+} from "./client";

package/src/scope/describe.ts

@@ -6,7 +6,7 @@
  */
 
 import { getActionDefaults } from "./actions";
-import type { ScopeDefinition } from "./index";
+import { resolveAgentConfig, type ScopeDefinition } from "./index";
 
 export function handleDescribe(definition: ScopeDefinition): void {
   const actionSpecs: Record<string, unknown> = {};
@@ -33,6 +33,9 @@ export function handleDescribe(definition: ScopeDefinition): void {
     schema: definition.schema,
     actions: actionSpecs,
     uiSchema: definition.uiSchema,
+    // Routing config with defaults resolved from the name, so the CLI applies
+    // exactly what the scope declares instead of re-deriving conventions.
+    agent: resolveAgentConfig(definition),
   };
 
   const cleaned = JSON.parse(JSON.stringify(output));

package/src/scope/index.ts

@@ -30,7 +30,8 @@ import { InMemoryEngine } from "@nullplatform/workflow-engine-in-memory";
 import { getActionDefaults } from "./actions";
 import { handleDescribe } from "./describe";
 import { handlePublish } from "./publish";
-import { patchActionStatus } from "./lifecycle";
+import { resolvePlatformClient } from "../platform";
+import { cfg } from "../config";
 import type { NpJSONSchema } from "../schema";
 
 // ─── Types ───────────────────────────────────────────────────────────
@@ -84,10 +85,35 @@ export interface ScopeDefinition {
   /** JSONForms UISchema for rendering the capabilities form. */
   uiSchema?: object;
 
+  /**
+   * How the platform routes actions to the worker. Optional — sensible defaults
+   * are derived from `name`, so most scopes never set this. Override only for a
+   * custom selector or a non-standard worker entrypoint.
+   */
+  agent?: ScopeAgentConfig;
+
   /** Actions: schema (input/output) + handler, keyed by action slug. */
   actions: Record<string, ActionDefinition>;
 }
 
+/** Agent routing config for a scope. See {@link ScopeDefinition.agent}. */
+export interface ScopeAgentConfig {
+  /** Selector tags an agent must carry to handle this scope. Default: `{ package: <name> }`. */
+  selector?: Record<string, string>;
+  /** Path the agent execs in the worker image. Default: `/app/packages/<name>/entrypoint`. */
+  entrypoint?: string;
+}
+
+/** Fill agent config defaults from the scope name (the package slug). */
+export function resolveAgentConfig(definition: ScopeDefinition): Required<ScopeAgentConfig> {
+  const slug = definition.name;
+  const selector = definition.agent?.selector;
+  return {
+    selector: selector && Object.keys(selector).length > 0 ? selector : { package: slug },
+    entrypoint: definition.agent?.entrypoint || `/app/packages/${slug}/entrypoint`,
+  };
+}
+
 // ─── Exec payload parsing ────────────────────────────────────────────
 // The platform only supports "exec" channel type today. np-agent reroutes
 // exec commands to this plugin when the channel config includes NP_PLUGIN=scope
@@ -178,6 +204,66 @@ export function defineScope(definition: ScopeDefinition): void {
     command_types: ["scope"],
   });
 
+  // Subprocess exec mode: agents that run this binary directly (no gRPC host)
+  // pass the action in the NP_ACTION_CONTEXT env var. Run the one action, report
+  // its lifecycle status, print the result, and exit.
+  const execCtx = cfg.actionContext();
+  if (execCtx && cfg.agentMode() !== "np-agent-v1") {
+    void (async () => {
+      const platform = resolvePlatformClient();
+      let out: ExecuteResult;
+      let serviceId = "";
+      let actionId = "";
+      let lifecycle = false;
+      try {
+        const raw = JSON.parse(execCtx);
+        const notification: Notification = raw.notification ?? raw;
+        serviceId = notification.service?.id ?? "";
+        actionId = notification.id ?? "";
+        // emit forwards handler output to the platform as action messages (shown
+        // live on the action). It routes through the injected client, so in dev
+        // it's recorded locally and never touches the API.
+        const emit = (o: { stdout?: string; stderr?: string }) => {
+          if (o?.stdout) void platform.emitLog(serviceId, actionId, o.stdout, "stdout").catch(() => {});
+          if (o?.stderr) void platform.emitLog(serviceId, actionId, o.stderr, "stderr").catch(() => {});
+        };
+        const actionSlug = resolveActionSlug(notification, notification.type ?? "");
+        const actionDef = definition.actions[actionSlug];
+        if (!actionDef) throw new Error(`Unknown action: ${actionSlug}`);
+        lifecycle = getActionDefaults(actionSlug).lifecycle;
+        if (lifecycle && actionId) {
+          await platform.transitionAction(serviceId, actionId, "in_progress").catch(() => {});
+        }
+        let data: unknown;
+        if (isWorkflowChain(actionDef.handler)) {
+          const observer = new StreamingExecutionObserver(emit, { apiUrl: cfg.executionsApiUrl() });
+          observer.emitPlan(actionDef.handler.toGraph());
+          const engine = new InMemoryEngine({ observer });
+          const wf = await actionDef.handler.run(notification, { engine, timeoutMs: 10 * 60 * 1000 });
+          if (wf.status !== "completed") throw new Error(wf.error?.message ?? `Workflow ${wf.status}`);
+          data = wf.output;
+        } else {
+          data = await actionDef.handler(notification, emit);
+        }
+        if (lifecycle && actionId) {
+          const results = data && typeof data === "object" ? (data as Record<string, unknown>) : undefined;
+          await platform.transitionAction(serviceId, actionId, "success", results).catch(() => {});
+        }
+        out = { success: true, data };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (lifecycle && actionId) {
+          await platform.transitionAction(serviceId, actionId, "failed", { error: message }).catch(() => {});
+        }
+        out = { success: false, error: message, errorCode: "EXECUTION_ERROR" };
+      }
+      process.stdout.write(JSON.stringify(out));
+      process.exit(out.success ? 0 : 1);
+    })();
+    return;
+  }
+
+  const platform = resolvePlatformClient();
   const plugin = createPlugin({
     async execute(req: ExecuteRequest): Promise<ExecuteResult> {
       // Handle both native "scope" and legacy "exec" command types
@@ -205,9 +291,10 @@ export function defineScope(definition: ScopeDefinition): void {
 
       const defaults = getActionDefaults(actionSlug);
       const actionId = notification.id;
+      const serviceId = notification.service?.id ?? "";
 
       if (defaults.lifecycle && actionId) {
-        await patchActionStatus(actionId, "in_progress").catch((err) => {
+        await platform.transitionAction(serviceId, actionId, "in_progress").catch((err) => {
           console.error(`[defineScope] Failed to patch action status: ${err.message}`);
         });
       }
@@ -218,7 +305,7 @@ export function defineScope(definition: ScopeDefinition): void {
         if (isWorkflowChain(actionDef.handler)) {
           // Workflow chain: emit plan, run with engine
           const observer = new StreamingExecutionObserver(req.emit, {
-            apiUrl: process.env.NP_EXECUTIONS_API_URL,
+            apiUrl: cfg.executionsApiUrl(),
           });
           observer.emitPlan(actionDef.handler.toGraph());
 
@@ -235,7 +322,8 @@ export function defineScope(definition: ScopeDefinition): void {
         }
 
         if (defaults.lifecycle && actionId) {
-          await patchActionStatus(actionId, "completed").catch((err) => {
+          const results = result && typeof result === "object" ? (result as Record<string, unknown>) : undefined;
+          await platform.transitionAction(serviceId, actionId, "success", results).catch((err) => {
             console.error(`[defineScope] Failed to patch action status: ${err.message}`);
           });
         }
@@ -245,7 +333,7 @@ export function defineScope(definition: ScopeDefinition): void {
         const message = error instanceof Error ? error.message : String(error);
 
         if (defaults.lifecycle && actionId) {
-          await patchActionStatus(actionId, "failed", message).catch((err) => {
+          await platform.transitionAction(serviceId, actionId, "failed", { error: message }).catch((err) => {
             console.error(`[defineScope] Failed to patch action status: ${err.message}`);
           });
         }

package/src/scope/publish.ts

@@ -15,6 +15,7 @@
 
 import { $ } from "bun";
 import { getActionDefaults } from "./actions";
+import { cfg } from "../config";
 import type { ScopeDefinition } from "./index";
 
 export async function handlePublish(definition: ScopeDefinition): Promise<void> {
@@ -161,7 +162,7 @@ export async function handlePublish(definition: ScopeDefinition): Promise<void>
   console.log(`  ${existingScopeType ? "↻" : "✓"} Scope type: ${scopeTypeId}`);
 
   // 4. Dev notification channel (upsert by description tag)
-  const apiKey = process.env.NP_API_KEY;
+  const apiKey = cfg.apiKey();
   if (!apiKey) {
     console.error("\n⚠ Skipping notification channel — NP_API_KEY not set");
     console.error("  Set it and re-run, or create the channel manually via the UI");

package/src/service/describe.ts

@@ -0,0 +1,43 @@
+/**
+ * --describe for a service package. Prints the manifest as JSON. The `kind:
+ * "service"` marker tells the CLI to register a dependency service_specification
+ * (with use_default_actions) instead of a scope + scope type.
+ */
+
+import { resolveAgentConfig } from "../scope";
+import type { ServiceDefinition } from "./index";
+
+export function handleServiceDescribe(definition: ServiceDefinition): void {
+  // Only CUSTOM actions are described — the platform generates create/update/
+  // delete when useDefaultActions is on, so we don't ship specs for them.
+  const defaultTypes = new Set(["create", "update", "delete"]);
+  const actionSpecs: Record<string, unknown> = {};
+  for (const [slug, action] of Object.entries(definition.actions)) {
+    if (definition.useDefaultActions !== false && defaultTypes.has(slug)) continue;
+    actionSpecs[slug] = {
+      name: action.name ?? slug,
+      type: action.type ?? "custom",
+      retryable: action.retryable ?? false,
+      lifecycle: true,
+      input: action.input,
+      output: action.output,
+    };
+  }
+
+  const output = {
+    kind: "service",
+    name: definition.name,
+    version: definition.version,
+    description: definition.description,
+    category: definition.category,
+    provider: definition.provider,
+    schema: definition.schema,
+    uiSchema: definition.uiSchema,
+    useDefaultActions: definition.useDefaultActions ?? true,
+    assignableTo: definition.assignableTo ?? "any",
+    actions: actionSpecs,
+    agent: resolveAgentConfig(definition as any),
+  };
+
+  console.log(JSON.stringify(JSON.parse(JSON.stringify(output)), null, 2));
+}

package/src/service/index.ts

@@ -0,0 +1,173 @@
+/**
+ * defineService() — define a self-describing SERVICE package.
+ *
+ * A service is an application *dependency* (a database, cache, queue, …), not a
+ * deployment target. It differs from a scope:
+ *   - the service_specification is `type: "dependency"` (no scope type),
+ *   - with `useDefaultActions` the platform auto-generates create/update/delete
+ *     action specs from the schema — you only write handlers, not specs,
+ *   - action slugs are dynamic (`create-<name>`), so handlers are keyed by the
+ *     action TYPE (create/update/delete) or a custom slug.
+ *
+ * The runtime (subprocess-exec + gRPC, lifecycle reporting) mirrors defineScope.
+ */
+
+import { createPlugin } from "../create-plugin";
+import type { ExecuteRequest, ExecuteResult } from "../types";
+import { registerManifest } from "../internal/manifest";
+import { StreamingExecutionObserver } from "../workflow";
+import { InMemoryEngine } from "@nullplatform/workflow-engine-in-memory";
+import { resolvePlatformClient } from "../platform";
+import { cfg } from "../config";
+import { resolveAgentConfig, type ScopeAgentConfig, type ActionDefinition, type Notification } from "../scope";
+import { handleServiceDescribe } from "./describe";
+import type { NpJSONSchema } from "../schema";
+
+export interface ServiceDefinition {
+  name: string;
+  version: string;
+  description?: string;
+  category?: string;
+  provider?: string;
+
+  /** JSON Schema for the service's attributes (its configurable properties). */
+  schema: NpJSONSchema;
+
+  /** JSONForms UISchema for the attributes form. */
+  uiSchema?: object;
+
+  /**
+   * Let the platform auto-generate create/update/delete action specs from the
+   * schema (default true). Set false to declare all action specs yourself.
+   */
+  useDefaultActions?: boolean;
+
+  /** Where the service can be assigned. Default "any". */
+  assignableTo?: "any" | "dimension" | "scope";
+
+  /** How the platform routes actions to the worker. Defaults from `name`. */
+  agent?: ScopeAgentConfig;
+
+  /**
+   * Handlers, keyed by action type (`create`/`update`/`delete`) for the default
+   * actions, and by slug for any custom action.
+   */
+  actions: Record<string, ActionDefinition>;
+}
+
+function isWorkflowChain(handler: unknown): handler is { run: Function; toGraph: Function } {
+  return !!handler && typeof (handler as any).run === "function" && typeof (handler as any).toGraph === "function";
+}
+
+// resolveServiceHandler maps a notification to a handler. Default actions arrive
+// with a dynamic slug (`create-<name>`) but a stable `type` (create/update/
+// delete), so we try: exact slug → action type → the type-prefixed slug.
+function resolveServiceHandler(def: ServiceDefinition, notification: Notification): { key: string; action?: ActionDefinition } {
+  const slug = notification.slug || notification.specification?.slug || "";
+  const type = String((notification as any).type ?? "");
+  if (slug && def.actions[slug]) return { key: slug, action: def.actions[slug] };
+  if (type && def.actions[type]) return { key: type, action: def.actions[type] };
+  // "create-postgres" → "create"
+  const prefix = slug.split("-")[0];
+  if (prefix && def.actions[prefix]) return { key: prefix, action: def.actions[prefix] };
+  return { key: slug || type };
+}
+
+export function defineService(definition: ServiceDefinition): void {
+  if (process.argv.includes("--describe")) {
+    handleServiceDescribe(definition);
+    process.exit(0);
+  }
+
+  registerManifest({
+    name: definition.name,
+    version: definition.version,
+    command_types: ["service"],
+  });
+
+  // Subprocess-exec mode (how the agent runs the worker): the action arrives in
+  // NP_ACTION_CONTEXT; run it, report lifecycle, print the result, exit.
+  const execCtx = cfg.actionContext();
+  if (execCtx && cfg.agentMode() !== "np-agent-v1") {
+    void (async () => {
+      const platform = resolvePlatformClient();
+      let out: ExecuteResult;
+      let serviceId = "";
+      let actionId = "";
+      try {
+        const raw = JSON.parse(execCtx);
+        const notification: Notification = raw.notification ?? raw;
+        serviceId = notification.service?.id ?? "";
+        actionId = notification.id ?? "";
+        const emit = (o: { stdout?: string; stderr?: string }) => {
+          if (o?.stdout) void platform.emitLog(serviceId, actionId, o.stdout, "stdout").catch(() => {});
+          if (o?.stderr) void platform.emitLog(serviceId, actionId, o.stderr, "stderr").catch(() => {});
+        };
+        const { key, action } = resolveServiceHandler(definition, notification);
+        if (!action) throw new Error(`Unknown service action: ${key}`);
+        if (actionId) await platform.transitionAction(serviceId, actionId, "in_progress").catch(() => {});
+        let data: unknown;
+        if (isWorkflowChain(action.handler)) {
+          const observer = new StreamingExecutionObserver(emit, { apiUrl: cfg.executionsApiUrl() });
+          observer.emitPlan((action.handler as any).toGraph());
+          const engine = new InMemoryEngine({ observer });
+          const wf = await (action.handler as any).run(notification, { engine, timeoutMs: 10 * 60 * 1000 });
+          if (wf.status !== "completed") throw new Error(wf.error?.message ?? `Workflow ${wf.status}`);
+          data = wf.output;
+        } else {
+          data = await (action.handler as any)(notification, emit);
+        }
+        if (actionId) {
+          const results = data && typeof data === "object" ? (data as Record<string, unknown>) : undefined;
+          await platform.transitionAction(serviceId, actionId, "success", results).catch(() => {});
+        }
+        out = { success: true, data };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (actionId) await platform.transitionAction(serviceId, actionId, "failed", { error: message }).catch(() => {});
+        out = { success: false, error: message, errorCode: "EXECUTION_ERROR" };
+      }
+      process.stdout.write(JSON.stringify(out));
+      process.exit(out.success ? 0 : 1);
+    })();
+    return;
+  }
+
+  // gRPC host path (dev / np-agent-v1).
+  const platform = resolvePlatformClient();
+  const plugin = createPlugin({
+    async execute(req: ExecuteRequest): Promise<ExecuteResult> {
+      let notification: Notification;
+      try {
+        const raw = JSON.parse(req.payload.toString("utf-8"));
+        notification = raw.notification ?? raw;
+      } catch {
+        return { success: false, error: "invalid payload", errorCode: "MISSING_CONTEXT" };
+      }
+      const { key, action } = resolveServiceHandler(definition, notification);
+      if (!action) return { success: false, error: `Unknown service action: ${key}`, errorCode: "UNKNOWN_ACTION" };
+      const actionId = notification.id;
+      const serviceId = notification.service?.id ?? "";
+      if (actionId) await platform.transitionAction(serviceId, actionId, "in_progress").catch(() => {});
+      try {
+        const result = await (action.handler as any)(notification, req.emit);
+        if (actionId) {
+          const results = result && typeof result === "object" ? (result as Record<string, unknown>) : undefined;
+          await platform.transitionAction(serviceId, actionId, "success", results).catch(() => {});
+        }
+        return { success: true, data: result };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (actionId) await platform.transitionAction(serviceId, actionId, "failed", { error: message }).catch(() => {});
+        return { success: false, error: message, errorCode: "EXECUTION_ERROR" };
+      }
+    },
+  });
+  plugin.start();
+}
+
+export { resolveAgentConfig };
+// Author-facing types: a service handler receives the action notification and an
+// `emit` callback. `ServiceActionInput` is the notification shape (aliased from
+// the shared Notification type) so action files read as service code.
+export type { Notification as ServiceActionInput, ActionDefinition, ScopeAgentConfig } from "../scope";

package/src/testing/plugin-client.ts

@@ -53,6 +53,10 @@ export async function startPluginProcess(
       ...process.env,
       ...opts?.env,
       NP_AGENT_PLUGIN: "np-agent-v1",
+      // This helper only ever runs a plugin for local dev/test (the real agent
+      // execs the binary directly). Force in-memory platform mode so a dev/test
+      // run can never hit the real API, even if NP_API_KEY is in the env.
+      NP_MODE: process.env.NP_MODE || "dev",
     },
     stdout: "pipe",
     stderr: "pipe",

package/src/scope/lifecycle.ts

@@ -1,39 +0,0 @@
-/**
- * Action lifecycle management.
- *
- * PATCHes service action status via the platform API.
- * Mirrors what `np service-action exec` does:
- *   - PATCH status: "in_progress" on start
- *   - PATCH status: "completed" or "failed" on end
- */
-
-const API_URL = () => process.env.NP_API_URL ?? "https://api.nullplatform.com";
-const API_KEY = () => process.env.NULLPLATFORM_APIKEY ?? "";
-
-export async function patchActionStatus(
-  actionId: string,
-  status: "in_progress" | "completed" | "failed",
-  error?: string,
-): Promise<void> {
-  const apiKey = API_KEY();
-  if (!apiKey) return; // skip lifecycle if no API key (local dev / testing)
-
-  const body: Record<string, unknown> = { status };
-  if (error) {
-    body.results = { error };
-  }
-
-  const res = await fetch(`${API_URL()}/service/action/${actionId}`, {
-    method: "PATCH",
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(body),
-  });
-
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error(`Lifecycle PATCH ${status} failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : ""}`);
-  }
-}