octoscript_
中文GitHub
DEVELOPER GUIDE / APPS & AGENTS

Run an app, then follow its agent

OctoScript describes workflows and interfaces. OctoSense hosts apps and connects them to octos, the Rust agent kernel. This guide follows an app from its source to a running UI, then follows a person’s request through its app agent.

The coding agent that helps write an app and the app agent that answers its users are separate roles. Development instruments inspect a running UI; app agents use the tools and data granted by the product host.

INTERACTIVE ARCHITECTURE

Follow a path. See who owns each step.

A map of the implementation, not a connection to a live app or account.

Choose the source you have. Follow its host and rendering path to native widgets.

100%

Select a node to read its role. Enable Move graph to drag; the wheel still scrolls the page. Focus the canvas and use arrow keys to pan. Fit view shows the whole map; Focus a node restores readable detail.

App authorRust app moduleCompiled AppModule
App bundleSplash app sourcemain.splash
App bundleL0 card + data + kitpage.card
Rust + MakepadNative module hostMount, events and state
App HubBundle admissionManifest → granted policy
OctoScript + rendererRealize, lower, translateCard tree → UiNode → source
Card runner + SplashContained UI hostEvaluate and mount
UI hostNative Makepad UIDraw → input → update
React Flow
Solid: execution or request pathTwo arrows: request and reply
App bundle

Splash app source

A contained script app ships main.splash. Makepad Script evaluates it with the capabilities installed by the host. This is a UI entry point, separate from the standalone OctoScript workflow CLI.

Read the source walkthrough ↗
Text version: both paths and their responsibilities

App → native UI

Choose the source you have. Follow its host and rendering path to native widgets.

  1. Rust app module — A native Rust AppModule supplies compiled widgets, state and service code. It can also embed Splash. This path describes a module inside its host; a separate native executable has its own process and integration contract.
  2. Splash app source — A contained script app ships main.splash. Makepad Script evaluates it with the capabilities installed by the host. This is a UI entry point, separate from the standalone OctoScript workflow CLI.
  3. L0 card + data + kit — An L0 card declares data, state and components. Realization checks and expands these declarations without a VM. The card still needs its declared data and a compatible component kit; it does not start an agent or gain tool access by itself.
  4. Native module host — The compiled host registers the AppModule, mounts its UI and delivers events to its Rust handlers. It owns state and widget lifetime. A standalone host and the full shell have different service wiring; the shell adds the request broker and agent integration.
  5. Bundle admission — The host checks the bundle and resolves its manifest against HostLimits before evaluation. Storage jail, network allowlist and resource budgets constrain the app. An admitted declaration still needs an executable service.
  6. Realize, lower, translate — OctoScript checks and realizes the semantic card tree. Lowering converts this tree into kit source; checked evaluation produces the renderer UiNode; Rust emits Makepad widget source. Native kits use the measured-design path. These are distinct tree representations and host stages.
  7. Contained UI host — The runner mounts script or lowered card source inside Splash and routes UI events. Standalone card-host registers no host services or agent runtime. In OctoSense, the shell supplies registered services and the app-agent bridge.
  8. Native Makepad UI — Makepad draws widgets and delivers input through the host event loop. The host updates state and decides when to render again. A visible widget is not proof that a database, device API or agent operation is connected.
  • Rust app module → Native module host: compile / register
  • Splash app source → Bundle admission: bundle
  • L0 card + data + kit → Bundle admission: bundle
  • Bundle admission → Realize, lower, translate: card entry
  • Bundle admission → Contained UI host: script entry
  • Realize, lower, translate → Contained UI host: widget source
  • Native module host → Native Makepad UI: mount
  • Contained UI host → Native Makepad UI: render

Request → answer

