HarnessBuild

Code packages and main

Updated 2026-11-16Partly available

Every turn ends up running one code package's entry point, main(context, handle). The Runtime calls it once per turn: context is the turn's business input, and handle is the private handle through which it asks the platform for things. The platform's own Ailo is a code package like this too, with no access that a customer's package would not have.

Current status

Live conversations run only the platform's two entry points today: the built-in loop and the standard package. A code package you upload cannot run in a live conversation yet; you can pack it into a .ailo, upload it, have it statically checked and save it as a version. This page describes the interface as it is today.

What the entry point looks like #

The smallest main
import type { Main } from '@ailodesk/ailo-sdk';

export const main: Main = async (context, handle) => {
  // Read context; use handle to call the model and make requests to Desk
  return { success: true };
};

main returns a MainResult:

Result Meaning
{ success: true, end_reason? } This call finished normally
{ success: false, error: { code, message? } } The package's code failed

success: true only says main finished, not that a message was sent; success: false does not mean nothing happened. What the customer received is whatever Desk's receipts say. Once main returns or throws, the Runtime closes the turn for you.

context: the turn's input #

Field Contents
turn turn_id, the trigger trigger, the deadline deadline_at, this turn's reply language locale
conversation The context Desk chose for this turn: recent public messages, notes for Ailo, public fields of tickets
user_info Only when the customer's identity is verified, otherwise null. The type has player_id, name, locale, tier and attributes; today only player_id and locale are filled in
allowed The actions and Desk tools allowed in this turn
package The pinned package version: system prompt prompt, SOPs procedures, FAQ faq, two catalogues and site settings settings
engine The engine parameters pinned for this turn, such as the maximum model calls per turn and how to close when a limit is hit
test A test conversation: only Desk's read tools are offered
simulated Handoffs and tickets are recorded as simulations only. The current test bench runs handoffs for real (to the person who started the test), so this is false there
images Images the customer sent, prepared by the Runtime; you decide whether the model sees them

A few rules:

  • The model sees only what you put in. The Runtime never adds context to the model input on its own; even user_info reaches the model only if you write it in.
  • Internal content is not in context. Notes for the team, internal ticket goals, other conversations and credentials are never given to a code package.
  • package.procedures and package.faq are Maps keyed by name; each entry has title, version, text, tools and tags. Where the fields come from is in Knowledge and SOP API.

handle: asking the platform #

Method What it does
start / get / resume / cancel Model runs: start a run, read its state, hand back tool results and continue, cancel
submitAction(action) Submit an action to Desk: reply say, handoff request_human, assist ticket request_assistance, end finish, fail fail, and progress activity.*
callTool(call) Call a business tool hosted by Desk
recordExternal(call) Record a result read from an outside system and get a ref a reply can cite
unread() Has the customer written something this turn has not read?
teamOnline() Is a teammate online now to pick up a draft?
report(step) Report the package's own steps for the run record
cancelled(), signal Whether the turn was cancelled; signal aborts when the handle closes
  • Desk's receipt is the answer. submitAction and callTool return { kind: 'receipt', … } or { kind: 'uncertain' }. When it is uncertain, do not resend under a new id: that could do the same thing twice.
  • The same request keeps the same id. Replaying a request id within a turn is recognized as a duplicate and returns the first result.
  • The handle is valid for this call only. Calls after main returns throw HostError('handle_closed'). The handle is not business data: never give it to a model, write it to a log or pass it to a tool.

Who guarantees what #

Whether you use the SDK's loop, write your own loop or skip the SDK entirely:

  • The Runtime enforces each turn's model-call limit, the daily budget and the deadline. A package cannot get past them.
  • Desk enforces serving rights, organization isolation, input validation, the turn's permissions and the evidence checks. A package's own approval counts for nothing.
  • Real writes in business systems must be made idempotent by whoever runs them. When the result of a write is unknown, do not redo it and do not promise the customer an outcome.

The Runtime can run the entry point in a separate worker thread, which contains infinite loops, crashes and memory misuse, but this is not a security sandbox: before customer code can be opened up, the platform has to design a real isolation boundary.

Choosing the entry point: engine.main #

In a package version's engine parameters, engine.main chooses which entry point the package runs:

Value Runs
unset The built-in loop (default)
loop The built-in loop
standard The main of the standard package @ailodesk/harness-standard, written with the SDK and reusing the built-in loop's prompts, tools and checks

Those are the only values; neither can point at your own code. Change engine parameters with set_package_engine_config: it needs an organization admin, Config turned on for the organization, and a web sign-in. It saves a new version and does not go live; going live works as in Versions, publishing and going live.

How the standard package is wired today

