Singularity

CLI commands

Execute exactly one autonomous cycle and print its persisted report.

singularity once

Boot the being, execute exactly one autonomous cycle, shut down Las, and return the cycle report.

Invocation

singularity once \
  --agent-id <id> \
  --role <role> \
  --environment <environment> \
  --host <host> \
  --workload-id <id> \
  --workload-public-key <64-lowercase-hex> \
  --executable-digest <64-lowercase-hex> \
  --code-digest <64-lowercase-hex> \
  --policy-digest <64-lowercase-hex> \
  --policy-sequence <integer> \
  --las-release-manifest <absolute-file> \
  --las-release-manifest-signature <absolute-file> \
  --las-release-trust-store <absolute-file> \
  --las-release-watermark <absolute-path>

Required inputs

The command requires these options, or their named environment-variable equivalents:

  • --agent-id (SINGULARITY_AGENT_ID), --role (SINGULARITY_ROLE), --environment (SINGULARITY_ENVIRONMENT), --host (SINGULARITY_HOST), and --workload-id (SINGULARITY_WORKLOAD_ID). Each is a 1–128 byte immutable identifier using only ASCII letters, digits, -, _, ., or :.
  • --workload-public-key, --executable-digest, --code-digest, and --policy-digest. Each value is exactly 64 lowercase hexadecimal characters.
  • --policy-sequence <integer>.
  • --las-release-manifest, --las-release-manifest-signature, and --las-release-trust-store. Each must name an absolute regular file. --las-release-watermark must be absolute.
  • Brama signing material: either --brama-secret-file <owner-only-file> / BRAMA_HMAC_SECRET_FILE, or WISENT_APP_AGENT_AUTH_SECRET when no file is supplied.

Runtime options

  • Persona: --agent-name MyAgent, --agent-ticker AGENT, --agent-type general, and --specialty general.
  • State and loop: --stimulus <text>, --starting-balance 10, --instance-price 0, --cycle-interval-secs 5, --max-tool-rounds 8, --state-dir .singularity, --workspace ., and --resume.
  • Brama: --brama-url http://127.0.0.1:8081, --brama-model any, --max-tokens 2048, --temperature 0.2, --input-price 0, and --output-price 0.
  • Las: --las-command node, --las-entrypoint ../las/src/mcp.mjs, --las-only <csv>, --las-skip <csv>, and --required-surfaces skarbiec,finance.
  • Most and deadlines: --most-url http://127.0.0.1:8080, optional --most-token-file <owner-only-file>, --http-timeout-secs 120, --mcp-timeout-secs 120, and --shutdown-grace-secs 10.

Every flag above also has the environment-variable spelling exposed by singularity <command> --help.

Output and state effect

After a successful cycle and successful Las shutdown, stdout receives pretty JSON with cycle, status, final_content, balance_usd, earned_usd, net_profit_usd, total_tokens, and ordered actions. Status is completed, tool_round_limit, or budget_exhausted.

The cycle counter, conversation, mind, budget, and activity journal are persisted exactly as they are under run. If the cycle or shutdown fails, no report is printed; the classed error is printed to stderr by the binary.

State refusals

Boot is deliberately strict:

  • Existing state without --resume is refused as state: state already exists at <path>; use --resume or a new directory.
  • --resume with no saved state is refused as state: resume requested but no state exists.
  • --resume with a different configured identity is refused as state: resume identity does not match configuration.

A fresh state directory without --resume creates a new being. A matching saved identity with --resume continues it.

Configuration refusals

Before contacting a surface or writing being state, the runtime refuses with the exact relevant message when:

  • stimulus exceeds 65536 bytes or contains NUL: configuration: stimulus must be at most 65536 bytes and contain no NUL;
  • the workspace cannot be resolved or is not a directory: configuration: workspace: <error> or configuration: workspace must be a directory;
  • --max-tool-rounds is zero: configuration: max tool rounds must be positive;
  • a starting balance or price is negative: configuration: prices and balance cannot be negative;
  • temperature is not finite or is outside 0 through 2: configuration: temperature must be finite and between zero and two;
  • the Las entrypoint is not a file: configuration: LAS entrypoint not found: <path>;
  • a release manifest, signature, or trust-store path is not absolute or not a regular file: configuration: <label> must be an absolute regular file;
  • the watermark path is relative: configuration: LAS release watermark must be an absolute path;
  • an immutable identity component is invalid: configuration: <label> is not a valid immutable identifier;
  • a public key or digest is malformed: configuration: <label> must be 64 lowercase hexadecimal characters;
  • neither Brama secret source exists: secret file: BRAMA_HMAC_SECRET_FILE or WISENT_APP_AGENT_AUTH_SECRET is required;
  • a secret path is not a regular file, is group/world accessible, or is empty: secret file: not a regular file: <path>, secret file: <path> must not be group/world accessible, or secret file: <path> is empty.

Clap refuses a missing required option before runtime code executes. Configuration and secret refusals exit 2; upstream Brama, Las/MCP, or Most failures exit 3; state or I/O failures exit 4; tool, runtime, or JSON failures exit 5.