@aster/processor

Canonical source: packages/processor/README.md · Edit the source file

The v2 authoring SDK for confined harnesses and domain processors. It exposes the six-duty adapter surface: a kernel-composed context package, brokered and wrapped tools, native-event emission, host-owned session leases, bounded control, and canonical Processor-face settlement.

Install

npm install @aster/processor

Use the root package for processor definitions, tool helpers, runtime types, and convenience imports. Use @aster/processor/turn when you want the dedicated low-level turn-processing entrypoint.

Quick start

import { Processor } from "@aster/processor"

export default Processor.make({
  id: "my-processor",
  name: "My Processor",
  description: "A minimal domain loop.",
  async run(input, runtime) {
    runtime.log(
      `Running obligation ${runtime.contextPackage.obligation.summary}`,
    )
    const turn = await runtime.turn.execute({ prompt: input.prompt })
    if (turn.canceled) {
      return runtime.settlement.canceled("The owner canceled the turn.")
    }
    return runtime.settlement.succeeded(`Completed: ${input.prompt}`)
  },
})

runtime.turn.execute is bounded. The host owns live-handle caching, durable lease metadata, steering delivery, and cancellation transport; authored loops do not poll an inbox or persist harness sessions. Use runtime.contextPackage as the exact admitted contract, runtime.tools for the projected tool inventory, runtime.events for canonical event emission, and runtime.settlement to return the aster.processor face.

Harness adapters

The root export includes the generic ports extracted from the Pi adapter:

• ProcessorHarnessToolPort injects brokered and shape-preserving wrapped tools through one host invocation path.
• ProcessorHarnessEventPort accepts native events for translation into Aster evidence.
• openProcessorHarnessSessionLease implements fresh, resumed, and evidence-rebuilt continuity while treating live handles as disposable caches.
• ProcessorHarnessContextPackageSchema validates the exact kernel-composed package delivered through native harness seams.

Start from templateDomainProcessor and makeTemplateHarnessAdapter. The template is intentionally small and passes the same conformance kit used by Pi without template-specific allowances. Certification through runHarnessAdapterConformance is the supported path for third-party harnesses.

Defining tools

Use tool() to create strongly typed tools with schema validation and automatic input coercion.

import { tool } from "@aster/processor"

const echo = tool({
  name: "echo",
  description: "Echo the input text",
  schema: tool.schema.Object({
    text: tool.schema.String({ minLength: 1 }),
    count: tool.schema.Number(),
    verbose: tool.schema.Optional(tool.schema.Boolean({ default: false })),
  }),
  async execute(args) {
    // args is typed as { text: string; count: number; verbose: boolean }
    return args.text.repeat(args.count)
  },
})

tool.schema exposes the underlying schema builder used by the SDK. Use it to define Object, String, Number, Boolean, Array, Optional, and similar shapes. Inputs are parsed before execute() runs, so numeric and boolean fields can be safely coerced from string inputs.

Register tools on your processor definition:

export default Processor.make({
  id: "my-processor",
  name: "My Processor",
  tools: [echo],
  async run(input, runtime) { /* ... */ },
})

Validation helpers

• Processor.make(input) — marks a v2 context/ports/settlement definition.
• isProcessorDefinition(value) — type guard that checks for the definition marker, id, name, and run function.

Entrypoints

Entrypoint	Contents
@aster/processor	Processor.make, harness ports and lease helper, template harness, tool, marker constants, turn helpers, and the full v2 runtime surface.
@aster/processor/tool	tool factory function with tool.schema (TypeBox Type namespace).
@aster/processor/runtime	Processor.make, Processor.is, Processor.turn, and isProcessorDefinition.
@aster/processor/turn	Processor.turn.

Related packages

• @aster/processor provides the standalone tool-package authoring surface.
• capabilities/plugins/deep-research, capabilities/plugins/excel, capabilities/plugins/jujutsu, and capabilities/plugins/powerpoint contain example service-owned processors that use this SDK.