The standard package currently reaches live conversations through a temporary in-process adapter and is off by default. Once the platform's persistent run path is ready, it replaces this adapter and the release evaluation is run again.

Uploading a code package #

What you can do today: pack a built package into a .ailo file with ailo pack and upload it; the platform checks it against its manifest and updates the draft if it passes; saving explicitly creates an immutable version. Only .ailo files are taken; ZIP versions uploaded earlier can still be viewed and downloaded. If you choose another file in the Console, the page says only a .ailo can be uploaded and uploads nothing.

What a .ailo is #

A .ailo is a standard ZIP with a manifest, ailo.json, at its root. The platform installs no dependencies and builds nothing: you upload a built artifact, with every dependency the code needs (the Ailo SDK included) already bundled in.

ailo.json field Contents
format The manifest format version: ailo pack writes 2 today; the older 1, with no tools, is still accepted
name, version The package name (lowercase letters, digits and -) and a semver version
protocol The protocol version for talking to the platform, from ailo.protocolVersion in package.json
runtime The runtime, node24 today
entry The entry file, .js or .mjs
sdk, built_by The SDK version at packing time (optional) and the packing tool
files The size and sha256 of every file other than ailo.json
tools Format 2 only: the package's own tools, see “Tools in a package” below; an empty list when the entry exports none

Packing and checking locally #

Bundle the code and the SDK into the entry file with the template's build first, then, in the package directory:

Shell
ailo pack
Shell
ailo validate ringfall-helper-1.2.0.ailo
  • ailo pack [DIR] [--out FILE.ailo] reads name, version, main (the entry) and ailo.protocolVersion from package.json, packs the files or folders listed in files (the folder holding main when there is none; with main at the root, the whole directory less node_modules, .git, .env, keys and earlier .ailo files) plus package.json, README, LICENSE and a lockfile, and writes <name>-<version>.ailo. Entries are sorted and carry a fixed time, so the same files give the same fingerprint everywhere, and the same bytes with the same CLI and Node version. It builds nothing, installs nothing and follows no symlink (a link anywhere in a path is refused); when the check fails it writes nothing.
  • ailo validate FILE.ailo runs the platform's upload check locally.
  • Both read local files only and need no sign-in.

Tools in a package #

Besides main, the entry exports tools: a list of tools made with defineTool. ailo pack loads the entry once, in a separate Node process on your machine (its top-level code runs, as it would under node), reads each tool's name, the description the model gets, its input_schema, its type and where it is defined, and writes them to tools in ailo.json. The platform reads only that list; it never loads uploaded code to list tools.

TypeScript
import { defineTool, type Main, platformTools, runAgent } from '@ailodesk/ailo-sdk';

export const orderStatus = defineTool({
  name: 'order_status',
  type: 'Orders',
  description: "Look up where one of this player's orders stands, by its order id.",
  input_schema: { type: 'object', properties: { order_id: { type: 'string' } }, required: ['order_id'] },
  execute: async (input, scope) => ({ body: { ok: true /* … */ } }),
});
export const tools = [orderStatus];
export const main: Main = (context, handle) =>
  runAgent(context, handle, { /* … */ tools: [...tools, ...platformTools(context)] });
  • type groups the Harness tools page. You choose the text: 1–32 characters with no leading or trailing space; a tool without one is Uncategorized. platform is kept for the platform's own tools (reply, request_human and the like) and no custom tool may use it, in any case (tool_type_reserved). The type only groups and filters; the model never sees it.
  • Names are the ones the model calls: a lowercase letter first, then lowercase letters, digits and _, at most 64 characters, unique within the package. At most 200 tools.
  • Where it is defined is the line that calls defineTool, so put the object defineTool returns in tools as it is: a copy ({ ...tool }) has no location. When the build leaves a source map and the original file is packed too (add src to files in package.json), that is the original file's line; otherwise the built file's; a file that is not packed is left out.
  • The SDK's platform tools (those from platformTools) are not listed: they belong to the platform group.
  • If the entry fails to load, takes more than 20 seconds, or exports a tools that is not a list, ailo pack stops and says why (tools_unreadable) and writes nothing. Timers or servers the entry starts do not keep it waiting.

What is checked #

Five layers, in order. The first two stop at the first problem; the other three list every problem at once, up to 50. Only syntax trees are parsed; nothing is executed.

Layer Checks
File The name ends in .ailo; at most 10 MiB; a valid ZIP
Archive Safe paths; no .git, node_modules, .env or keys; no links, encrypted or damaged files; no native binaries (.node, .so, .dylib, .dll, .exe); at most 30 MiB unpacked, 10 MiB per file, 1,000 files and 32 path segments
Manifest A root ailo.json (at most 512 KiB) with every field and no others; a format version and protocol version the platform supports; in format 2, tools with valid, unique names, no platform type and sources that are files in the package
Integrity Every file in the package is listed in ailo.json with a matching size and sha256; every listed file is there
Code The entry exports a function main; every static import from the entry onwards is followed: relative paths must point at files in the package, third-party packages must be bundled in; Node built-in modules do not count as missing