The shell controls access. One shared kernel runs peer conversations; app data stays behind host tools.

  1. Person in app chat — A person can use desktop Ask <app> or a supported app-owned chat surface. Trusted shell input carries person origin; a script’s person trigger is only its assertion, not an approval bypass. Answers return to the originating conversation with separate transcript and request IDs.
  2. System agent — agents.ask handles preparation and readiness. peer_send_input delegates to the actual peer identifier through the shell. System requests use the peer session; peer_gather collects their results. These routes do not grant a general app-to-system delegation API.
  3. Shell app broker — The broker is the shell’s request adapter. It prepares the allowed app/account peer, opens conversation sessions and routes input and output. Human sharing-context sessions and the system peer session keep separate transcripts while sharing bounded recent context.
  4. Shared agent kernel — The shell shares one kernel runtime across app peers. A turn orchestration task waits at a start barrier; admission, ownership and acceptance precede its release and agent processing. A peer is not one Tokio task or one UI VM. Desktop/Android use a child process; OpenHarmony embeds the runtime.
  5. App peer — A peer is a persistent app/account identity. Each session holds one conversation; the model processes its turn and requests only available tools. Host results return to that turn. Human answers go to their event receiver; results may also leave origin-labelled blackboard records (shared result records), without automatically waking the system agent for human turns.
  6. Authorized host tools — Host adapters enforce scope and approval before executing operations. Cross-app tools also need the owner’s shareable declaration and caller grant; default App Hub admission rejects arbitrary names such as mail.send. Store-app script tool declarations still lack a dispatcher.
  7. App records / account API — The app’s business data is separate from transcripts and agent memory. Access needs an implemented tool. On Unix, consent plus an available exposed account workspace can enable bounded files.list/read/search; other app storage and host secrets are not automatically readable.
  • Person in app chat ↔ Shell app broker: input / answer
  • System agent ↔ Shell app broker: delegate / result
  • Shell app broker ↔ App peer: turn / events
  • Shared agent kernel → System agent: runs
  • Shared agent kernel → App peer: hosts
  • App peer ↔ Authorized host tools: tool / result
  • Authorized host tools ↔ App records / account API: operation / data

Choose what you are running

ArtifactRuntimeStart here
Workflow .octoscriptOctoScript’s bounded workflow runtime, with registered tools and host-issued grantsThe workflow example
Native Rust appA compiled AppModule with Rust event handlers and Makepad widgetsOctoSense build and run instructions
Contained main.splash appMakepad Script evaluated inside a Splash UI hostDesign Flow’s tools/octo run and App Hub’s card-host
L0 page.card with data and a kitOctoScript checks and realizes the card; OctoScript-Makepad lowers and renders itThe same card host, with the declared data and kit files

tools/octo is a Python development command. It starts the Rust card host; it is not the octos agent kernel. A native Rust app can embed a Splash view while keeping its services in compiled Rust.

Run a contained app locally

Use Design Flow’s native workspace setup to prepare the repositories and build prerequisites. Its runtime lock selects compatible source revisions.

Recipe status: these native build and launch commands have not been executed as part of the website checks.

From the Design Flow checkout:

python3 tools/setup-native.py
python3 tools/setup-native.py --check

From the App Hub sibling:

cargo build --release -p octosense-card-host -p octosense-app-hub

Return to Design Flow and use a new destination directory and a free port:

tools/octo doctor
tools/octo new /tmp/octosense-notes --id walkthrough.notes --name "Notes"
tools/octo run /tmp/octosense-notes/bundle --hidden --detach --port 8141
tools/octo shot 8141 /tmp/octosense-notes/first-frame.png
curl -s http://127.0.0.1:8141/quit

run takes the bundle path as a positional argument. With --detach, it returns after the new process exposes its UI and a rendered frame; without it, the terminal waits for the app to exit. The default development run stamps the manifest, so use an unsigned working copy.

This tests parsing, rendering and the host’s contained storage and network policy. Standalone card-host registers no host services and no agent runtime. It cannot complete mail.*, model.complete or octos.* requests. Use the local signed-catalog rehearsal to test an installed app inside the full shell. Desktop, Android Home and ROM commands belong to the OctoSense repository; a ROM build also includes the operating system.

From card source to native widgets

Realization checks the card’s declared data and state and expands its components into a complete tree. Lowering converts that tree into the more detailed source needed by a component kit and renderer.

page.card + host data + instance state
  → OctoScript L0 check and realization
  → component-kit lowering
  → checked evaluation into renderer UiNode data
  → Makepad widget source
  → native host mounts a View and handles events

The realized L0 tree and the renderer’s UiNode are different representations. Native kits load native/<mood>/kit.json and use the measured-design path; other kits assemble palette and component source. In either case the host supplies data, registers widgets, handles actions and decides when to render again.

