OPAL reference

OPAL (Operator Permission and Access Layer) is the structured command interface every operator uses to drive Korall Engineering™ — you, an automation rule, or a connected language model. This page is the per-domain catalogue of registered OPAL Tasks.

For the architectural overview (why OPAL exists, the three operator types, permissions, audit), see OPAL architecture.

Security Consideration

OPAL Tasks are validated against operator permissions before execution. An LLM can only perform tasks the user has explicitly granted scope for — and those permissions can be revoked at any time. Every execution lands in the OPAL History database, so you can always see exactly what was done, by whom, against which Sentient and Node.

Task domains

Every subsystem registers its tasks into the central registry under a domain prefix. Click through for per-task parameter schemas, permissions, and examples.

Representative tasks of each domain:

• Catalog — catalog.list_widgets, catalog.list_by_tag, catalog.search, catalog.capture_widget, catalog.capture_all, catalog.preview_widget.
• Navigation — navigation.list_activities, navigation.goto_activity.
• Screenshot — screenshot.copy, screenshot.save.
• Batch — batch.list, batch.status, batch.cancel, batch.jobs.query, batch.job.get, batch.job.cancel, batch.job.retry.
• Batch — node — batch.node.mode, batch.node.capacity.
• Batch — fleet — batch.executors.list, batch.executors.explain, batch.drift.
• Clockwork — clockwork.list, clockwork.get, clockwork.history, clockwork.preview, clockwork.put, clockwork.pause, clockwork.resume, clockwork.run-now, clockwork.delete.
• Filesystem — filesystem.copy, filesystem.chmod.
• Directives — directive.new, directive.list, directive.pause, directive.resume, directive.delete.
• Constellation — constellation.list, constellation.details, constellation.status, constellation.launch, constellation.stop, constellation.create, constellation.delete, constellation.add_member.
• Help — help.search, help.list, help.outline, help.read, help.open, help.find.
• Attachment — attachment.list, attachment.glob, attachment.grep, attachment.read.
• LLM — llm.status, llm.usage, llm.provider.list, llm.provider.enable, llm.model.list, llm.model.setDefault, llm.credential.set, llm.permission.get, llm.permission.set.
• Web — web.fetch.
• Serial — serial.list_ports, serial.list_connections, serial.get_connection, serial.create_connection, serial.update_connection, serial.delete_connection, serial.open.
• BanterLab — banter.param_list, banter.preset_list, banter.codec_list, banter.testset_describe, banter.testset_list_tests.
• Shade — shade.run, shade.get_source.
• Sentient — sentient.set_password, sentient.view_profile, sentient.security_unboxing, sentient.export_recovery, node.create, node.delete, node.list, node.select.
• Config — config.list, config.get, config.set, config.reset, config.revert, config.export, config.import, config.undo, config.window.open.
• Singularity — singularity.audio.list-outputs, singularity.audio.set-output, singularity.audio.set-output-pair, singularity.audio.play-test-tone.
• Construct — construct.item_add, construct.item_remove, construct.item_rename, construct.item_duplicate, construct.item_set_transform, construct.item_set_rotation_mode, construct.item_set_parent, construct.item_set_material, construct.render.capabilities, construct.render.measure, construct.render.queue, construct.library.list, construct.library.rename, construct.library.tag, construct.library.trash, construct.library.restore, construct.library.trash_list, construct.library.health.

Rotation via OPAL is Euler-angle based and gizmo-independent. construct.item_set_transform sets rotation with rx/ry/rz (degrees) written directly to the item's transform — it does not go through the interactive rotation gizmo, so OPAL plans set orientation the same way regardless of gizmo behaviour.

An SDF item stores its rotation in one of eight representations. By default rx/ry/rz are degrees in the item's current mode. The optional rotationMode argument (EulerZYX, EulerXYZ, EulerXZY, EulerYXZ, EulerYZX, EulerZXY, AxisAngle, Quaternion) sets the rotation in that mode; for AxisAngle, rx/ry/rz are the axis and angle is the degrees. Given alone, rotationMode converts the item's current rotation without moving it, which is also what construct.item_set_rotation_mode (itemId, mode) does.

A transform under an expression is set through the parameter task. translate, rotate and scale are parameters, so an expression covers a whole channel: construct.sdf.set_all_parameters with {"rotate": "=vec3(0, anim.progress * 360, 0)"}. The scalars on construct.item_set_transform carry literal numbers only. It refuses a channel an expression already owns, because the expression is re-evaluated every frame and would discard the write.

Detail pages

Operator types

Every task invocation is made by one of three operator types. The task is the same; the permission gate differs:

See OPAL architecture for the rationale and Trust Levels for how permissions are graduated.

TaskPlans

A single task does one thing. A TaskPlan is a JSON document chaining tasks, with each step able to reference earlier outputs:

{
  "steps": [
    {"task": "catalog.list_by_tag", "tag": "trust"},
    {"task": "catalog.capture",     "id": "$1.results[0].id"},
    {"task": "filesystem.copy",     "from": "$2.image_path", "to": "/exports/"}
  ]
}

The same shape underlies LLM-composed plans, batch jobs, and trigger directives. See Plans for authoring tools.

Where you see OPAL in the UI

After a large task, such as a solve, a bake, a mesh step or a video export, the chat shows a result card below the row of the task: a small table of the numbers of the result, at most 12 rows. A task declares its card in its answer, in the output card. A job that ends after its task returned (wait: false) shows its card when it ends. The card is part of the conversation, so the history, a restored conversation and the PDF export show it too.