Runtime SDK

pnpm add github:Company-Runtime/runtime-sdk#<commit>

// package.json
{ "pnpm": { "onlyBuiltDependencies": ["@runtime-protocol/sdk"] } }

import {
  createRuntime,
  EnvCredentialBroker,
  GrantAuthority,
  verifyReceipt,
} from "@runtime-protocol/sdk";
import { createReferenceProvider } from "@runtime-protocol/sdk/reference";

const runtime = createRuntime({
  providers: [createReferenceProvider()],
  authority: new GrantAuthority([
    {
      id: "support",
      authority: "authority://company/support-manager",
      subjects: ["identity://agent/support-agent"],
      capabilities: ["communication.send"],
    },
  ]),
  // The key lives in RUNTIME_SECRET_ORGANIZATION_PROVIDERS_REFERENCE.
  credentials: {
    bindings: [
      { provider: "reference", ref: "secret://organization/providers/reference" },
    ],
    broker: new EnvCredentialBroker(),
  },
});

const outcome = await runtime.execute({
  capability: "communication.send",
  profile: "email",
  traits: { required: ["delivery_receipt"] },
  actor: "identity://agent/support-agent",
  input: {
    recipients: ["identity://customer/981"],
    subject: "Account update",
    content: "Your account has been updated.",
  },
  evidence: { require: ["execution", "delivery"] },
});

// "completed" — only because execution and delivery were proven
outcome.execution.state;
verifyReceipt(outcome.receipt!); // true

import { defineProvider, ProviderFailure } from "@runtime-protocol/sdk";

export const provider = defineProvider({
  id: "acme-mail",
  capabilities: [
    {
      capability: "communication.send",
      profiles: ["email"],
      traits: ["delivery_receipt", "idempotency"],
    },
  ],
  credentials: { required: true, accepts: ["organization"] },
  handlers: {
    "communication.send": async (input, ctx) => {
      const key = await ctx.credential(); // never log or return it
      const receipt = await sendThroughYourSystem(input, key, {
        idempotencyKey: ctx.idempotencyKey,
        signal: ctx.signal,
      });
      if (receipt.rejected) {
        throw new ProviderFailure("the recipient was rejected before sending");
      }
      return {
        output: {
          message: { ref: `resource://acme-mail/messages/${receipt.id}` },
          accepted_recipients: input.recipients,
        },
        evidence: [
          ctx.evidence.providerReceipt(["execution", "delivery"], {
            message_id: receipt.id,
          }),
        ],
      };
    },
  },
});

runtime-conformance provider ./dist/provider.js \
  --export provider --samples samples.yaml

# inside a clone of runtime-sdk
pnpm conformance

import { createHttpHandler, serve } from "@runtime-protocol/sdk/http";
import { createMcpServer, serveStdio } from "@runtime-protocol/sdk/mcp";

// HTTP: authenticate establishes who the caller may act as.
const handler = createHttpHandler(runtime, { authenticate });
const { url } = await serve(handler, { port: 8080 });

// MCP over stdio, for one session actor.
const actor = { ref: "identity://agent/support-agent" };
await serveStdio(createMcpServer(runtime, { actor }));