Introducing Unified Apps: one capability, every caller

Two files

Every call

1. Fused validates the input against the schema.
2. It runs execute on the Engine.
3. It adds provider credentials server-side as each operation is dispatched.
4. It validates the output and returns it.

Credentials never appear in the app's source or the caller's environment.

What it isn't

It isn't a workflow canvas and it isn't a normalized "unified API" schema. It's code you own, deployed as a versioned contract. A run doesn't depend on which caller started it or on how a model planned it.

1. Describe

With the CLI installed and signed in, describe the process in plain language:

fused-cli describe --name publish-release --bucket default \
  "Create a Unified App that publishes a GitHub release and announces it by email.
   Accept repository (owner/repo) and tag (vMAJOR.MINOR.PATCH).
   List the repository's releases; fail if the tag already exists, otherwise use the latest published release as the base.
   Search for pull requests merged into main since that release; fail if there are none.
   Build release notes grouped into Features, Fixes and Other using the feature and fix labels.
   Create the release on main with those notes.
   Then email the notes to releases@acme.dev with Resend.
   Return releaseUrl, pullRequests (count) and announcementId.
   Keep credentials in the default bucket."

describe finds GitHub and Resend in your workspace, or searches the Registry for them. It then selects the operations the process needs and drafts TypeScript against their contracts. You review the proposal (services, pinned versions, operations and source) before anything is applied. Once you confirm, it activates any missing services, deploys the app and saves the files to .fused/unified_app/.

If you'd rather write the files yourself, use plan and apply.

2. TypeScript

// .fused/unified_app/publish-release.ts
import { z } from "zod";
import { buildUnifiedApp } from "@fused/unified-app";
import { fused } from "@fused/operations";

// Only the provider fields this app relies on.
const releaseList = z.array(
  z.object({ tag_name: z.string(), draft: z.boolean(), published_at: z.string().nullable() }),
);
const mergedPRs = z.object({
  total_count: z.number(),
  items: z.array(
    z.object({ number: z.number(), title: z.string(), labels: z.array(z.object({ name: z.string() })) }),
  ),
});
type PullRequest = z.infer<typeof mergedPRs>["items"][number];

export default buildUnifiedApp({
  input: z.object({
    repository: z.string().regex(/^[\w.-]+\/[\w.-]+$/), // "acme/web"
    tag: z.string().regex(/^v\d+\.\d+\.\d+$/),           // "v2.4.0"
  }),
  output: z.object({
    releaseUrl: z.string().url(),
    pullRequests: z.number(),
    announcementId: z.string(),
  }),

  async execute({ input }) {
    const [owner, repo] = input.repository.split("/");

    // 1. Never publish the same tag twice; otherwise start from the last published release.
    const releases = releaseList.parse(await fused.github.reposListReleases({ owner, repo, per_page: 20 }));
    if (releases.some((r) => r.tag_name === input.tag)) {
      throw new Error(`${input.tag} has already been released`);
    }
    const previous = releases.find((r) => !r.draft && r.published_at !== null);
    const since = previous?.published_at ?? "1970-01-01T00:00:00Z";

    // 2. Everything merged into main since then. Fail loudly rather than publish partial notes.
    const prs = mergedPRs.parse(
      await fused.github.searchIssuesAndPullRequests({
        q: `repo:${input.repository} is:pr is:merged base:main merged:>${since}`,
        per_page: 100,
      }),
    );
    if (prs.total_count === 0) throw new Error(`Nothing merged since ${previous?.tag_name ?? "the first commit"}`);
    if (prs.total_count > prs.items.length) throw new Error("More than 100 pull requests; split the release");

    // 3. Same notes format for every release.
    const notes = releaseNotes(prs.items, previous?.tag_name);

    // 4. Create the release.
    const release = z.object({ html_url: z.string() }).parse(
      await fused.github.reposCreateRelease({
        owner, repo, tag_name: input.tag, target_commitish: "main", name: input.tag, body: notes,
      }),
    );

    // 5. Announce it only once the release exists.
    const announcementId = await announce(input.repository, input.tag, release.html_url, notes);

    return { releaseUrl: release.html_url, pullRequests: prs.total_count, announcementId };
  },
});

// The only part of the app that knows how announcements are delivered.
async function announce(repository: string, tag: string, url: string, notes: string): Promise<string> {
  const sent = z.object({ id: z.string() }).parse(
    await fused.resend.postEmails({
      from: "Acme Releases <releases@acme.dev>",
      to: "releases@acme.dev",
      subject: `${repository} ${tag} is out`,
      text: `${notes}\n\nFull release: ${url}`,
    }),
  );
  return sent.id;
}

function releaseNotes(prs: PullRequest[], previousTag?: string): string {
  const has = (pr: PullRequest, label: string) => pr.labels.some((l) => l.name === label);
  const section = (title: string, items: PullRequest[]) =>
    items.length ? [`## ${title}`, ...items.map((pr) => `- ${pr.title} (#${pr.number})`), ""] : [];

  return [
    ...section("Features", prs.filter((pr) => has(pr, "feature"))),
    ...section("Fixes", prs.filter((pr) => has(pr, "fix"))),
    ...section("Other", prs.filter((pr) => !has(pr, "feature") && !has(pr, "fix"))),
    previousTag ? `Changes since ${previousTag}.` : "",
  ].join("\n");
}

