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, 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}!` }),
  }),
]);

`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