In the framework’s catalog and preview hosts, the final widget source is evaluated on the app’s main makepad-script VM and its View is assigned to Splash.view. App Hub’s contained script host has its own admission and isolate setup. Sharing the VM implementation does not give every app the same instance, bindings or permissions. Follow the renderer code walkthrough for the exact calls and the different evaluation budgets.

Follow “Summarize my saved notes”

Assume the app has stored notes in its exposed account folder and the person has allowed its agent in OctoSense. A peer is that app agent’s identity; a session holds one conversation and its transcript; a turn is one request and the model/tool work needed to answer it.

  1. The person opens desktop Ask <app> and sends the request. The shell selects the app peer and its human conversation. An app can also provide a chat surface through the shell’s octos.* service.
  2. The shell starts a turn with the person’s origin. Octos admits the turn, records ownership and starts model processing. The model can request a tool; its text does not authorize access.
  3. On Unix, the shell can expose bounded files.list, files.read and files.search tools when the person has consented and an account workspace is available. These tools read the exposed account folder. Records at the app’s storage root, and host-service secrets outside that folder, are not automatically readable.
  4. The tool result returns to the model, which writes an answer. Events and completion go back to the human conversation that submitted the request.

A UI’s data store, the conversation transcript and the agent’s memory are separate stores. For structured records elsewhere, the app needs an implemented tool that interprets those records; shipping a tool declaration alone does not make that operation executable.

The system agent can delegate the same request using the app peer’s actual identifier. Its request uses the peer’s system conversation; human chat can use a separate session that shares bounded recent context. Each keeps its own transcript. Human answers go to that conversation’s event receiver. Both origins can leave labelled results in the peer blackboard, the coordination record; a human-origin result does not automatically wake the system agent. The system agent gathers the results of its delegated requests.

Calling another app or the system agent

Cross-app calls require an owner’s shareable tool declaration, the caller’s grant, host admission and an executable route. Approval applies where the tool’s policy requires it. App Hub’s default offered-tool list excludes arbitrary names such as mail.send; adding that name to agent.tools fails default admission.

System-to-app delegation is implemented. A contained app does not inherit the system agent’s tools or gain unrestricted app-to-system delegation. It can use only coordination routes the host actually supplies and authorizes.

Declaration or featureCurrent integration boundary
First-party implemented_by: "host-service" toolsRun through registered Rust services under the host’s policy.
Store app implemented_by: "app" toolsThe current shell has no script dispatcher for these declarations. Opening the UI does not install one.
Bundle AGENT.md and skillsApp Hub validates them; the current shell does not install their contents into app peers. Repository AGENTS.md instead instructs the coding agent.
Model needs, background triggers and scheduling metadataValidation does not supply the missing runtime selection or scheduling behavior.
L0 sys.chat / ChatEntrySupported by the shell’s runtime, but absent from the current Design Flow authoring pin. Check AI services and runtime compatibility before authoring such cards.

Where Tokio fits

A peer can exist while no task is running. When handling a request, Octos spawns turn orchestration behind a start barrier. It checks admission, records ownership and sends acceptance before releasing the barrier; a refusal aborts the waiting task. Orchestration then spawns the agent processing task. A host-tool call waits on a one-result channel while Tokio can schedule other work; the host decides where the actual database or network operation executes.

Transport and event forwarding add other tasks. Card/VM evaluation and UI events follow the UI host’s scheduling; a peer is neither one Tokio task nor one UI VM. The shell shares a kernel runtime across app peers. Desktop and Android normally run it as a child process, OpenHarmony embeds it, and iOS currently has no integrated kernel. Follow the octos request and task walkthrough for admission, cancellation and reply correlation.

Continue in the source repositories

  • OctoSense: native apps, desktop/Home/ROM, conversation entry points and the shell broker.
  • App Hub: admission, installation, contained storage and host-service requests.
  • Design Flow: CLI behavior, image/card stages and publication hand-off.

Read the source revision selected by the consuming app’s Cargo and runtime locks. The website’s prebuilt WASM lab has its own pinned build receipt and uses local demo state; it does not connect to a production OctoSense app agent or account.

←All documentation