Actions

@agent-native/core provides an action dispatcher and utilities for building agent-callable actions.

Action Dispatcher

The action system lets you create actions that agents can invoke via pnpm action <name>. Each action is a TypeScript file that exports a default async function.

// actions/run.ts — dispatcher (one-time setup)
import { runScript } from "@agent-native/core";
runScript();

// actions/hello.ts — example action
import { parseArgs } from "@agent-native/core";

export default async function hello(args: string[]) {
  const { name } = parseArgs(args);
  console.log(`Hello, ${name ?? "world"}!`);
}

# Run it
pnpm action hello --name Steve

parseArgs(args)

Parse CLI arguments in --key value or --key=value format:

import { parseArgs } from "@agent-native/core";

const args = parseArgs(["--name", "Steve", "--verbose", "--count=3"]);
// { name: "Steve", verbose: "true", count: "3" }

Standard actions

Every template should include these two actions for context awareness:

view-screen

Reads the current navigation state, fetches contextual data, and returns a snapshot of what the user sees. The agent should always call this before acting.

// actions/view-screen.ts
import { readAppState } from "@agent-native/core/application-state";

export default async function main() {
  const navigation = await readAppState("navigation");
  const screen: Record<string, unknown> = { navigation };

  if (navigation?.view === "inbox") {
    const res = await fetch("http://localhost:3000/api/emails?label=" + navigation.label);
    screen.emailList = await res.json();
  }

  console.log(JSON.stringify(screen, null, 2));
}

pnpm action view-screen

navigate

Writes a one-shot navigation command to application-state. The UI reads it, navigates, and deletes the entry.

// actions/navigate.ts
import { parseArgs } from "@agent-native/core";
import { writeAppState } from "@agent-native/core/application-state";

export default async function main(args: string[]) {
  const parsed = parseArgs(args);
  await writeAppState("navigate", parsed);
  console.log("Navigate command written:", parsed);
}

pnpm action navigate --view inbox --threadId thread-123

Shared Agent Chat

@agent-native/core provides an isomorphic chat bridge that works in both browser and Node.js:

import { agentChat } from "@agent-native/core";

// Auto-submit a message
agentChat.submit("Generate a report for Q4");

// Prefill without submitting
agentChat.prefill("Draft an email to...", contextData);

// Full control
agentChat.send({
  message: "Process this data",
  context: JSON.stringify(data),
  submit: true,
});

In the browser, messages are sent via window.postMessage(). In Node.js (actions), they use the BUILDER_PARENT_MESSAGE: stdout format that the Electron host translates to postMessage.

Utility Functions

Function	Returns	Description
loadEnv(path?)	void	Load .env from project root (or custom path)
camelCaseArgs(args)	Record	Convert kebab-case keys to camelCase
isValidPath(p)	boolean	Validate relative path (no traversal, no absolute)
isValidProjectPath(p)	boolean	Validate project slug (e.g. "my-project")
ensureDir(dir)	void	mkdir -p helper
fail(message)	never	Print error to stderr and exit(1)