Tier 1 API

Tier 1 API

Cadenza exposes a small, curated surface as bare names — callable with no using directives, because each SDK adds global using static for the right classes. Tier 1 stays ≤ 10 names per SDK and is the same across every variant where it makes sense.

This page lists the surface as it ships in 1.0.x. The authoritative source is the code under src/; this is a user-facing summary.

Convention used below: a name shown as Foo is callable bare. A name shown as Foo.Bar is reached through the (bare) type Foo.

Shared across all five SDKs

These are available everywhere — they live in Cadenza.* packages that every SDK ships.

Fs — filesystem

string  Fs.ReadText(string path);
Task<string> Fs.ReadTextAsync(string path);
void    Fs.WriteText(string path, string content);   // UTF-8, no BOM
byte[]  Fs.ReadBytes(string path);
void    Fs.WriteBytes(string path, byte[] content);
bool    Fs.Exists(string path);
void    Fs.Delete(string path);
void    Fs.Move(string src, string dst);
void    Fs.Copy(string src, string dst);
void    Fs.MakeDir(string path);
IEnumerable<string> Fs.Glob(string pattern);          // **/*.cs etc.
TempDirectory Fs.TempDir();                            // IDisposable

ReadText, WriteText, and Glob are also exported as plain bare names (no Fs. prefix) on Console / Worker / Web / Mcp / Agent.

Sh — process / shell

int    Sh.Run(string cmd, bool throwOnError = false);     // returns exit code
string Sh.Capture(string cmd);                            // stdout, throws on non-zero
string Sh.Pipe(string cmd, string stdin);
Task<int>    Sh.RunAsync(string cmd, CancellationToken ct);
Task<string> Sh.CaptureAsync(string cmd, CancellationToken ct);

On Console / Worker / Web / Agent, Run and Capture are also bare. Not on Mcp — see "Per-SDK notes".

Http — HTTP client

Task<T>      Http.GetJson<T>(string url, JsonTypeInfo<T> ctx, CancellationToken ct = default);
Task<TResp>  Http.PostJson<TReq, TResp>(string url, TReq body,
                JsonTypeInfo<TReq> reqCtx, JsonTypeInfo<TResp> respCtx, CancellationToken ct = default);
Task<string> Http.GetText(string url, CancellationToken ct = default);
Task         Http.Download(string url, string path, CancellationToken ct = default);
HttpClient   Http.Client { get; }                         // for full-fat scenarios

Env — process environment

string? Env.Get(string key);
string  Env.Get(string key, string @default);
string[] Env.Args { get; }
string  Env.Cwd { get; }
string  Env.ScriptPath       { get; }                  // path to the running .cs
string  Env.ScriptDirectory  { get; }                  // its directory
void    Env.Exit(int code);
bool    Env.IsCi             { get; }                  // CI env detection
bool    Env.IsWindows / .IsMacOS / .IsLinux  { get; }

Json — JSON helpers

T?     Json.Parse<T>(string json, JsonTypeInfo<T> ctx);
string Json.Stringify<T>(T value, JsonTypeInfo<T> ctx);

Both take a JsonTypeInfo<T> (source-generated context) so they're AOT-clean.

Prompt — interactive console input

Available on Console / Worker / Web (not Mcp, not Agent — those SDKs don't own the terminal).

bool   Prompt.Confirm(string question, bool @default = false);
T      Prompt.Select<T>(string question, IEnumerable<T> options);
string Prompt.Text(string question, string? @default = null);
string Prompt.Password(string question);

Standard console

WriteLine, Write, ReadLine are exposed via using static System.Console on Console / Worker / Web / Agent.

Not on Mcp — Mcp owns stdio for JSON-RPC. Writing to stdout would corrupt the protocol; use Log.Info(...) instead.

Cadenza — Console

The same shared surface above, plus:

• Sh.Run / Sh.Capture are bare → Run("git status"), Capture("git rev-parse HEAD").
• Fs.ReadText / Fs.WriteText / Fs.Glob are bare → ReadText("file"), Glob("**/*.cs").
• No host — the script runs top to bottom and exits.

Cadenza.Worker

The shared surface (without Prompt is technically still available but inadvisable in a daemon), plus:

Task Worker.Run(Func<CancellationToken, Task> work);
Task Worker.Run(Func<IServiceProvider, CancellationToken, Task> work);   // DI variant
T?   Worker.Config<T>(string key);
T    Worker.Service<T>();

• Run is bare → await Run(async ct => { … });
• Log.Info / Warn / Error / Debug route through ILogger.

Cadenza.Web

RouteHandlerBuilder       Web.Get(string path, Delegate handler);
RouteHandlerBuilder       Web.Post(string path, Delegate handler);
RouteHandlerBuilder       Web.Put(string path, Delegate handler);
RouteHandlerBuilder       Web.Delete(string path, Delegate handler);
IEndpointConventionBuilder Web.Map(string path, Delegate handler);
Task                       Web.Run();

void                       Web.UseHttps();
void                       Web.UseCors(string policy = "default");

IServiceCollection         Web.Services { get; }      // add DI services
WebApplication             Web.App      { get; }      // drop down to raw ASP.NET Core

Get / Post / Put / Delete / Map / Run / UseHttps / UseCors are bare.

Bind URL is configured via standard ASP.NET Core mechanisms: the ASPNETCORE_URLS environment variable, the --urls CLI argument, or Web.App.Urls.Add(...). See Cadenza Web and Deployment Container.

Cadenza.Mcp

void Mcp.Tool(string name, string description, Delegate handler);
void Mcp.Resource(string uri, string name, Delegate handler);
void Mcp.Prompt(string name, string description, Delegate handler);
Task Mcp.Run();

All four are bare. Cadenza infers the JSON schema for tool inputs from the handler's parameter types.

Log.Info / Warn / Error / Debug are available; WriteLine and friends are deliberately not — stdout belongs to the MCP JSON-RPC framing.

Cadenza.Agent

void Agent.Tool(string name, string description, Delegate handler);
void Agent.SystemPrompt(string text);

void Agent.UseOllama(string model, string baseUrl = "http://localhost:11434");
void Agent.UseOpenAi(string model, string? apiKey = null);
void Agent.UseAnthropic(string model, string? apiKey = null);
void Agent.UseAzureOpenAi(string endpoint, string deploymentName, string? apiKey = null);
void Agent.UseChatClient(IChatClient client);          // escape hatch (OpenRouter, custom, …)

Task          Agent.Run();        // OpenAI-compatible HTTP server (Chat Completions + Responses)
Task          Agent.ChatLoop();   // local REPL
Task<string>  Agent.Reply(string prompt);

And these mutable properties on the Agent type:

Agent.Port            { get; set; } = 8080;
Agent.HostName        { get; set; } = "localhost";
Agent.ServedModelName { get; set; } = "cadenza-agent";

Set them like HostName = "0.0.0.0"; Port = 9000; before await Run(). See Cadenza Agent for OpenRouter and Codex CLI patterns.

Discrepancies and notes

• Cadenza.Agent is not AOT-clean today — Microsoft.Extensions.AI's function-invocation middleware uses reflection. The other four SDKs are AOT-clean.
• The Sh.* / Fs.* / Http.* / Env.* / Json.* modules are stable across all SDKs and are intentionally the same shape everywhere.
• The full type signatures (JsonTypeInfo<T> for Http and Json, etc.) make every API AOT-safe by construction — see the spec, §4 onward, for the formal contract.

See also

• Directives — #:sdk, #:package, #:include, #:property
• Samples — every Tier 1 name has a working sample
• Source: src/ — authoritative surface