refactor: replace actor tags with key-based identification

Author: NathanFlurry

CLAUDE.md

@@ -103,4 +103,4 @@ This ensures imports resolve correctly across different build environments and p
 - Ensure proper error handling with descriptive messages
 - Run `yarn check-types` regularly during development to catch type errors early. Prefer `yarn check-types` instead of `yarn build`.
 - Use `tsx` CLI to execute TypeScript scripts directly (e.g., `tsx script.ts` instead of `node script.js`).
-
+- Do not auto-commit changes

examples/chat-room/scripts/cli.ts

@@ -10,8 +10,7 @@ async function main() {
 
 	// connect to chat room - now accessed via property
 	// can still pass parameters like room
-	const chatRoom = await client.chatRoom.get({
-		tags: { room },
+	const chatRoom = await client.chatRoom.connect(room, {
 		params: { room },
 	});
 

examples/chat-room/scripts/connect.ts

@@ -7,7 +7,7 @@ async function main() {
 	const client = createClient<App>(process.env.ENDPOINT ?? "http://localhost:6420");
 
 	// connect to chat room - now accessed via property
-	const chatRoom = await client.chatRoom.get();
+	const chatRoom = await client.chatRoom.connect();
 
 	// call action to get existing messages
 	const messages = await chatRoom.getHistory();

examples/chat-room/tests/chat-room.test.ts

@@ -6,7 +6,7 @@ test("chat room should handle messages", async (test) => {
 	const { client } = await setupTest(test, app);
 
 	// Connect to chat room
-	const chatRoom = await client.chatRoom.get();
+	const chatRoom = await client.chatRoom.connect();
 
 	// Initial history should be empty
 	const initialMessages = await chatRoom.getHistory();

examples/counter/scripts/connect.ts

@@ -5,7 +5,7 @@ import type { App } from "../actors/app";
 async function main() {
 	const client = createClient<App>(process.env.ENDPOINT ?? "http://localhost:6420");
 
-	const counter = await client.counter.get()
+	const counter = await client.counter.connect()
 
 	counter.on("newCount", (count: number) => console.log("Event:", count));
 

examples/counter/tests/counter.test.ts

@@ -4,7 +4,7 @@ import { app } from "../actors/app";
 
 test("it should count", async (test) => {
 	const { client } = await setupTest(test, app);
-	const counter = await client.counter.get();
+	const counter = await client.counter.connect();
 
 	// Test initial count
 	expect(await counter.getCount()).toBe(0);

examples/linear-coding-agent/src/actors/coding-agent/mod.ts

@@ -406,8 +406,8 @@ export const codingAgent = actor({
 
 	// Handle actor instantiation
 	onCreate: (c) => {
-		console.log(`[ACTOR] Created actor instance with tags: ${JSON.stringify(c.tags)}`);
-		updateDebugState(c, "Actor created", `with tags: ${JSON.stringify(c.tags)}`);
+		console.log(`[ACTOR] Created actor instance with key: ${JSON.stringify(c.key)}`);
+		updateDebugState(c, "Actor created", `with key: ${JSON.stringify(c.key)}`);
 	},
 
 	// Handle actor start

examples/linear-coding-agent/src/server/index.ts

@@ -72,12 +72,10 @@ server.post('/api/webhook/linear', async (c) => {
       return c.json({ status: 'error', statusEmoji: '❌', message: 'No issue ID found in webhook event' }, 400);
     }
 
-    // Create or get a coding agent instance with the issue ID as a tag
+    // Create or get a coding agent instance with the issue ID as a key
     // This ensures each issue gets its own actor instance
     console.log(`[SERVER] Getting actor for issue: ${issueId}`);
-    const actorClient = await client.codingAgent.get({
-      tags: { issueId },
-    });
+    const actorClient = await client.codingAgent.connect(issueId);
 
     // Initialize the agent if needed
     console.log(`[SERVER] Initializing actor for issue: ${issueId}`);

examples/resend-streaks/tests/user.test.ts

@@ -26,7 +26,7 @@ beforeEach(() => {
 
 test("streak tracking with time zone signups", async (t) => {
 	const { client } = await setupTest(t, app);
-	const actor = await client.user.get();
+	const actor = await client.user.connect();
 
 	// Sign up with specific time zone
 	const signupResult = await actor.completeSignUp(

packages/actor-core/src/actor/action.ts

@@ -1,7 +1,7 @@
 import type { AnyActorInstance } from "./instance";
 import type { Conn } from "./connection";
 import type { Logger } from "@/common/log";
-import type { ActorTags } from "@/common/utils";
+import type { ActorKey } from "@/common/utils";
 import type { Schedule } from "./schedule";
 import type { ConnId } from "./connection";
 import type { SaveStateOptions } from "./instance";
@@ -65,10 +65,10 @@ export class ActionContext<S, CP, CS, V> {
 	}
 
 	/**
-	 * Gets the actor tags.
+	 * Gets the actor key.
 	 */
-	get tags(): ActorTags {
-		return this.#actorContext.tags;
+	get key(): ActorKey {
+		return this.#actorContext.key;
 	}
 
 	/**