Common failure codes:

Code Meaning
manifest_missing No ailo.json at the root: the package was not packed with ailo pack
nested_root ailo.json is inside a folder: the outer folder was zipped too
format_unsupported The platform does not know this manifest format version
protocol_too_old The protocol version is older than the platform supports: upgrade the SDK and pack again
file_unlisted / file_missing A file in the package is not in the manifest, or a listed file is not in the package
file_hash_mismatch A file changed after packing
native_binary The package contains a native binary
import_unresolved The entry, or a file it imports, imports something the package does not contain
tool_type_reserved A tool's type is platform, the platform tools' type: choose another
tool_type_invalid A tool's type is empty, has a leading or trailing space, is over 32 characters or contains a control character
tool_name_duplicate Two tools have the same name
tool_invalid A tool's name, description, input_schema or source location is not valid

Protocol versions #

The platform's protocol version is 1 today, and the oldest it supports is 1. Once the protocol moves on, packages older than the oldest supported version are refused (protocol_too_old); upgrade the SDK and pack again.

Fingerprint #

For a package that passes, the platform records the sha256 of the canonical ailo.json as its fingerprint; it does not depend on the order of files in the ZIP or on the spacing in ailo.json. ailo pack and ailo validate print the same value.

Third-party libraries and keys #

  • Third-party libraries are bundled in. The platform installs no dependencies and has no list of preinstalled libraries: every library the package uses (a model vendor's SDK or another agent framework included) goes into the entry or the package's files through your build. Any pure-JavaScript library works; one that needs a native binary does not (native_binary).
  • You can call external models or agents with your own key. You put the key in the package, in code or in a JSON config file in the package; the platform keeps no secrets for code packages. Files named .env, .env.* (except .env.example, .env.sample and .env.template), SSH private keys such as id_rsa, *.key, *.pem, *.p12 or *.pfx are refused, so keep keys out of them.
  • Every member who can see the Console can download versions (harness_url, which needs console.view), and so can read the keys in them. Versions are immutable: to change a key, pack, upload and save a new version, then revoke the old key with the external service.
  • Outbound network rules are not decided yet. Uploaded code does not run today; which external addresses it may reach is settled together with the isolation design.

Obfuscation #

Obfuscated code is fine. The check parses syntax trees and runs nothing, so obfuscated code passes when:

  • It is an ES module (.js or .mjs) and the entry still has the named export main; that name must not be changed. When main is the result of a call (wrapped once, say), the upload passes and the check is left to run time; a literal, object, array or class is refused.
  • It was bundled before it was obfuscated: static imports may only point at files in the package or Node built-in modules.
  • It stays within the size limits above; obfuscation often makes files several times larger.

Also:

  • Obfuscation does not protect keys. Anyone who can download the version can still recover the strings in it.
  • Leave source maps out. A .map file is not refused, but shipping one hands over the source.
  • Errors and stack traces show the obfuscated names; keep your own unobfuscated build to read them against.
  • For the same source to give the same fingerprint, give the obfuscator a fixed seed.
  • Avoid options that generate code at run time or fight debuggers (eval, new Function, debugger loops): the isolation design may not allow code generated at run time, and debugger traps run into each turn's deadline.

Intact is not safe #

A .ailo only guarantees that the package is complete and has not changed since it was packed. It does not make the code safe, and there is no signing yet. Before uploaded code can run in live conversations, the platform needs isolation at the level of a virtual machine or container; until then the organization's Code packages switch is off by default and only platform staff can turn it on. Serving rights, keeping internal content internal, no invented progress, no unfounded promises and organization isolation are enforced on the Desk side only (see Who guarantees what above); nothing a package's code does gets around them.

  • Not available yet: running, and using an uploaded version in conversations or releases.
Command HTTP
create_ailo POST /api/tenants/{tenant_id}/ailos/commands/create_ailo
upload_harness POST /api/tenants/{tenant_id}/ailos/{ailo_id}/harness?filename=F.ailo&expected_revision=N with the raw .ailo bytes as the body
save_harness POST /api/tenants/{tenant_id}/ailos/commands/save_harness
read_harness GET /api/tenants/{tenant_id}/ailos/{ailo_id}/harness: the draft, the versions and the result of each upload

Write commands need an admin. upload_harness takes the Idempotency-Key header as its command id. From the CLI: ailo ailos upload AILO_ID --revision N --file F.ailo.

Next #