refactor: replace actor tags with key-based identification

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;
 	}
 
 	/**

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

@@ -2,7 +2,7 @@ import { Logger } from "@/common/log";
 import { Actions } from "./config";
 import { ActorInstance, SaveStateOptions } from "./instance";
 import { Conn, ConnId } from "./connection";
-import { ActorTags } from "@/common/utils";
+import { ActorKey } from "@/common/utils";
 import { Schedule } from "./schedule";
 
 
@@ -58,11 +58,11 @@ export class ActorContext<S, CP, CS, V> {
 	}
 
 	/**
-	 * Gets the actor tags.
+	 * Gets the actor key.
 	 */
-	get tags(): ActorTags {
+	get key(): ActorKey {
 		// @ts-ignore - Access protected method
-		return this.#actor.tags;
+		return this.#actor.key;
 	}
 
 	/**

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

@@ -1,6 +1,6 @@
 import type { Logger } from "@/common//log";
 import {
-	type ActorTags,
+	type ActorKey,
 	isJsonSerializable,
 	stringifyError,
 } from "@/common//utils";
@@ -109,7 +109,7 @@ export class ActorInstance<S, CP, CS, V> {
 	#actorDriver!: ActorDriver;
 	#actorId!: string;
 	#name!: string;
-	#tags!: ActorTags;
+	#key!: ActorKey;
 	#region!: string;
 	#ready = false;
 
@@ -145,14 +145,14 @@ export class ActorInstance<S, CP, CS, V> {
 		actorDriver: ActorDriver,
 		actorId: string,
 		name: string,
-		tags: ActorTags,
+		key: ActorKey,
 		region: string,
 	) {
 		this.#connectionDrivers = connectionDrivers;
 		this.#actorDriver = actorDriver;
 		this.#actorId = actorId;
 		this.#name = name;
-		this.#tags = tags;
+		this.#key = key;
 		this.#region = region;
 		this.#schedule = new Schedule(this);
 		this.inspector = new ActorInspector(this);
@@ -954,10 +954,10 @@ export class ActorInstance<S, CP, CS, V> {
 	}
 
 	/**
-	 * Gets the tags.
+	 * Gets the key.
 	 */
-	get tags(): ActorTags {
-		return this.#tags;
+	get key(): ActorKey {
+		return this.#key;
 	}
 
 	/**

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

@@ -12,9 +12,10 @@ export type { Conn } from "./connection";
 export type { ActionContext } from "./action";
 export type { ActorConfig, OnConnectOptions } from "./config";
 export type { Encoding } from "@/actor/protocol/serde";
-export type { ActorTags } from "@/common/utils";
+export type { ActorKey } from "@/common/utils";
 export type {
 	ActorDefinition,
+	AnyActorDefinition,
 	ActorContextOf,
 	ActionContextOf,
 } from "./definition";