SDK reference

Every export of the @noodleseed/one authoring SDK, with signatures and import paths. The complete surface a coding agent authors against.

Everything you author with imports from the bare @noodleseed/one package. Two subpaths exist for widgets and hosting: @noodleseed/one/react (widget view helpers) and @noodleseed/one/platform (hosting target). This page lists the full surface.

One tool primitive

Every tool uses tool(...). Add view when its result renders React UI, or set visibility: ['app'] when it is an app-only helper. There is no separate widget-tool factory.

Bare `@noodleseed/one`

Export	Purpose
`server`	Compile a name + options + definitions into a deployable server.
`tool`	A typed tool; optionally view-linked or app-only through options.
`resource`	Readable context at a fixed or `{var}`-templated URI.
`prompt`	A reusable, argument-driven prompt template.
`connector`	Fluent builder for HTTP / compute / signature-only connectors.
`annotations`	Tool behavior-hint presets (`readOnly`, `action`, …).
`asset`	Reference a local file (logo, image) the compiler packages.
`handoffSession`	Build a typed handoff envelope to an external URL (checkout, booking).
`when`	Record a conditional step inside a `fulfil` flow.
`secret`	Reference a managed secret by name (`secret("API_KEY")`).
`variable`	Reference a managed non-secret variable (`variable("REGION")`).
`z`	The Zod namespace, compiled to JSON Schema 2020-12.

`server`

server(name: string, options: ServerOptions, definitions?: readonly ServerComponent[]): ServerDefinition

Key options: title, version, use (tool-facing connectors), provides (catalog-only connectors), instructions, agentGuide, distribution, branding, auth (customer auth), state. There is no fluent builder: you pass tools, resources, and prompts as the definitions array.

import { server, tool, z } from '@noodleseed/one';

export default server('hello', { title: 'Hello', version: '1.0.0' }, [
  tool('greet', {
    description: 'Greet someone by name.',
    input: z.object({ name: z.string().default('world') }),
    output: z.object({ message: z.string() }),
    fulfil: ({ input }) => ({ message: `Hello, ${input.name}!` }),
  }),
]);

agentGuide is the optional host-neutral source for product workflows that span declared capabilities. The compiler validates its symbolic tool, resource, and prompt references and emits a separate App Package; it does not add guide prose to the Runtime Artifact. See Product agent guides for the decision criteria, TypeScript shape, local installation, and explicit regeneration lifecycle.

distribution is the optional host-neutral source for listing copy, publisher/support/legal links, packaged icon/logo/screenshots, and credential-free review scenarios. It is useful only when preparing a host package. The SDK exposes it through toDistributionMetadata() separately, so listing edits do not change the manifest, Runtime Artifact, or canonical App Package. The CLI can project it through the explicit OpenAI local or submission adapter with noodle export plugin openai; Claude remains a later adapter. The option and export command do not deploy, register, publish, or submit anything.

`tool`

tool(name: string, options: {
  description: string;
  input: z.ZodType;
  output?: z.ZodType;
  annotations?: Record<string, unknown>;
  visibility?: ('model' | 'app')[];   // default ['model','app']
  view?: { component: string; entry: string } | { html: string };
  viewName?: string;
  viewTitle?: string;
  viewDescription?: string;
  csp?: WidgetCsp;
  domain?: string;
  permissions?: WidgetPermissions;
  fulfil: (ctx: { input; user; connectors }) => unknown | Promise<unknown>;
}): ServerComponent

The same factory covers all tool presentation:

tool(name, {
  description, input, output, fulfil,
  viewTitle: string,
  view?: { component: string; entry: string },   // React view path
  csp?, permissions?, annotations?, visibility?,
})

tool(name, { description, input, output, fulfil, visibility: ['app'] })

See the Apps & widgets guide.

`resource`

resource(name, {
  uri: string;               // 'docs://changelog' or 'case://{case_id}'
  title?, description?, mimeType?,
  fulfil: (ctx) => ({ contents: [{ uri, mimeType, text }] }),
})

`prompt`

prompt(name, {
  title?, description?,
  arguments?: z.ZodType | { name: string; description?: string; required?: boolean }[];
  fulfil: (ctx) => ({ messages: [{ role, content: { type: 'text', text } }] }),
})

`connector`

connector(id: string).version(v: string)
  .http({ baseUrl, auth?, allowedOrigins?, operations })   // real HTTP API
  .compute(name, { input?, output?, run, limits?, calls? }) // sandboxed TS
  .operation(name, { ... })                                 // signature only

See the Connectors guide and expression reference.

`annotations`

annotations.readOnly(opts?)      // { readOnlyHint: true, idempotentHint: true, ... }
annotations.action(opts?)        // model-callable side effect
annotations.localAction(opts?)
annotations.openAction(opts?)

`asset`, `handoffSession`, `when`

asset(sourcePath: string): PackagedAssetReference      // branding.logo.uri = asset('assets/logo.svg')

handoffSession({
  url: string; purpose: 'checkout' | 'booking' | 'payment' | 'external_link' | ...;
  expiresAt: string; provider?; stateHandle?;
})

when(condition, () => connectors.x.op(...))            // conditional flow step inside fulfil

`secret`, `variable`, `z`

secret('WEATHER_API_KEY')      // managed secret ref; set with `noodle secrets set`
variable('REGION')             // managed non-secret ref; set with `noodle variables set`
z.object({ name: z.string(), count: z.number().int().min(1).default(1) })

`@noodleseed/one/react`

For a widget's React view component:

import { generateHelpers } from '@noodleseed/one/react';
const { useToolResult } = generateHelpers();

`@noodleseed/one/platform`

The hosting target and built-in helper connectors:

import { noodlePlatform, noodlePlatformCatalog } from '@noodleseed/one/platform';

Validate as you go

The SDK compiles Zod schemas to JSON Schema and resolves connector references at compile time. Run noodle validate after each change; see Troubleshooting for the error format and common fixes.

On this page