Other APIs

This chapter collects the rest of the public author-facing runtime helpers.

flo.sleep(ms)

Pause the script asynchronously:

await flo.sleep(500);

Use it sparingly for pacing, polling, or short waits between retries.

flo.time.formatUnixTimestamp(...)

Format a Unix timestamp using the runtime helper:

const text = flo.time.formatUnixTimestamp(
  1_700_000_000,
  "YYYY-MM-DD HH:mm:ss",
  "UTC",
);

flo.task.getContext<T>()

Read durable task context, including resume payloads:

const context = await flo.task.getContext<{
  resume_payload?: { batch_id?: string };
  custom?: { value: number };
}>();

flo.task.getProfile()

Read the current runtime profile metadata for the tool caller:

const profile = await flo.task.getProfile();
const profileId = profile.profile_id;
const displayName = profile.display_name;

The returned object includes:

• profile_id
• profile_kind
• permissions
• optional display_name

In the local Node preload shim, profile_id defaults to local-node-profile and can be overridden with FLO_LOCAL_PROFILE_ID. display_name can be set with FLO_LOCAL_PROFILE_DISPLAY_NAME.

flo.task.waitForUserMessage(...)

Suspend the current task until a later user message resumes it:

const response = await flo.task.waitForUserMessage({
  user_message: "Please finish the login, then reply done.",
  resume_payload: { step: "login" },
});

The public API name is waitForUserMessage. Legacy internal payloads may mention wait_for_human, but authored tools should use flo.task.waitForUserMessage(...).

See Wait For User Messages for resume behavior and checkpointing details.

flo.task.limits

Inspect runtime task-orchestration limits:

const maxChildren = flo.task.limits.maxSpawnChildren;

Use this value to chunk child-task work before calling spawnChildren(...).

flo.task.getState(...) And flo.task.putState(...)

Read and write lightweight task-scoped state shared by all tools in the current task:

await flo.task.putState({
  key: "checkpoint",
  value: { phase: "fetching" },
});

const checkpoint = await flo.task.getState<{ phase?: string }>({
  key: "checkpoint",
});

Built-In Tools Through flo.callTool(...)

flo.d.ts includes typed support for built-ins such as:

• read_text_file
• write_text_file
• read_dir
• zip
• unzip
• csv_*
• excel_*
• media_fetch
• media_push_vfs
• media_push_base64
• get_media_download_url
• read_tool_result_artifact
• send_notification
• send_media_attachment
• activate_skill
• read_skill_resource
• import_skill_asset

When a built-in already matches the file or media operation you need, prefer it over reimplementing the same behavior in script code.

read_tool_result_artifact reads a bounded selection from a large tool result that the current task already references. Pass artifact_id and optionally json_pointer, offset, and limit; limit is a serialized-data byte budget capped at 16 KiB. The tool never returns the complete artifact in one call, and artifact ids from other tasks are not readable.

Skill Resources And Assets

Two built-ins are especially useful from authored skills:

• activate_skill proactively adds a visible skill to the current task by skill_id
  • activation is handled by suspending the current execution so agentd can restart the task turn with the expanded skill set
  • if the newly activated skills require labels the current agent does not satisfy, agentd may hand the task over before execution continues
• read_skill_resource reads a selected skill resource or imports it into VFS
• import_skill_asset copies a selected skill asset into VFS

Both are invoked through flo.callTool(...).

Final Notes

• Favor JSON-serializable inputs and outputs.
• Keep secrets in the vault, not in manifests or state.
• Use shared task state or task tool state for resume checkpoints, depending on whether later tools need the same checkpoint.
• Use the manifest as the contract for what your tool needs.

For exact TypeScript signatures, refer to flo.d.ts.