3. YAML

# .fused/unified_app/publish-release.yaml
apiVersion: fused/v1
kind: unified_app
name: publish-release
version: "1.0.0"
bucket: default
source_path: publish-release.ts
services:
  github:
    version: "v3"
    operations: [reposListReleases, searchIssuesAndPullRequests, reposCreateRelease]
  resend:
    version: "1.5.0"
    operations: [postEmails]

This is the app's entire permission surface: four operations across two services. The GitHub token in the bucket may be able to delete releases or push to branches, but the app can't, because those operations aren't listed.

4. Credentials

describe can enable services, but it can't create API keys. Store a GitHub token that can read pull requests and write releases, plus your Resend key:

fused-cli bucket credential set github --bucket default
fused-cli bucket credential set resend --bucket default

The CLI prompts for each secret without echoing it, and the credentials take effect immediately.

Deploying registers the app but doesn't run it. Save the app family ID and the execution token from the deploy output, because the token is shown only once.

5. Call it

curl -X POST "$FUSED_ENGINE_URL/v1/apps/$FUSED_APP_FAMILY_ID/executions" \
  -H "Authorization: Bearer $FUSED_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"operation":"execute","input":{"repository":"acme/web","tag":"v2.4.0"}}'

{
  "status": "succeeded",
  "output": {
    "releaseUrl": "https://github.com/acme/web/releases/tag/v2.4.0",
    "pullRequests": 23,
    "announcementId": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
  }
}

The response is trimmed. If an execution is still running, look up the result later.

1. Code

Replace the one function that knows about the provider:

// The only part of the app that knows how announcements are delivered.
async function announce(repository: string, tag: string, url: string, notes: string): Promise<string> {
  const posted = z.object({ ts: z.string() }).parse(
    await fused.slack.chatPostMessage({
      channel: "#releases",
      text: `*${repository} ${tag} is out*\n${notes}\n<${url}|Full release>`,
    }),
  );
  return posted.ts;
}

2. Config

Swap the service and bump the version:

-version: "1.0.0"
+version: "1.1.0"
 ...
 services:
   github:
     version: "v3"
     operations: [reposListReleases, searchIssuesAndPullRequests, reposCreateRelease]
-  resend:
-    version: "1.5.0"
-    operations: [postEmails]
+  slack:
+    operations: [chatPostMessage]

3. Deploy

fused-cli bucket credential set slack --bucket default
fused-cli app plan  -f .fused/unified_app/publish-release.yaml
fused-cli app apply -f .fused/unified_app/publish-release.yaml

Callers using the family URL pick up 1.1.0 with no code change or redeploy.

4. Roll back

Published versions are immutable. Redeploying changed code under an existing version number fails with app_version_immutable, so 1.0.0 stays exactly as it was.

fused-cli app promote publish-release --version 1.0.0

New requests go back to the email version immediately. Your local files aren't touched.

With raw API tools

Prompt: "Release v2.4.0 of acme/web." To get it right, the agent has to work out on its own that it should:

• check that v2.4.0 hasn't already been released
• pick the right base release and ignore drafts
• write a valid merged-PR search and notice when results run past one page
• create the release before announcing it
• avoid a second announcement when it retries a failed step

Every run is planned from scratch. Every tool call is another round trip. The agent also holds every operation those tools expose.

With a Unified App

{
  "name": "execute",
  "arguments": {
    "operation": "unified_app:publish_release",
    "input": { "repository": "acme/web", "tag": "v2.4.0" }
  }
}

The steps, order and edge cases are the same on every run, and the agent holds one action instead of the operations behind it. Failures come back as clear errors, such as Nothing merged since v2.3.0, which the agent can report instead of improvising a fix.

TypeScript SDK

apiVersion: fused/v1
kind: sdk
name: release-tools
version: "1.0.0"
language: typescript
bucket: default
unified_apps:
  publish_release:
    name: publish-release
    version: "1.1.0"

After fused-cli app plan and apply:

const result = await sdk.unifiedApps.publish_release({ repository: "acme/web", tag: "v2.4.0" });

if (result.status === "succeeded") {
  console.log(`Published ${result.output.pullRequests} changes: ${result.output.releaseUrl}`);
}

The Python SDK exposes the same app as sdk.unified_apps.publish_release(...).

MCP server

apiVersion: fused/v1
kind: mcp
name: release-agent-tools
version: "1.0.0"
description: Release tools for the engineering assistant
bucket: default
unified_apps:
  publish_release:
    name: publish-release
    version: "1.1.0"

Agents call it through the server's execute tool as unified_app:publish_release.

REST

Use the family URL and execution token from the deploy, as in the build steps above. The family URL serves whichever version is currently promoted.

Another app

One Unified App can call another with fused.callApp(...), up to eight levels deep and with at most 32 nested calls.