build: generate agentos actor action types

Author: NathanFlurry

.gitignore

@@ -15,6 +15,7 @@ target/
 # TypeScript
 *.tsbuildinfo
 dist/
+packages/agentos/src/generated/
 
 # IDE
 .vscode/

crates/agentos-actor-plugin/src/actions/mod.rs

@@ -237,6 +237,9 @@ pub mod contract {
         pub ts_signature: &'static str,
     }
 
+    pub const GENERATED_ACTOR_ACTIONS_PATH: &str =
+        "packages/agentos/src/generated/actor-actions.generated.ts";
+
     pub const ACTION_CONTRACTS: &[ActionContract] = &[
         ActionContract {
             name: "readFile",
@@ -517,6 +520,141 @@ pub mod contract {
         },
     ];
 
+    pub fn render_actor_actions_ts() -> String {
+        use std::fmt::Write as _;
+
+        let mut out = String::from(ACTOR_ACTIONS_TS_PREAMBLE);
+        for action in ACTION_CONTRACTS {
+            writeln!(&mut out, "\t{}", action.ts_signature)
+                .expect("writing generated actor actions to string");
+        }
+        out.push_str("};\n");
+        out
+    }
+
+    const ACTOR_ACTIONS_TS_PREAMBLE: &str = r#"// @generated by agentos-actor-plugin. Do not edit.
+// This file is generated locally and is intentionally not committed to Git.
+// Run `pnpm --dir packages/agentos generate:actions` to regenerate it.
+import type {
+	ExecResult,
+	PermissionReply,
+	ProcessInfo,
+	ProcessTreeNode,
+	SpawnedProcessInfo,
+	VirtualStat,
+} from "@rivet-dev/agentos-core";
+import type {
+	PersistedSessionEvent,
+	PersistedSessionRecord,
+	PromptResult,
+	SerializableCronJobInfo,
+	SerializableCronJobOptions,
+} from "../types.js";
+
+// The leading actor context arg; stripped from the client-facing method.
+// biome-ignore lint/suspicious/noExplicitAny: ctx is server-side only and never reaches the typed client surface.
+type Ctx = any;
+
+export interface DirEntry {
+	path: string;
+	type: "file" | "directory" | "symlink";
+	size: number;
+}
+
+export interface ReaddirEntry {
+	name: string;
+	isDirectory: boolean;
+	isSymbolicLink: boolean;
+}
+
+export interface SpawnedProcess {
+	pid: number;
+}
+
+export interface ExecActionOptions {
+	env?: Record<string, string>;
+	cwd?: string;
+}
+
+export interface SpawnActionOptions {
+	env?: Record<string, string>;
+	cwd?: string;
+	streamStdin?: boolean;
+}
+
+export interface ScheduledCronJob {
+	id: string;
+}
+
+export interface VmFetchOptions {
+	method?: string;
+	headers?: Record<string, string>;
+	body?: string | Uint8Array;
+}
+
+export interface VmFetchResponse {
+	status: number;
+	statusText: string;
+	headers: Record<string, string>;
+	body: Uint8Array;
+}
+
+export interface CreateSessionOptions {
+	cwd?: string;
+	env?: Record<string, string>;
+	skipOsInstructions?: boolean;
+	additionalInstructions?: string;
+}
+
+export interface SignedPreviewUrl {
+	path: string;
+	token: string;
+	port: number;
+	expiresAt: number;
+}
+
+export interface OpenShellActionOptions {
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	cwd?: string;
+	cols?: number;
+	rows?: number;
+}
+
+export interface OpenShellResult {
+	shellId: string;
+}
+
+export interface WriteFileResult {
+	path: string;
+	success: boolean;
+	error?: string;
+}
+
+export interface ReadFileResult {
+	path: string;
+	content?: Uint8Array;
+	error?: string;
+}
+
+export interface MountInfo {
+	path: string;
+	kind: "host_dir" | "s3" | "google_drive" | "sandbox_agent";
+	config: unknown;
+	readOnly: boolean;
+}
+
+export interface SoftwareInfo {
+	package: string;
+	kind: "wasm-commands" | "agent" | "tool";
+	version: string | null;
+	commands: string[];
+}
+
+export type AgentOsActions = {
+"#;
+
     pub fn decode_action_args(name: &str, args: &[u8]) -> Result<()> {
         match name {
             "readFile" => super::decode_as::<(String,)>(args).map(|_| ()),

crates/agentos-actor-plugin/src/bin/generate-ts-actions.rs

@@ -0,0 +1,51 @@
+use std::path::PathBuf;
+
+use agentos_actor_plugin::actions::contract;
+use anyhow::{bail, Context as _, Result};
+
+fn main() -> Result<()> {
+    let mut args = std::env::args().skip(1);
+    let command = args.next();
+    if args.next().is_some() {
+        bail!("usage: generate-ts-actions [--write|--check]");
+    }
+
+    let rendered = contract::render_actor_actions_ts();
+    match command.as_deref() {
+        Some("--write") => {
+            let path = generated_path();
+            let parent = path
+                .parent()
+                .context("generated actor actions path must have a parent")?;
+            std::fs::create_dir_all(parent)
+                .with_context(|| format!("create {}", parent.display()))?;
+            std::fs::write(&path, rendered).with_context(|| format!("write {}", path.display()))?;
+        }
+        Some("--check") => {
+            let path = generated_path();
+            let current = std::fs::read_to_string(&path)
+                .with_context(|| format!("read {}", path.display()))?;
+            if current != rendered {
+                bail!(
+                    "{} is stale; run `pnpm --dir packages/agentos generate:actions`",
+                    contract::GENERATED_ACTOR_ACTIONS_PATH
+                );
+            }
+        }
+        None => {
+            print!("{rendered}");
+        }
+        Some(other) => {
+            bail!("unknown argument {other}; usage: generate-ts-actions [--write|--check]")
+        }
+    }
+
+    Ok(())
+}
+
+fn generated_path() -> PathBuf {
+    let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    manifest_dir
+        .join("../..")
+        .join(contract::GENERATED_ACTOR_ACTIONS_PATH)
+}

crates/agentos-actor-plugin/tests/action_contract.rs

@@ -165,14 +165,14 @@ fn create_session_reply_is_bare_string_regression() {
 
 #[test]
 fn ts_action_interface_matches_rust_contract_fixture() {
-    let ts = include_str!("../../../packages/agentos/src/actor-actions.ts");
-    let normalized_ts = normalize_ws(ts);
+    let ts = contract::render_actor_actions_ts();
+    let normalized_ts = normalize_ws(&ts);
 
     for action in ACTION_CONTRACTS {
         let signature = normalize_ws(action.ts_signature);
         assert!(
             normalized_ts.contains(&signature),
-            "packages/agentos/src/actor-actions.ts signature drifted for {}.\nexpected snippet: {}",
+            "generated actor-actions signature drifted for {}.\nexpected snippet: {}",
             action.name,
             action.ts_signature
         );
@@ -197,7 +197,7 @@ fn ts_event_interface_matches_rust_contract_fixture() {
 
 #[test]
 fn ts_dto_field_names_match_rust_contract_fixture() {
-    let actor_actions = include_str!("../../../packages/agentos/src/actor-actions.ts");
+    let actor_actions = contract::render_actor_actions_ts();
     let actor_types = include_str!("../../../packages/agentos/src/types.ts");
     let core_agent_os = include_str!("../../../packages/core/src/agent-os.ts");
     let core_runtime = include_str!("../../../packages/core/src/runtime.ts");
@@ -260,20 +260,20 @@ fn ts_dto_field_names_match_rust_contract_fixture() {
         ),
         (
             "VmFetchResponse",
-            "packages/agentos/src/actor-actions.ts",
-            actor_actions,
+            "generated actor-actions",
+            &actor_actions,
             "export interface VmFetchResponse { status: number; statusText: string; headers: Record<string, string>; body: Uint8Array; }",
         ),
         (
             "WriteFileResult",
-            "packages/agentos/src/actor-actions.ts",
-            actor_actions,
+            "generated actor-actions",
+            &actor_actions,
             "export interface WriteFileResult { path: string; success: boolean; error?: string; }",
         ),
         (
             "ReadFileResult",
-            "packages/agentos/src/actor-actions.ts",
-            actor_actions,
+            "generated actor-actions",
+            &actor_actions,
             "export interface ReadFileResult { path: string; content?: Uint8Array; error?: string; }",
         ),
         (

packages/agentos/package.json

@@ -47,11 +47,12 @@
 		"node": ">=22.0.0"
 	},
 	"scripts": {
-		"build": "pnpm build:actor && pnpm build:tabs",
+		"generate:actions": "cargo run --quiet -p agentos-actor-plugin --bin generate-ts-actions -- --write",
+		"build": "pnpm generate:actions && pnpm build:actor && pnpm build:tabs",
 		"build:actor": "tsup src/index.ts src/client.ts src/react.ts",
 		"build:tabs": "vite build --config vite.tabs.config.ts",
-		"check-types": "tsc --noEmit",
-		"test": "vitest run"
+		"check-types": "pnpm generate:actions && tsc --noEmit",
+		"test": "pnpm generate:actions && vitest run"
 	},
 	"dependencies": {
 		"@agentos-software/common": "workspace:*",