diff --git a/.changeset/config.json b/.changeset/config.json
index bed0f3c..a722d25 100644
--- a/.changeset/config.json
+++ b/.changeset/config.json
@@ -1,11 +1,18 @@
{
"$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
- "changelog": ["./changelog-formatter.js", { "repo": "plotday/plot" }],
+ "changelog": [
+ "./changelog-formatter.js",
+ {
+ "repo": "plotday/plot"
+ }
+ ],
"commit": false,
"fixed": [],
"linked": [],
"access": "public",
"baseBranch": "main",
"updateInternalDependencies": "patch",
- "ignore": ["@plotday/agent-*"]
+ "ignore": [
+ "@plotday/twist-*"
+ ]
}
diff --git a/.changeset/silver-eagles-grow.md b/.changeset/silver-eagles-grow.md
new file mode 100644
index 0000000..b4df3ed
--- /dev/null
+++ b/.changeset/silver-eagles-grow.md
@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Changed: BREAKING: Renamed to @plotday/twister
diff --git a/README.md b/README.md
index 23027f2..7f34546 100644
--- a/README.md
+++ b/README.md
@@ -4,42 +4,42 @@
- Plot Agent Builder
+ 🌪️ Twister, the Plot Twist Creator
- The official package for building Plot agents -
- custom code that organizes and prioritizes all your messages, tasks, and apps.
+ The official package for building Plot twists -
+ smart automations that organize and prioritize all your tasks, messages, and documents from all your apps and agents.
## Packages
-- **[@plotday/agent](./builder)** - Core agent builder package with the `plot` command, agent and tool SDK, and built-in tools
-- **[tools/](./tools)** - Additional tools for building agents, including integrations with popular services
-- **[agents/](./agents)** - Full source code for several agents
+- **[@plotday/twister](./twister)** - Core twist creator package with the `plot` command, twist and tool SDK, and built-in tools
+- **[tools/](./tools)** - Additional tools for building twists, including integrations with popular services
+- **[twists/](./twists)** - Full source code for several twists
## Quick Start
-You'll need a [Plot account](https://plot.day) to deploy agents.
+You'll need a [Plot account](https://plot.day) to deploy twists.
```bash
-# Create a new agent
-npx @plotday/agent create
+# Create a new twist
+npx @plotday/twister create
# Connect your Plot account
-npx @plotday/agent login
+npx @plotday/twister login
-# Deploy your agent
-cd my-agent
+# Deploy your twist
+cd my-twist
npm run deploy
```
## Documentation
-See the [Agent Builder documentation](https://build.plot.day) for detailed guides and API reference.
+See the [Twist Creator documentation](https://build.plot.day) for detailed guides and API reference.
## Changelog
-See the [Agent Builder changelog](./builder/CHANGELOG.md) for version history and release notes.
+See the [Twister changelog](./twister/CHANGELOG.md) for version history and release notes.
## License
diff --git a/RELEASING.md b/RELEASING.md
index 5f27ce4..b6d6fdf 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -4,9 +4,9 @@ This repository uses [Changesets](https://github.com/changesets/changesets) to m
## Package Versioning Strategy
-- **Agent Builder** (`@plotday/agent`): Independent versioning
+- **Twist Creator** (`@plotday/twister`): Independent versioning
- **Tools** (`@plotday/tool-*`): Independent versioning
-- **Agents** (`@plotday/agent-*`): Not published, excluded from releases
+- **Twists** (`@plotday/twist-*`): Not published, excluded from releases
Each package maintains its own version and can be released independently.
@@ -25,7 +25,7 @@ This will prompt you with:
1. **Which packages would you like to include?**
- Select the packages you've modified (use space to select, enter to confirm)
- - Only builder and tools packages can be selected (agents are excluded)
+ - Only builder and tools packages can be selected (twists are excluded)
2. **What kind of change is this?**
@@ -79,7 +79,7 @@ The changeset file will be created in `.changeset/` with a random name like `.ch
- Builds all packages
- Publishes changed packages to npm
- Creates GitHub releases with changelogs
- - Tags each release (e.g., `agent@0.9.1`, `tool-google-calendar@0.1.0`)
+ - Tags each release (e.g., `twister@0.9.1`, `tool-google-calendar@0.1.0`)
## GitHub Releases
@@ -89,7 +89,7 @@ When packages are published, GitHub releases are automatically created with the
Each package gets its own tag based on its directory structure:
-- **Agent Builder**: `agent@0.9.1`
+- **Twist Creator**: `twister@0.9.1`
- **Tools**: `tool-google-calendar@0.1.0`, `tool-outlook-calendar@0.1.0`, etc.
This tagging convention allows you to:
@@ -102,7 +102,7 @@ This tagging convention allows you to:
Each GitHub release includes:
-- **Title**: Package name and version (e.g., `@plotday/agent@0.9.1`)
+- **Title**: Package name and version (e.g., `@plotday/twister@0.9.1`)
- **Release Notes**: Automatically extracted from the package's CHANGELOG.md for that version
- **Assets**: None (packages are distributed via npm)
@@ -112,7 +112,7 @@ View all releases at: `https://github.com/plotday/plot/releases`
Or filter by package:
-- Builder releases: Search for tags starting with `agent@`
+- Builder releases: Search for tags starting with `twister@`
- Tool releases: Search for tags starting with `tool-`
### Manual GitHub Release
@@ -120,8 +120,8 @@ Or filter by package:
If you need to create a GitHub release manually after publishing:
```bash
-# For Agent Builder
-gh release create agent@0.9.1 --title "@plotday/agent@0.9.1" --notes "Release notes here"
+# For Twist Creator
+gh release create twister@0.9.1 --title "@plotday/twister@0.9.1" --notes "Release notes here"
# For a tool
gh release create tool-google-calendar@0.1.0 --title "@plotday/tool-google-calendar@0.1.0" --notes "Release notes here"
@@ -136,7 +136,7 @@ gh release create tool-google-calendar@0.1.0 --title "@plotday/tool-google-calen
```
- Fix calendar sync race condition causing duplicate events
- Add support for recurring events in Google Calendar integration
-- BREAKING: Remove deprecated `createAgent()` function
+- BREAKING: Remove deprecated `createTwist()` function
```
**Bad examples:**
@@ -198,7 +198,7 @@ git push
pnpm release
# 5. (Optional) Create GitHub release manually
-gh release create agent@0.9.1 --title "@plotday/agent@0.9.1" --notes "Release notes"
+gh release create twister@0.9.1 --title "@plotday/twister@0.9.1" --notes "Release notes"
```
⚠️ This should only be done in emergencies. The automated workflow is preferred.
@@ -211,8 +211,8 @@ gh release create agent@0.9.1 --title "@plotday/agent@0.9.1" --notes "Release no
### Changeset not detecting my package
-**Problem:** You modified an agent package.
-**Solution:** Agents are excluded from releases. No changeset needed for agent-only changes.
+**Problem:** You modified a twist package.
+**Solution:** Twists are excluded from releases. No changeset needed for twist-only changes.
### Version Packages PR has conflicts
diff --git a/builder/src/agents-guide.ts b/builder/src/agents-guide.ts
deleted file mode 100644
index 54f8721..0000000
--- a/builder/src/agents-guide.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-/**
- * Agent Implementation Guide
- *
- * This guide is used by AI systems to generate Plot agents.
- * Auto-generated from cli/templates/AGENTS.template.md during build.
- */
-
-import agentsGuideTemplate from "./llm-docs/agents-guide-template.js";
-
-export const AGENTS_GUIDE = agentsGuideTemplate;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8901fa3..b710448 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -24,52 +24,57 @@ importers:
specifier: ^5.9.3
version: 5.9.3
- agents/chat:
+ tools/gmail:
dependencies:
- '@plotday/agent':
+ '@plotday/twister':
specifier: workspace:^
- version: link:../../builder
- typebox:
- specifier: ^1.0.35
- version: 1.0.35
+ version: link:../../twister
devDependencies:
typescript:
specifier: ^5.9.3
version: 5.9.3
- agents/events:
+ tools/google-calendar:
dependencies:
- '@plotday/agent':
- specifier: workspace:^
- version: link:../../builder
- '@plotday/tool-google-calendar':
+ '@plotday/twister':
specifier: workspace:^
- version: link:../../tools/google-calendar
- '@plotday/tool-outlook-calendar':
+ version: link:../../twister
+ devDependencies:
+ typescript:
+ specifier: ^5.9.3
+ version: 5.9.3
+
+ tools/google-contacts:
+ dependencies:
+ '@plotday/twister':
specifier: workspace:^
- version: link:../../tools/outlook-calendar
+ version: link:../../twister
devDependencies:
typescript:
specifier: ^5.9.3
version: 5.9.3
- agents/message-tasks:
+ tools/outlook-calendar:
dependencies:
- '@plotday/agent':
+ '@plotday/twister':
specifier: workspace:^
- version: link:../../builder
- '@plotday/tool-slack':
+ version: link:../../twister
+ devDependencies:
+ typescript:
+ specifier: ^5.9.3
+ version: 5.9.3
+
+ tools/slack:
+ dependencies:
+ '@plotday/twister':
specifier: workspace:^
- version: link:../../tools/slack
- typebox:
- specifier: ^1.0.35
- version: 1.0.35
+ version: link:../../twister
devDependencies:
typescript:
specifier: ^5.9.3
version: 5.9.3
- builder:
+ twister:
dependencies:
chalk:
specifier: ^4.1.2
@@ -106,51 +111,46 @@ importers:
specifier: ^5.9.3
version: 5.9.3
- tools/gmail:
+ twists/calendar-sync:
dependencies:
- '@plotday/agent':
+ '@plotday/tool-google-calendar':
specifier: workspace:^
- version: link:../../builder
- devDependencies:
- typescript:
- specifier: ^5.9.3
- version: 5.9.3
-
- tools/google-calendar:
- dependencies:
- '@plotday/agent':
+ version: link:../../tools/google-calendar
+ '@plotday/tool-outlook-calendar':
specifier: workspace:^
- version: link:../../builder
- devDependencies:
- typescript:
- specifier: ^5.9.3
- version: 5.9.3
-
- tools/google-contacts:
- dependencies:
- '@plotday/agent':
+ version: link:../../tools/outlook-calendar
+ '@plotday/twister':
specifier: workspace:^
- version: link:../../builder
+ version: link:../../twister
devDependencies:
typescript:
specifier: ^5.9.3
version: 5.9.3
- tools/outlook-calendar:
+ twists/chat:
dependencies:
- '@plotday/agent':
+ '@plotday/twister':
specifier: workspace:^
- version: link:../../builder
+ version: link:../../twister
+ typebox:
+ specifier: ^1.0.35
+ version: 1.0.35
devDependencies:
typescript:
specifier: ^5.9.3
version: 5.9.3
- tools/slack:
+ twists/message-tasks:
dependencies:
- '@plotday/agent':
+ '@plotday/tool-slack':
+ specifier: workspace:^
+ version: link:../../tools/slack
+ '@plotday/twister':
specifier: workspace:^
- version: link:../../builder
+ version: link:../../twister
+ typebox:
+ specifier: ^1.0.35
+ version: 1.0.35
devDependencies:
typescript:
specifier: ^5.9.3
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 5f9e879..8ef7d4d 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,7 +1,7 @@
packages:
- - builder
+ - twister
- tools/*
- - agents/*
+ - twists/*
onlyBuiltDependencies:
- esbuild
diff --git a/tools/gmail/package.json b/tools/gmail/package.json
index 5d1b4e8..48e4f3e 100644
--- a/tools/gmail/package.json
+++ b/tools/gmail/package.json
@@ -24,7 +24,7 @@
"clean": "rm -rf dist"
},
"dependencies": {
- "@plotday/agent": "workspace:^"
+ "@plotday/twister": "workspace:^"
},
"devDependencies": {
"typescript": "^5.9.3"
diff --git a/tools/gmail/src/gmail-api.ts b/tools/gmail/src/gmail-api.ts
index ef7af66..9eb6bd5 100644
--- a/tools/gmail/src/gmail-api.ts
+++ b/tools/gmail/src/gmail-api.ts
@@ -1,5 +1,5 @@
-import type { NewActivity } from "@plotday/agent";
-import { ActivityLinkType, ActivityType } from "@plotday/agent";
+import type { NewActivity } from "@plotday/twister";
+import { ActivityLinkType, ActivityType } from "@plotday/twister";
export type GmailLabel = {
id: string;
diff --git a/tools/gmail/src/gmail.ts b/tools/gmail/src/gmail.ts
index 2d731ab..bd30461 100644
--- a/tools/gmail/src/gmail.ts
+++ b/tools/gmail/src/gmail.ts
@@ -3,22 +3,22 @@ import {
type ActivityLink,
Tool,
type ToolBuilder,
-} from "@plotday/agent";
+} from "@plotday/twister";
import {
type MessageChannel,
type MessageSyncOptions,
type MessagingAuth,
type MessagingTool,
-} from "@plotday/agent/common/messaging";
-import { type Callback } from "@plotday/agent/tools/callbacks";
+} from "@plotday/twister/common/messaging";
+import { type Callback } from "@plotday/twister/tools/callbacks";
import {
AuthLevel,
AuthProvider,
type Authorization,
Integrations,
-} from "@plotday/agent/tools/integrations";
-import { Network, type WebhookRequest } from "@plotday/agent/tools/network";
-import { ActivityAccess, ContactAccess, Plot } from "@plotday/agent/tools/plot";
+} from "@plotday/twister/tools/integrations";
+import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
+import { ActivityAccess, ContactAccess, Plot } from "@plotday/twister/tools/plot";
import {
GmailApi,
@@ -39,7 +39,7 @@ import {
*
* @example
* ```typescript
- * class MessagesAgent extends Agent {
+ * class MessagesTwist extends Twist {
* private gmail: Gmail;
*
* constructor(id: string, tools: Tools) {
diff --git a/tools/gmail/tsconfig.json b/tools/gmail/tsconfig.json
index f207561..b98a116 100644
--- a/tools/gmail/tsconfig.json
+++ b/tools/gmail/tsconfig.json
@@ -1,6 +1,6 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
- "extends": "@plotday/agent/tsconfig.base.json",
+ "extends": "@plotday/twister/tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist"
},
diff --git a/tools/google-calendar/CHANGELOG.md b/tools/google-calendar/CHANGELOG.md
index 59d1be5..2bf709a 100644
--- a/tools/google-calendar/CHANGELOG.md
+++ b/tools/google-calendar/CHANGELOG.md
@@ -39,7 +39,7 @@
### Changed
- BREAKING: Creating and updating Activity using the Plot tool now requires requesting permission in options ([#51](https://github.com/plotday/plot/pull/51) [`b3242e4`](https://github.com/plotday/plot/commit/b3242e4adecea87011379ac2dd58712dc91729d7))
-- BREAKING: Agents and Tools now define a build() method to gain access to tools, which are then available via this.tools.
+- BREAKING: Twists and Tools now define a build() method to gain access to tools, which are then available via this.tools.
- BREAKING: Improved callback ergonomics and types to use functions instead of strings ([#51](https://github.com/plotday/plot/pull/51) [`02c6a1e`](https://github.com/plotday/plot/commit/02c6a1e834b9aa645f29191ed59ee5b66b70c32a))
- Update for new callback function names ([#51](https://github.com/plotday/plot/pull/51) [`49b4dc9`](https://github.com/plotday/plot/commit/49b4dc94e08906a89799903610325c5fe7ebe10b))
- Updated dependencies:
@@ -87,7 +87,7 @@
### Fixed
-- Several instances of Agents and Tools missing the id argument ([#24](https://github.com/plotday/plot/pull/24) [`2d53d37`](https://github.com/plotday/plot/commit/2d53d3794419ee218976d6468319ae9129c93088))
+- Several instances of Twists and Tools missing the id argument ([#24](https://github.com/plotday/plot/pull/24) [`2d53d37`](https://github.com/plotday/plot/commit/2d53d3794419ee218976d6468319ae9129c93088))
## 0.1.5
diff --git a/tools/google-calendar/README.md b/tools/google-calendar/README.md
index 64d923d..bd9c47b 100644
--- a/tools/google-calendar/README.md
+++ b/tools/google-calendar/README.md
@@ -5,17 +5,17 @@ A Plot tool for syncing with Google Calendar.
## Installation
```bash
-npm install @plotday/tool-google-calendar @plotday/agent
+npm install @plotday/tool-google-calendar @plotday/twister
```
## Usage
```typescript
-import { Agent, Tools } from "@plotday/agent";
+import { Twist, Tools } from "@plotday/twister";
import { GoogleCalendar } from "@plotday/tool-google-calendar";
-import { Integrations, AuthLevel, AuthProvider } from "@plotday/agent/tools/integrations";
+import { Integrations, AuthLevel, AuthProvider } from "@plotday/twister/tools/integrations";
-export default class extends Agent {
+export default class extends Twist {
private googleCalendar: GoogleCalendar;
private auth: Integrations;
diff --git a/tools/google-calendar/package.json b/tools/google-calendar/package.json
index 1824bca..c57fd4c 100644
--- a/tools/google-calendar/package.json
+++ b/tools/google-calendar/package.json
@@ -24,7 +24,7 @@
"clean": "rm -rf dist"
},
"dependencies": {
- "@plotday/agent": "workspace:^"
+ "@plotday/twister": "workspace:^"
},
"devDependencies": {
"typescript": "^5.9.3"
diff --git a/tools/google-calendar/src/google-api.ts b/tools/google-calendar/src/google-api.ts
index d514f62..b5c6bd4 100644
--- a/tools/google-calendar/src/google-api.ts
+++ b/tools/google-calendar/src/google-api.ts
@@ -1,5 +1,5 @@
-import type { NewActivity } from "@plotday/agent";
-import { ActivityType, ConferencingProvider } from "@plotday/agent";
+import type { NewActivity } from "@plotday/twister";
+import { ActivityType, ConferencingProvider } from "@plotday/twister";
export type GoogleEvent = {
id: string;
diff --git a/tools/google-calendar/src/google-calendar.ts b/tools/google-calendar/src/google-calendar.ts
index 6c6dfba..10113ef 100644
--- a/tools/google-calendar/src/google-calendar.ts
+++ b/tools/google-calendar/src/google-calendar.ts
@@ -9,25 +9,25 @@ import {
Tag,
Tool,
type ToolBuilder,
-} from "@plotday/agent";
+} from "@plotday/twister";
import {
type Calendar,
type CalendarAuth,
type CalendarTool,
-} from "@plotday/agent/common/calendar";
-import { type Callback } from "@plotday/agent/tools/callbacks";
+} from "@plotday/twister/common/calendar";
+import { type Callback } from "@plotday/twister/tools/callbacks";
import {
AuthLevel,
AuthProvider,
type Authorization,
Integrations,
-} from "@plotday/agent/tools/integrations";
-import { Network, type WebhookRequest } from "@plotday/agent/tools/network";
+} from "@plotday/twister/tools/integrations";
+import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
import {
ActivityAccess,
ContactAccess,
Plot,
-} from "@plotday/agent/tools/plot";
+} from "@plotday/twister/tools/plot";
import {
extractConferencingLinks,
@@ -59,7 +59,7 @@ import {
*
* @example
* ```typescript
- * class EventsAgent extends Agent {
+ * class CalendarSyncTwist extends Twist {
* private googleCalendar: GoogleCalendar;
*
* constructor(id: string, tools: Tools) {
diff --git a/tools/google-calendar/tsconfig.json b/tools/google-calendar/tsconfig.json
index f207561..b98a116 100644
--- a/tools/google-calendar/tsconfig.json
+++ b/tools/google-calendar/tsconfig.json
@@ -1,6 +1,6 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
- "extends": "@plotday/agent/tsconfig.base.json",
+ "extends": "@plotday/twister/tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist"
},
diff --git a/tools/google-contacts/CHANGELOG.md b/tools/google-contacts/CHANGELOG.md
index a747fd9..bfa6a92 100644
--- a/tools/google-contacts/CHANGELOG.md
+++ b/tools/google-contacts/CHANGELOG.md
@@ -31,7 +31,7 @@
### Changed
- BREAKING: Creating and updating Activity using the Plot tool now requires requesting permission in options ([#51](https://github.com/plotday/plot/pull/51) [`b3242e4`](https://github.com/plotday/plot/commit/b3242e4adecea87011379ac2dd58712dc91729d7))
-- BREAKING: Agents and Tools now define a build() method to gain access to tools, which are then available via this.tools.
+- BREAKING: Twists and Tools now define a build() method to gain access to tools, which are then available via this.tools.
- BREAKING: Improved callback ergonomics and types to use functions instead of strings ([#51](https://github.com/plotday/plot/pull/51) [`02c6a1e`](https://github.com/plotday/plot/commit/02c6a1e834b9aa645f29191ed59ee5b66b70c32a))
- Update for new callback function names ([#51](https://github.com/plotday/plot/pull/51) [`49b4dc9`](https://github.com/plotday/plot/commit/49b4dc94e08906a89799903610325c5fe7ebe10b))
- Updated dependencies:
@@ -78,7 +78,7 @@
### Fixed
-- Several instances of Agents and Tools missing the id argument ([#24](https://github.com/plotday/plot/pull/24) [`2d53d37`](https://github.com/plotday/plot/commit/2d53d3794419ee218976d6468319ae9129c93088))
+- Several instances of Twists and Tools missing the id argument ([#24](https://github.com/plotday/plot/pull/24) [`2d53d37`](https://github.com/plotday/plot/commit/2d53d3794419ee218976d6468319ae9129c93088))
## 0.1.5
diff --git a/tools/google-contacts/README.md b/tools/google-contacts/README.md
index 8ef1c16..39534f8 100644
--- a/tools/google-contacts/README.md
+++ b/tools/google-contacts/README.md
@@ -5,17 +5,17 @@ A Plot tool for syncing with Google Contacts.
## Installation
```bash
-npm install @plotday/tool-google-contacts @plotday/agent
+npm install @plotday/tool-google-contacts @plotday/twister
```
## Usage
```typescript
-import { Agent, Tools } from "@plotday/agent";
+import { Twist, Tools } from "@plotday/twister";
import { GoogleContacts } from "@plotday/tool-google-contacts";
-import { Integrations, AuthLevel, AuthProvider } from "@plotday/agent/tools/integrations";
+import { Integrations, AuthLevel, AuthProvider } from "@plotday/twister/tools/integrations";
-export default class extends Agent {
+export default class extends Twist {
private googleContacts: GoogleContacts;
private auth: Integrations;
diff --git a/tools/google-contacts/package.json b/tools/google-contacts/package.json
index 674d968..35e5282 100644
--- a/tools/google-contacts/package.json
+++ b/tools/google-contacts/package.json
@@ -24,7 +24,7 @@
"clean": "rm -rf dist"
},
"dependencies": {
- "@plotday/agent": "workspace:^"
+ "@plotday/twister": "workspace:^"
},
"devDependencies": {
"typescript": "^5.9.3"
diff --git a/tools/google-contacts/src/google-contacts.ts b/tools/google-contacts/src/google-contacts.ts
index 4c0167c..dace49b 100644
--- a/tools/google-contacts/src/google-contacts.ts
+++ b/tools/google-contacts/src/google-contacts.ts
@@ -1,12 +1,12 @@
-import { Tool, type ToolBuilder } from "@plotday/agent";
-import { type Callback } from "@plotday/agent/tools/callbacks";
+import { Tool, type ToolBuilder } from "@plotday/twister";
+import { type Callback } from "@plotday/twister/tools/callbacks";
import {
AuthLevel,
AuthProvider,
type AuthToken,
type Authorization,
Integrations,
-} from "@plotday/agent/tools/integrations";
+} from "@plotday/twister/tools/integrations";
import type {
Contact,
diff --git a/tools/google-contacts/src/types.ts b/tools/google-contacts/src/types.ts
index 33fddec..1bb19ae 100644
--- a/tools/google-contacts/src/types.ts
+++ b/tools/google-contacts/src/types.ts
@@ -1,4 +1,4 @@
-import type { ActivityLink, ITool } from "@plotday/agent";
+import type { ActivityLink, ITool } from "@plotday/twister";
export type Contact = {
email: string;
diff --git a/tools/google-contacts/tsconfig.json b/tools/google-contacts/tsconfig.json
index f207561..b98a116 100644
--- a/tools/google-contacts/tsconfig.json
+++ b/tools/google-contacts/tsconfig.json
@@ -1,6 +1,6 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
- "extends": "@plotday/agent/tsconfig.base.json",
+ "extends": "@plotday/twister/tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist"
},
diff --git a/tools/outlook-calendar/CHANGELOG.md b/tools/outlook-calendar/CHANGELOG.md
index 4722ee8..9ae04b7 100644
--- a/tools/outlook-calendar/CHANGELOG.md
+++ b/tools/outlook-calendar/CHANGELOG.md
@@ -31,7 +31,7 @@
### Changed
- BREAKING: Creating and updating Activity using the Plot tool now requires requesting permission in options ([#51](https://github.com/plotday/plot/pull/51) [`b3242e4`](https://github.com/plotday/plot/commit/b3242e4adecea87011379ac2dd58712dc91729d7))
-- BREAKING: Agents and Tools now define a build() method to gain access to tools, which are then available via this.tools.
+- BREAKING: Twists and Tools now define a build() method to gain access to tools, which are then available via this.tools.
- BREAKING: Improved callback ergonomics and types to use functions instead of strings ([#51](https://github.com/plotday/plot/pull/51) [`02c6a1e`](https://github.com/plotday/plot/commit/02c6a1e834b9aa645f29191ed59ee5b66b70c32a))
- Update for new callback function names ([#51](https://github.com/plotday/plot/pull/51) [`49b4dc9`](https://github.com/plotday/plot/commit/49b4dc94e08906a89799903610325c5fe7ebe10b))
- Updated dependencies:
@@ -79,7 +79,7 @@
### Fixed
-- Several instances of Agents and Tools missing the id argument ([#24](https://github.com/plotday/plot/pull/24) [`2d53d37`](https://github.com/plotday/plot/commit/2d53d3794419ee218976d6468319ae9129c93088))
+- Several instances of Twists and Tools missing the id argument ([#24](https://github.com/plotday/plot/pull/24) [`2d53d37`](https://github.com/plotday/plot/commit/2d53d3794419ee218976d6468319ae9129c93088))
## 0.1.5
diff --git a/tools/outlook-calendar/README.md b/tools/outlook-calendar/README.md
index c0b0906..856e235 100644
--- a/tools/outlook-calendar/README.md
+++ b/tools/outlook-calendar/README.md
@@ -5,17 +5,17 @@ A Plot tool for syncing with Microsoft Outlook Calendar (Microsoft 365).
## Installation
```bash
-npm install @plotday/tool-outlook-calendar @plotday/agent
+npm install @plotday/tool-outlook-calendar @plotday/twister
```
## Usage
```typescript
-import { Agent, Tools } from "@plotday/agent";
+import { Twist, Tools } from "@plotday/twister";
import { OutlookCalendar } from "@plotday/tool-outlook-calendar";
-import { Integrations, AuthLevel, AuthProvider } from "@plotday/agent/tools/integrations";
+import { Integrations, AuthLevel, AuthProvider } from "@plotday/twister/tools/integrations";
-export default class extends Agent {
+export default class extends Twist {
private outlookCalendar: OutlookCalendar;
private auth: Integrations;
diff --git a/tools/outlook-calendar/package.json b/tools/outlook-calendar/package.json
index 98481ce..50c65ec 100644
--- a/tools/outlook-calendar/package.json
+++ b/tools/outlook-calendar/package.json
@@ -24,7 +24,7 @@
"clean": "rm -rf dist"
},
"dependencies": {
- "@plotday/agent": "workspace:^"
+ "@plotday/twister": "workspace:^"
},
"devDependencies": {
"typescript": "^5.9.3"
diff --git a/tools/outlook-calendar/src/graph-api.ts b/tools/outlook-calendar/src/graph-api.ts
index edfc6c6..940f7d5 100644
--- a/tools/outlook-calendar/src/graph-api.ts
+++ b/tools/outlook-calendar/src/graph-api.ts
@@ -1,6 +1,6 @@
-import type { NewActivity } from "@plotday/agent";
-import { ActivityType } from "@plotday/agent";
-import type { Calendar } from "@plotday/agent/common/calendar";
+import type { NewActivity } from "@plotday/twister";
+import { ActivityType } from "@plotday/twister";
+import type { Calendar } from "@plotday/twister/common/calendar";
/**
* Microsoft Graph API event type
diff --git a/tools/outlook-calendar/src/outlook-calendar.ts b/tools/outlook-calendar/src/outlook-calendar.ts
index 7b9e7e1..c4bb0ec 100644
--- a/tools/outlook-calendar/src/outlook-calendar.ts
+++ b/tools/outlook-calendar/src/outlook-calendar.ts
@@ -9,25 +9,25 @@ import {
Tag,
Tool,
type ToolBuilder,
-} from "@plotday/agent";
+} from "@plotday/twister";
import type {
Calendar,
CalendarAuth,
CalendarTool,
-} from "@plotday/agent/common/calendar";
-import { type Callback } from "@plotday/agent/tools/callbacks";
+} from "@plotday/twister/common/calendar";
+import { type Callback } from "@plotday/twister/tools/callbacks";
import {
AuthLevel,
AuthProvider,
type Authorization,
Integrations,
-} from "@plotday/agent/tools/integrations";
-import { Network, type WebhookRequest } from "@plotday/agent/tools/network";
+} from "@plotday/twister/tools/integrations";
+import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
import {
ActivityAccess,
ContactAccess,
Plot,
-} from "@plotday/agent/tools/plot";
+} from "@plotday/twister/tools/plot";
import {
GraphApi,
syncOutlookCalendar,
@@ -87,7 +87,7 @@ type WatchState = {
*
* @example
* ```typescript
- * class EventsAgent extends Agent {
+ * class CalendarSyncTwist extends Twist {
* private outlookCalendar: OutlookCalendar;
*
* constructor(id: string, tools: Tools) {
diff --git a/tools/outlook-calendar/tsconfig.json b/tools/outlook-calendar/tsconfig.json
index f207561..b98a116 100644
--- a/tools/outlook-calendar/tsconfig.json
+++ b/tools/outlook-calendar/tsconfig.json
@@ -1,6 +1,6 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
- "extends": "@plotday/agent/tsconfig.base.json",
+ "extends": "@plotday/twister/tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist"
},
diff --git a/tools/slack/package.json b/tools/slack/package.json
index faa7aa8..cd783a9 100644
--- a/tools/slack/package.json
+++ b/tools/slack/package.json
@@ -24,7 +24,7 @@
"clean": "rm -rf dist"
},
"dependencies": {
- "@plotday/agent": "workspace:^"
+ "@plotday/twister": "workspace:^"
},
"devDependencies": {
"typescript": "^5.9.3"
diff --git a/tools/slack/src/slack-api.ts b/tools/slack/src/slack-api.ts
index 034d872..0f5f34a 100644
--- a/tools/slack/src/slack-api.ts
+++ b/tools/slack/src/slack-api.ts
@@ -1,5 +1,5 @@
-import type { NewActivity, ActorId } from "@plotday/agent";
-import { ActivityType } from "@plotday/agent";
+import type { NewActivity, ActorId } from "@plotday/twister";
+import { ActivityType } from "@plotday/twister";
export type SlackChannel = {
id: string;
diff --git a/tools/slack/src/slack.ts b/tools/slack/src/slack.ts
index 9e37261..0019ab9 100644
--- a/tools/slack/src/slack.ts
+++ b/tools/slack/src/slack.ts
@@ -4,26 +4,26 @@ import {
type NewActivity,
Tool,
type ToolBuilder,
-} from "@plotday/agent";
+} from "@plotday/twister";
import {
type MessageChannel,
type MessagingAuth,
type MessageSyncOptions,
type MessagingTool,
-} from "@plotday/agent/common/messaging";
-import { type Callback } from "@plotday/agent/tools/callbacks";
+} from "@plotday/twister/common/messaging";
+import { type Callback } from "@plotday/twister/tools/callbacks";
import {
AuthLevel,
AuthProvider,
type Authorization,
Integrations,
-} from "@plotday/agent/tools/integrations";
-import { Network, type WebhookRequest } from "@plotday/agent/tools/network";
+} from "@plotday/twister/tools/integrations";
+import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
import {
ActivityAccess,
ContactAccess,
Plot,
-} from "@plotday/agent/tools/plot";
+} from "@plotday/twister/tools/plot";
import {
SlackApi,
@@ -63,7 +63,7 @@ import {
*
* @example
* ```typescript
- * class MessagesAgent extends Agent {
+ * class MessagesTwist extends Twist {
* private slack: Slack;
*
* constructor(id: string, tools: Tools) {
diff --git a/tools/slack/tsconfig.json b/tools/slack/tsconfig.json
index f207561..b98a116 100644
--- a/tools/slack/tsconfig.json
+++ b/tools/slack/tsconfig.json
@@ -1,6 +1,6 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
- "extends": "@plotday/agent/tsconfig.base.json",
+ "extends": "@plotday/twister/tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist"
},
diff --git a/builder/.gitignore b/twister/.gitignore
similarity index 100%
rename from builder/.gitignore
rename to twister/.gitignore
diff --git a/builder/CHANGELOG.md b/twister/CHANGELOG.md
similarity index 82%
rename from builder/CHANGELOG.md
rename to twister/CHANGELOG.md
index 761bbb8..a024670 100644
--- a/builder/CHANGELOG.md
+++ b/twister/CHANGELOG.md
@@ -1,4 +1,4 @@
-# @plotday/agent
+# @plotday/twister
## 0.19.1
@@ -20,7 +20,7 @@
### Changed
-- Update several references to the previous agent subcommand group ([`02936a6`](https://github.com/plotday/plot/commit/02936a671496c6124a31c1c54d69598276f4d8bb))
+- Update several references to the previous twist subcommand group ([`02936a6`](https://github.com/plotday/plot/commit/02936a671496c6124a31c1c54d69598276f4d8bb))
### Fixed
@@ -46,7 +46,7 @@
### Changed
-- Renamed @plotday/sdk to @plotday/agent. ([#55](https://github.com/plotday/plot/pull/55) [`8106ba0`](https://github.com/plotday/plot/commit/8106ba0597966909dd223b800adf4f63b9c4b278))
+- Renamed @plotday/sdk to @plotday/twister. ([#55](https://github.com/plotday/plot/pull/55) [`8106ba0`](https://github.com/plotday/plot/commit/8106ba0597966909dd223b800adf4f63b9c4b278))
## 0.17.0
@@ -56,15 +56,15 @@
### Changed
-- **BREAKING: Package renamed from @plotday/sdk to @plotday/agent**
- - Product name changed to "Plot Agent Builder"
+- **BREAKING: Package renamed from @plotday/sdk to @plotday/twister**
+ - Product name changed to "Plot twist Builder"
- Directory renamed from `public/sdk/` to `public/builder/`
- Export `./sdk-docs` renamed to `./builder-docs`
- Function `getSDKDocumentation()` renamed to `getBuilderDocumentation()`
- See deprecation notice in @plotday/sdk@0.17.1
- BREAKING: Creating and updating Activity using the Plot tool now requires requesting permission in options ([#51](https://github.com/plotday/plot/pull/51) [`b3242e4`](https://github.com/plotday/plot/commit/b3242e4adecea87011379ac2dd58712dc91729d7))
-- BREAKING: Agents and Tools now define a build() method to gain access to tools, which are then available via this.tools.
-- BREAKING: Renamed callCallback, run, cancel, and cancelAll Agent/Tool functions ([#51](https://github.com/plotday/plot/pull/51) [`49b4dc9`](https://github.com/plotday/plot/commit/49b4dc94e08906a89799903610325c5fe7ebe10b))
+- BREAKING: Twists and Tools now define a build() method to gain access to tools, which are then available via this.tools.
+- BREAKING: Renamed callCallback, run, cancel, and cancelAll twist/Tool functions ([#51](https://github.com/plotday/plot/pull/51) [`49b4dc9`](https://github.com/plotday/plot/commit/49b4dc94e08906a89799903610325c5fe7ebe10b))
- BREAKING: Improved callback ergonomics and types to use functions instead of strings ([#51](https://github.com/plotday/plot/pull/51) [`02c6a1e`](https://github.com/plotday/plot/commit/02c6a1e834b9aa645f29191ed59ee5b66b70c32a))
## 0.16.1
@@ -77,19 +77,19 @@
### Changed
-- BREAKING: Rename Agent.call() and Tool.call() to callCallback() to avoid confusion with JavaScript's Object.call(). ([#47](https://github.com/plotday/plot/pull/47) [`9ed2cf4`](https://github.com/plotday/plot/commit/9ed2cf4e019b5f7f0e04d35c383675ca4b6cd137))
+- BREAKING: Rename twist.call() and Tool.call() to callCallback() to avoid confusion with JavaScript's Object.call(). ([#47](https://github.com/plotday/plot/pull/47) [`9ed2cf4`](https://github.com/plotday/plot/commit/9ed2cf4e019b5f7f0e04d35c383675ca4b6cd137))
## 0.15.0
### Changed
-- BREAKING: Agents are now restricted to the http URLs they request via tools.enableInternet(). ([#45](https://github.com/plotday/plot/pull/45) [`0490f8e`](https://github.com/plotday/plot/commit/0490f8e801199893a971fdbfbead6ba2973a53c7))
+- BREAKING: Twists are now restricted to the http URLs they request via tools.enableInternet(). ([#45](https://github.com/plotday/plot/pull/45) [`0490f8e`](https://github.com/plotday/plot/commit/0490f8e801199893a971fdbfbead6ba2973a53c7))
## 0.14.8
### Added
-- Documentation on generating agents from a spec ([#43](https://github.com/plotday/plot/pull/43) [`83ebb7e`](https://github.com/plotday/plot/commit/83ebb7ef96770e1d8ae42b62e8d48200424ee35e))
+- Documentation on generating twists from a spec ([#43](https://github.com/plotday/plot/pull/43) [`83ebb7e`](https://github.com/plotday/plot/commit/83ebb7ef96770e1d8ae42b62e8d48200424ee35e))
### Changed
@@ -129,41 +129,41 @@
### Added
-- plot agent logs keepalive
+- plot twist logs keepalive
## 0.14.1
### Changed
-- plot agent logs takes id from package.json ([#29](https://github.com/plotday/plot/pull/29) [`9fefaca`](https://github.com/plotday/plot/commit/9fefaca426640fb84f7433471340d4f8ab4ba7b4))
+- plot twist logs takes id from package.json ([#29](https://github.com/plotday/plot/pull/29) [`9fefaca`](https://github.com/plotday/plot/commit/9fefaca426640fb84f7433471340d4f8ab4ba7b4))
## 0.14.0
### Added
-- plot agent logs ([#27](https://github.com/plotday/plot/pull/27) [`8030c59`](https://github.com/plotday/plot/commit/8030c5951a72dc6326b06d798ea150843cdc0143))
+- plot twist logs ([#27](https://github.com/plotday/plot/pull/27) [`8030c59`](https://github.com/plotday/plot/commit/8030c5951a72dc6326b06d798ea150843cdc0143))
### Fixed
-- Improper use of tools in Agent and Tool base classes causing "Tool not found" errors ([#27](https://github.com/plotday/plot/pull/27) [`43ce7ab`](https://github.com/plotday/plot/commit/43ce7abdd97bea1fc8ee8569fd371f5f249c498c))
+- Improper use of tools in twist and Tool base classes causing "Tool not found" errors ([#27](https://github.com/plotday/plot/pull/27) [`43ce7ab`](https://github.com/plotday/plot/commit/43ce7abdd97bea1fc8ee8569fd371f5f249c498c))
## 0.13.1
### Added
-- Progress updates for agent generate and deploy ([#25](https://github.com/plotday/plot/pull/25) [`b9c3528`](https://github.com/plotday/plot/commit/b9c35288c9a49a9a4d21f59b637146e33c15fe87))
+- Progress updates for twist generate and deploy ([#25](https://github.com/plotday/plot/pull/25) [`b9c3528`](https://github.com/plotday/plot/commit/b9c35288c9a49a9a4d21f59b637146e33c15fe87))
- Install latest SDK package after generate ([#25](https://github.com/plotday/plot/pull/25) [`b9c3528`](https://github.com/plotday/plot/commit/b9c35288c9a49a9a4d21f59b637146e33c15fe87))
### Fixed
-- Several instances of Agents and Tools missing the id argument ([#24](https://github.com/plotday/plot/pull/24) [`2d53d37`](https://github.com/plotday/plot/commit/2d53d3794419ee218976d6468319ae9129c93088))
+- Several instances of Twists and Tools missing the id argument ([#24](https://github.com/plotday/plot/pull/24) [`2d53d37`](https://github.com/plotday/plot/commit/2d53d3794419ee218976d6468319ae9129c93088))
## 0.13.0
### Changed
-- BREAKING: Add agent id to Agent and Tool constructors ([#22](https://github.com/plotday/plot/pull/22) [`34e7e43`](https://github.com/plotday/plot/commit/34e7e439d2d625e6749195623fe55389ff857e2a))
-- Generate agent-guide.ts from AGENT.template.md ([#21](https://github.com/plotday/plot/pull/21) [`fee051d`](https://github.com/plotday/plot/commit/fee051dcb33729826cb31910e74fbdf8f57acdeb))
+- BREAKING: Add twist id to twist and Tool constructors ([#22](https://github.com/plotday/plot/pull/22) [`34e7e43`](https://github.com/plotday/plot/commit/34e7e439d2d625e6749195623fe55389ff857e2a))
+- Generate twist-guide.ts from twist.template.md ([#21](https://github.com/plotday/plot/pull/21) [`fee051d`](https://github.com/plotday/plot/commit/fee051dcb33729826cb31910e74fbdf8f57acdeb))
## 0.12.2
@@ -187,25 +187,25 @@
### Changed
-- Add instructions to AGENTS.md to avoid accidentally reprocessing agent-created activities ([#10](https://github.com/plotday/plot/pull/10) [`6dc8403`](https://github.com/plotday/plot/commit/6dc8403))
+- Add instructions to AGENTS.md to avoid accidentally reprocessing twist-created activities ([#10](https://github.com/plotday/plot/pull/10) [`6dc8403`](https://github.com/plotday/plot/commit/6dc8403))
- improved changelog format ([#9](https://github.com/plotday/plot/pull/9) [`ceecf33`](https://github.com/plotday/plot/commit/ceecf33))
-- Generate a plotAgentId on "plot agent generate" if none specified ([#10](https://github.com/plotday/plot/pull/10) [`6dc8403`](https://github.com/plotday/plot/commit/6dc8403))
+- Generate a plotTwistId on "plot twist generate" if none specified ([#10](https://github.com/plotday/plot/pull/10) [`6dc8403`](https://github.com/plotday/plot/commit/6dc8403))
### Fixed
-- Set displayName on plot agent generate ([#10](https://github.com/plotday/plot/pull/10) [`6dc8403`](https://github.com/plotday/plot/commit/6dc8403))
+- Set displayName on plot twist generate ([#10](https://github.com/plotday/plot/pull/10) [`6dc8403`](https://github.com/plotday/plot/commit/6dc8403))
## 0.11.0
### Added
-- plot agent generate command ([#7](https://github.com/plotday/plot/pull/7) [`1d809ec`](https://github.com/plotday/plot/commit/1d809ec778244921cda072eb3744f36e28b3c1b4))
+- plot twist generate command ([#7](https://github.com/plotday/plot/pull/7) [`1d809ec`](https://github.com/plotday/plot/commit/1d809ec778244921cda072eb3744f36e28b3c1b4))
## 0.10.2
### Added
-- CLAUDE.md on "plot agent create" ([#5](https://github.com/plotday/plot/pull/5) [`0ac9a95`](https://github.com/plotday/plot/commit/0ac9a95953212ccd3abb3517e143e6a0957c061b14))
+- CLAUDE.md on "plot twist create" ([#5](https://github.com/plotday/plot/pull/5) [`0ac9a95`](https://github.com/plotday/plot/commit/0ac9a95953212ccd3abb3517e143e6a0957c061b14))
## 0.10.1
@@ -217,7 +217,7 @@
### Added
-- README.md and AGENTS.md on "plot agent create" ([#1](https://github.com/plotday/plot/pull/1) [`dce4f2f`](https://github.com/plotday/plot/commit/dce4f2ff3596bd9c73212c90a1cd49a7dac12f48))
+- README.md and AGENTS.md on "plot twist create" ([#1](https://github.com/plotday/plot/pull/1) [`dce4f2f`](https://github.com/plotday/plot/commit/dce4f2ff3596bd9c73212c90a1cd49a7dac12f48))
### Changed
diff --git a/builder/DOCS.md b/twister/DOCS.md
similarity index 87%
rename from builder/DOCS.md
rename to twister/DOCS.md
index bedb1e8..ba15a81 100644
--- a/builder/DOCS.md
+++ b/twister/DOCS.md
@@ -1,14 +1,14 @@
-# Plot Agent Builder Documentation
+# Plot Twist Creator Documentation
-This directory contains the TypeDoc-generated API documentation for the Plot Agent Builder.
+This directory contains the TypeDoc-generated API documentation for the Plot Twist Creator.
## Published Documentation
-The Agent Builder documentation is automatically published to GitHub Pages whenever changes are pushed to the main branch:
+The Twist Creator documentation is automatically published to GitHub Pages whenever changes are pushed to the main branch:
**Live Documentation**: [https://plotday.github.io/plot/](https://plotday.github.io/plot/)
-The documentation is automatically updated whenever changes to the Builder are merged into the main branch, ensuring developers always have access to the latest API reference.
+The documentation is automatically updated whenever changes to the Twist Creator are merged into the main branch, ensuring developers always have access to the latest API reference.
## Generating Documentation
@@ -17,7 +17,7 @@ The documentation is automatically generated during the build process, but you c
### Generate Documentation
```bash
-# From the Builder directory
+# From the Twist Creator directory
pnpm build:docs
```
@@ -62,7 +62,7 @@ start dist/docs/index.html
The generated documentation includes:
-- **Classes** - Agent, Tool, and built-in tool classes
+- **Classes** - Twist, Tool, and built-in tool classes
- **Interfaces** - Activity, Priority, Contact, and other data types
- **Enums** - ActivityType, ActorType, ActivityLinkType, etc.
- **Type Aliases** - NewActivity, NewPriority, and utility types
@@ -74,14 +74,14 @@ The documentation is automatically published in two ways:
### 1. GitHub Pages (Automatic)
-When changes to the Builder are pushed to the main branch, a GitHub Action automatically:
+When changes to the Twist Creator are pushed to the main branch, a GitHub Action automatically:
-- Builds the Builder and generates the documentation
+- Builds the Twist Creator and generates the documentation
- Deploys it to GitHub Pages at [https://plotday.github.io/plot/](https://plotday.github.io/plot/)
**Workflow Location**: `.github/workflows/deploy-docs.yml`
-**Trigger**: Automatic on push to `main` when files in `public/agent/**` change
+**Trigger**: Automatic on push to `main` when files in `public/twist/**` change
### 2. npm Package (Manual)
@@ -105,7 +105,7 @@ The `deploy-docs.yml` workflow includes all necessary permissions and configurat
The documentation generation is configured in `typedoc.json`. Key settings:
-- **Entry Points**: Main Agent Builder exports (agent, tool, plot, tools/\*)
+- **Entry Points**: Main Twist Creator exports (twist, tool, plot, tools/\*)
- **Output**: `dist/docs/`
- **Visibility**: Public APIs only (excludes private/protected/internal members)
- **Theme**: Default TypeDoc theme optimized for GitHub Pages
diff --git a/builder/LICENSE b/twister/LICENSE
similarity index 100%
rename from builder/LICENSE
rename to twister/LICENSE
diff --git a/builder/README.md b/twister/README.md
similarity index 73%
rename from builder/README.md
rename to twister/README.md
index 47d59ca..510c1d2 100644
--- a/builder/README.md
+++ b/twister/README.md
@@ -4,11 +4,11 @@
- Plot Agent Builder
+ Plot Twist Creator
- The official Builder for building Plot agents -
- custom code that organizes and prioritizes all your messages, tasks, and apps.
+ The official Creator for building Plot Twists -
+ smart automations that connect, organize, and prioritize your work.
@@ -24,14 +24,14 @@ Choose your path:
### No-Code Quick Start
-Create agents using natural language - no programming required!
+Create twists using natural language - no programming required!
-**1. Create `plot-agent.md`:**
+**1. Create `plot-twist.md`:**
```markdown
-# My Calendar Agent
+# My Calendar Twist
-I want an agent that:
+I want a twist that:
- Syncs my Google Calendar events into Plot
- Creates tasks for upcoming meetings
@@ -41,34 +41,34 @@ I want an agent that:
**2. Deploy:**
```bash
-npx @plotday/agent login
-npx @plotday/agent deploy
+npx @plotday/twister login
+npx @plotday/twister deploy
```
-That's it! [Learn more →](https://build.plot.day/documents/Getting_Started.html#no-code-agents)
+That's it! [Learn more →](https://build.plot.day/documents/Getting_Started.html#no-code-twists)
### Developer Quick Start
-Build agents with TypeScript for maximum flexibility.
+Build twists with TypeScript for maximum flexibility.
-**1. Create a new agent:**
+**1. Create a new twist:**
```bash
-npx @plotday/agent create
+npx @plotday/twister create
```
-**2. Implement your agent:**
+**2. Implement your twist:**
```typescript
import {
ActivityType,
- Agent,
+ Twist,
type Priority,
type ToolBuilder,
-} from "@plotday/agent";
-import { Plot } from "@plotday/agent/tools/plot";
+} from "@plotday/twister";
+import { Plot } from "@plotday/twister/tools/plot";
-export default class MyAgent extends Agent {
+export default class MyTwist extends Twist {
build(build: ToolBuilder) {
return {
plot: build(Plot),
@@ -78,7 +78,7 @@ export default class MyAgent extends Agent {
async activate(priority: Pick) {
await this.tools.plot.createActivity({
type: ActivityType.Note,
- title: "Welcome! Your agent is now active.",
+ title: "Welcome! Your twist is now active.",
});
}
}
@@ -97,20 +97,20 @@ npm run deploy
## Core Concepts
-### Agents
+### Twists
-Agents implement integrations and automations. They respond to lifecycle events and process activities.
+Twists are smart automations that connect, organize, and prioritize your work. They implement opinionated workflows and respond to lifecycle events.
```typescript
// Lifecycle methods
-async activate(priority) // When agent is added to a priority
-async deactivate() // When agent is removed
+async activate(priority) // When twist is added to a priority
+async deactivate() // When twist is removed
async upgrade() // When new version is deployed
```
-### Tools
+### Twist Tools
-Tools provide capabilities to agents. Use built-in tools or create your own.
+Twist tools provide capabilities to twists. They are usually unopinionated and do nothing on their own. Use built-in tools or create your own.
**Built-in Tools:**
@@ -152,11 +152,11 @@ await this.tools.plot.createActivity({
# Authentication
plot login
-# Agent management
-plot create # Create new agent project
-plot generate # Generate code from plot-agent.md
+# Twist management
+plot create # Create new twist project
+plot generate # Generate code from plot-twist.md
plot deploy # Deploy to Plot
-plot logs # Stream real-time agent logs
+plot logs # Stream real-time twist logs
# Priority management
plot priority list # List all priorities
@@ -174,9 +174,9 @@ plot priority create # Create new priority
### Guides
- [Getting Started](https://build.plot.day/documents/Getting_Started.html) - Complete walkthrough
-- [Core Concepts](https://build.plot.day/documents/Core_Concepts.html) - Agents, tools, and architecture
+- [Core Concepts](https://build.plot.day/documents/Core_Concepts.html) - Twists, tools, and architecture
- [Built-in Tools](https://build.plot.day/documents/Built-in_Tools.html) - Plot, Store, AI, and more
-- [Building Custom Tools](https://build.plot.day/documents/Building_Custom_Tools.html) - Create reusable tools
+- [Building Custom Tools](https://build.plot.day/documents/Building_Custom_Tools.html) - Create reusable twist tools
- [Runtime Environment](https://build.plot.day/documents/Runtime_Environment.html) - Execution constraints and optimization
- [Advanced Topics](https://build.plot.day/documents/Advanced.html) - Complex patterns and techniques
@@ -189,10 +189,10 @@ plot priority create # Create new priority
## Examples
-### Simple Note Agent
+### Simple Note Twist
```typescript
-export default class WelcomeAgent extends Agent {
+export default class WelcomeTwist extends Twist {
build(build: ToolBuilder) {
return { plot: build(Plot) };
}
@@ -209,7 +209,7 @@ export default class WelcomeAgent extends Agent {
### GitHub Integration
```typescript
-export default class GitHubAgent extends Agent {
+export default class GitHubTwist extends Twist {
build(build: ToolBuilder) {
return {
plot: build(Plot),
@@ -237,11 +237,11 @@ export default class GitHubAgent extends Agent {
## TypeScript Configuration
-Extend the Builder's base configuration in your `tsconfig.json`:
+Extend the Twist Creator's base configuration in your `tsconfig.json`:
```json
{
- "extends": "@plotday/agent/tsconfig.base.json",
+ "extends": "@plotday/twister/tsconfig.base.json",
"include": ["src/*.ts"]
}
```
diff --git a/builder/assets/favicon.svg b/twister/assets/favicon.svg
similarity index 100%
rename from builder/assets/favicon.svg
rename to twister/assets/favicon.svg
diff --git a/builder/cli/commands/build.ts b/twister/cli/commands/build.ts
similarity index 68%
rename from builder/cli/commands/build.ts
rename to twister/cli/commands/build.ts
index 49b2d82..a8daa89 100644
--- a/builder/cli/commands/build.ts
+++ b/twister/cli/commands/build.ts
@@ -1,7 +1,7 @@
import * as fs from "fs";
import * as path from "path";
-import { bundleAgent } from "../utils/bundle";
+import { bundleTwist } from "../utils/bundle";
import * as out from "../utils/output";
interface BuildOptions {
@@ -9,44 +9,44 @@ interface BuildOptions {
}
/**
- * Build command - bundles the agent without deploying.
+ * Build command - bundles the twist without deploying.
*
* This command is useful for:
- * - Testing that your agent builds successfully
+ * - Testing that your twist builds successfully
* - Inspecting the bundled output
* - CI/CD pipelines that separate build and deploy steps
*
* @param options - Build configuration
*/
export async function buildCommand(options: BuildOptions) {
- const agentPath = path.resolve(process.cwd(), options.dir);
+ const twistPath = path.resolve(process.cwd(), options.dir);
- // Verify we're in an agent directory
- const packageJsonPath = path.join(agentPath, "package.json");
+ // Verify we're in an twist directory
+ const packageJsonPath = path.join(twistPath, "package.json");
if (!fs.existsSync(packageJsonPath)) {
out.error(
- "package.json not found. Are you in an agent directory?",
- "Run this command from your agent's root directory"
+ "package.json not found. Are you in an twist directory?",
+ "Run this command from your twist's root directory"
);
process.exit(1);
}
- // Read package.json for agent name
- let agentName = "agent";
+ // Read package.json for twist name
+ let twistName = "twist";
try {
const packageJsonContent = fs.readFileSync(packageJsonPath, "utf-8");
const packageJson = JSON.parse(packageJsonContent);
- agentName = packageJson.displayName || packageJson.name || "agent";
+ twistName = packageJson.displayName || packageJson.name || "twist";
} catch (error) {
// Continue with default name if parsing fails
}
- out.header(`Building ${agentName}`);
+ out.header(`Building ${twistName}`);
try {
- // Bundle the agent
+ // Bundle the twist
out.progress("Bundling...");
- const result = await bundleAgent(agentPath, {
+ const result = await bundleTwist(twistPath, {
minify: false,
sourcemap: true,
});
@@ -63,7 +63,7 @@ export async function buildCommand(options: BuildOptions) {
}
// Get bundle stats
- const buildDir = path.join(agentPath, "build");
+ const buildDir = path.join(twistPath, "build");
const bundlePath = path.join(buildDir, "index.js");
const stats = fs.statSync(bundlePath);
const sizeKB = (stats.size / 1024).toFixed(2);
@@ -76,7 +76,7 @@ export async function buildCommand(options: BuildOptions) {
// Tip for next steps
out.blank();
out.plain("Next steps:");
- out.plain(" • Run 'plot deploy' to deploy this agent");
+ out.plain(" • Run 'plot deploy' to deploy this twist");
out.plain(" • Or inspect the bundled output in build/index.js");
out.blank();
} catch (error) {
diff --git a/builder/cli/commands/create.ts b/twister/cli/commands/create.ts
similarity index 75%
rename from builder/cli/commands/create.ts
rename to twister/cli/commands/create.ts
index 602b2c2..7e75ce7 100644
--- a/builder/cli/commands/create.ts
+++ b/twister/cli/commands/create.ts
@@ -13,7 +13,7 @@ interface CreateOptions {
}
export async function createCommand(options: CreateOptions) {
- out.header("Create a new Plot agent");
+ out.header("Create a new Plot twist");
let response: { name: string; displayName: string };
@@ -64,19 +64,19 @@ export async function createCommand(options: CreateOptions) {
response = promptResponse as { name: string; displayName: string };
}
- const agentDir = options.dir || response.name;
- const agentPath = path.resolve(process.cwd(), agentDir);
+ const twistDir = options.dir || response.name;
+ const twistPath = path.resolve(process.cwd(), twistDir);
- if (fs.existsSync(agentPath)) {
- out.error(`Directory "${agentDir}" already exists`);
+ if (fs.existsSync(twistPath)) {
+ out.error(`Directory "${twistDir}" already exists`);
process.exit(1);
}
out.progress(`Creating ${response.displayName}...`);
// Create directory structure
- fs.mkdirSync(agentPath, { recursive: true });
- fs.mkdirSync(path.join(agentPath, "src"), { recursive: true });
+ fs.mkdirSync(twistPath, { recursive: true });
+ fs.mkdirSync(path.join(twistPath, "src"), { recursive: true });
// Read SDK version from package.json
let sdkVersion = "^0.1.0"; // Fallback version
@@ -86,12 +86,12 @@ export async function createCommand(options: CreateOptions) {
sdkVersion = `^${sdkPackage.version}`;
} catch (error) {
console.warn(
- "Warning: Could not read Agent Builder version, using fallback"
+ "Warning: Could not read Twist Creator version, using fallback"
);
}
- // Generate a unique agent ID
- const plotAgentId = crypto.randomUUID();
+ // Generate a unique twist ID
+ const plotTwistId = crypto.randomUUID();
// Create package.json
const packageJson: any = {
@@ -99,13 +99,13 @@ export async function createCommand(options: CreateOptions) {
displayName: response.displayName || response.name,
main: "src/index.ts",
types: "src/index.ts",
- plotAgentId: plotAgentId,
+ plotTwistId: plotTwistId,
scripts: {
lint: "plot lint",
deploy: "plot deploy",
},
dependencies: {
- "@plotday/agent": sdkVersion,
+ "@plotday/twister": sdkVersion,
},
devDependencies: {
typescript: "^5.8.3",
@@ -113,29 +113,29 @@ export async function createCommand(options: CreateOptions) {
};
fs.writeFileSync(
- path.join(agentPath, "package.json"),
+ path.join(twistPath, "package.json"),
JSON.stringify(packageJson, null, 2) + "\n"
);
// Create tsconfig.json
const tsconfigJson = {
- extends: "@plotday/agent/tsconfig.base.json",
+ extends: "@plotday/twister/tsconfig.base.json",
include: ["src/*.ts"],
};
fs.writeFileSync(
- path.join(agentPath, "tsconfig.json"),
+ path.join(twistPath, "tsconfig.json"),
JSON.stringify(tsconfigJson, null, 2) + "\n"
);
- const agentTemplate = `import {
+ const twistTemplate = `import {
type Activity,
- Agent,
+ Twist,
type Priority,
type ToolBuilder,
-} from "@plotday/agent";
-import { Plot } from "@plotday/agent/tools/plot";
+} from "@plotday/twister";
+import { Plot } from "@plotday/twister/tools/plot";
-export default class MyAgent extends Agent {
+export default class MyTwist extends Twist {
build(build: ToolBuilder) {
return {
plot: build(Plot),
@@ -143,15 +143,15 @@ export default class MyAgent extends Agent {
}
async activate(_priority: Pick) {
- // Called when agent is enabled for a priority
+ // Called when twist is enabled for a priority
}
async activity(activity: Activity) {
- // Called when an activity is routed to this agent
+ // Called when an activity is routed to this twist
}
}
`;
- fs.writeFileSync(path.join(agentPath, "src", "index.ts"), agentTemplate);
+ fs.writeFileSync(path.join(twistPath, "src", "index.ts"), twistTemplate);
// Detect and use appropriate package manager
const packageManager = detectPackageManager();
@@ -177,26 +177,26 @@ export default class MyAgent extends Agent {
/\{\{packageManager\}\}/g,
packageManagerCommand
);
- fs.writeFileSync(path.join(agentPath, "README.md"), readmeContent);
+ fs.writeFileSync(path.join(twistPath, "README.md"), readmeContent);
} catch (error) {
console.warn("Warning: Could not copy README template");
}
// Copy AGENTS.md from template
- const agentsTemplatePath = path.join(
+ const twistsTemplatePath = path.join(
__dirname,
"..",
"templates",
"AGENTS.template.md"
);
try {
- let agentsContent = fs.readFileSync(agentsTemplatePath, "utf-8");
+ let twistsContent = fs.readFileSync(twistsTemplatePath, "utf-8");
// Replace template variables
- agentsContent = agentsContent.replace(
+ twistsContent = twistsContent.replace(
/\{\{packageManager\}\}/g,
packageManagerCommand
);
- fs.writeFileSync(path.join(agentPath, "AGENTS.md"), agentsContent);
+ fs.writeFileSync(path.join(twistPath, "AGENTS.md"), twistsContent);
} catch (error) {
console.warn("Warning: Could not copy AGENTS template");
}
@@ -210,7 +210,7 @@ export default class MyAgent extends Agent {
);
try {
const claudeContent = fs.readFileSync(claudeTemplatePath, "utf-8");
- fs.writeFileSync(path.join(agentPath, "CLAUDE.md"), claudeContent);
+ fs.writeFileSync(path.join(twistPath, "CLAUDE.md"), claudeContent);
} catch (error) {
console.warn("Warning: Could not copy CLAUDE template");
}
@@ -220,11 +220,11 @@ export default class MyAgent extends Agent {
build/
.env
`;
- fs.writeFileSync(path.join(agentPath, ".gitignore"), gitignore);
+ fs.writeFileSync(path.join(twistPath, ".gitignore"), gitignore);
// Initialize git
try {
- execSync("git init", { cwd: agentPath, stdio: "ignore" });
+ execSync("git init", { cwd: twistPath, stdio: "ignore" });
} catch (error) {
// Silently fail - not critical
}
@@ -234,17 +234,17 @@ build/
// Install dependencies
try {
- execSync(installCommand, { cwd: agentPath, stdio: "ignore" });
+ execSync(installCommand, { cwd: twistPath, stdio: "ignore" });
} catch (error) {
out.warning("Couldn't install dependencies", [
- `Run '${installCommand}' in ${agentDir}`,
+ `Run '${installCommand}' in ${twistDir}`,
]);
}
out.success(`${response.displayName} created`);
out.nextSteps([
- `cd ${agentDir}`,
+ `cd ${twistDir}`,
`${packageManager === "npm" ? "npm run" : packageManager} lint`,
`${packageManager === "npm" ? "npm run" : packageManager} deploy`,
]);
diff --git a/builder/cli/commands/deploy.ts b/twister/cli/commands/deploy.ts
similarity index 85%
rename from builder/cli/commands/deploy.ts
rename to twister/cli/commands/deploy.ts
index a20ba92..ebf9dba 100644
--- a/builder/cli/commands/deploy.ts
+++ b/twister/cli/commands/deploy.ts
@@ -3,7 +3,7 @@ import * as fs from "fs";
import * as path from "path";
import prompts from "prompts";
-import { bundleAgent } from "../utils/bundle";
+import { bundleTwist } from "../utils/bundle";
import * as out from "../utils/output";
import { handleSSEStream } from "../utils/sse";
import { getGlobalTokenPath } from "../utils/token";
@@ -25,8 +25,8 @@ interface PackageJson {
description?: string;
author?: string;
license?: string;
- plotAgentId?: string;
- plotAgent?: {
+ plotTwistId?: string;
+ plotTwist?: {
id?: string;
tools?: string[];
};
@@ -34,10 +34,10 @@ interface PackageJson {
}
export async function deployCommand(options: DeployOptions) {
- const agentPath = path.resolve(process.cwd(), options.dir);
+ const twistPath = path.resolve(process.cwd(), options.dir);
// Check for package.json
- const packageJsonPath = path.join(agentPath, "package.json");
+ const packageJsonPath = path.join(twistPath, "package.json");
let packageJson: PackageJson | undefined;
if (fs.existsSync(packageJsonPath)) {
@@ -50,11 +50,11 @@ export async function deployCommand(options: DeployOptions) {
process.exit(1);
}
} else {
- // No package.json - check for plot-agent.md as fallback
- const specPath = path.join(agentPath, "plot-agent.md");
+ // No package.json - check for plot-twist.md as fallback
+ const specPath = path.join(twistPath, "plot-twist.md");
if (fs.existsSync(specPath)) {
- out.info("No package.json found, but plot-agent.md exists", [
- "Generating agent from spec first...",
+ out.info("No package.json found, but plot-twist.md exists", [
+ "Generating twist from spec first...",
]);
// Import and run generate command
@@ -79,46 +79,46 @@ export async function deployCommand(options: DeployOptions) {
out.progress("Continuing with deployment...");
} else {
out.error(
- "Neither package.json nor plot-agent.md found",
- "Run 'plot create' to create a new agent, or create a plot-agent.md spec file"
+ "Neither package.json nor plot-twist.md found",
+ "Run 'plot create' to create a new twist, or create a plot-twist.md spec file"
);
process.exit(1);
}
}
- // Extract agent metadata from package.json
- let agentId = packageJson?.plotAgentId;
- const agentName = packageJson?.displayName;
- const agentDescription = packageJson?.description;
+ // Extract twist metadata from package.json
+ let twistId = packageJson?.plotTwistId;
+ const twistName = packageJson?.displayName;
+ const twistDescription = packageJson?.description;
const environment = options.environment || "personal";
// Validate required fields
- if (!agentName) {
+ if (!twistName) {
out.error(
"package.json is missing displayName",
- 'Add "displayName": "Your Agent Name" to package.json'
+ 'Add "displayName": "Your Twist Name" to package.json'
);
process.exit(1);
}
- // Validate Agent ID is present (from package.json or CLI)
- if (!agentId && !options.id) {
+ // Validate Twist ID is present (from package.json or CLI)
+ if (!twistId && !options.id) {
out.error(
- "Agent ID missing",
+ "Twist ID missing",
"Run 'plot create' to generate one, or provide --id flag"
);
process.exit(1);
}
// Resolve deployment ID, name, and description from options or package.json
- const deploymentId = options.id || agentId;
- const deploymentName = options.name || agentName;
- const deploymentDescription = options.description || agentDescription;
+ const deploymentId = options.id || twistId;
+ const deploymentName = options.name || twistName;
+ const deploymentDescription = options.description || twistDescription;
// Load DEPLOY_TOKEN from multiple sources (CLI, env var, .env, global config)
let deployToken = options.deployToken;
- const envPath = path.join(agentPath, ".env");
+ const envPath = path.join(twistPath, ".env");
if (!deployToken) {
// Try to load from PLOT_DEPLOY_TOKEN environment variable
@@ -184,7 +184,7 @@ export async function deployCommand(options: DeployOptions) {
}
}
- // Build the agent
+ // Build the twist
let requestBody: {
module: string;
sourcemap?: string;
@@ -201,7 +201,7 @@ export async function deployCommand(options: DeployOptions) {
: `Building ${deploymentName}...`
);
- const result = await bundleAgent(agentPath, {
+ const result = await bundleTwist(twistPath, {
minify: false,
sourcemap: true,
});
@@ -231,7 +231,7 @@ export async function deployCommand(options: DeployOptions) {
// Validate all required deployment fields
if (!deploymentName) {
out.error(
- "Agent name is required",
+ "Twist name is required",
"Provide --name, or add 'displayName' to package.json"
);
process.exit(1);
@@ -240,7 +240,7 @@ export async function deployCommand(options: DeployOptions) {
// Description is only required for non-personal environments
if (environment !== "personal" && !deploymentDescription) {
out.error(
- "Agent description is required for non-personal environments",
+ "Twist description is required for non-personal environments",
"Provide --description, or add 'description' to package.json"
);
process.exit(1);
@@ -250,7 +250,7 @@ export async function deployCommand(options: DeployOptions) {
const urlPath = deploymentId || "personal";
try {
- const response = await fetch(`${options.apiUrl}/v1/agent/${urlPath}`, {
+ const response = await fetch(`${options.apiUrl}/v1/twist/${urlPath}`, {
method: "POST",
headers: {
"Content-Type": "application/json",
@@ -290,7 +290,7 @@ export async function deployCommand(options: DeployOptions) {
}
process.exit(1);
} else {
- out.success("Validation passed - agent is ready to deploy");
+ out.success("Validation passed - twist is ready to deploy");
out.info("Run without --dry-run to deploy", [`plot deploy`]);
}
return;
diff --git a/builder/cli/commands/generate.ts b/twister/cli/commands/generate.ts
similarity index 78%
rename from builder/cli/commands/generate.ts
rename to twister/cli/commands/generate.ts
index ed351a6..30edb4b 100644
--- a/builder/cli/commands/generate.ts
+++ b/twister/cli/commands/generate.ts
@@ -17,7 +17,7 @@ interface GenerateOptions {
apiUrl: string;
}
-interface AgentSource {
+interface TwistSource {
displayName: string;
dependencies: Record;
files: Record;
@@ -64,18 +64,18 @@ async function promptOverwrite(
}
export async function generateCommand(options: GenerateOptions) {
- const agentPath = path.resolve(process.cwd(), options.dir);
+ const twistPath = path.resolve(process.cwd(), options.dir);
- // Determine spec file path (default to plot-agent.md)
+ // Determine spec file path (default to plot-twist.md)
const specPath = options.spec
? path.resolve(process.cwd(), options.spec)
- : path.join(agentPath, "plot-agent.md");
+ : path.join(twistPath, "plot-twist.md");
// Check if spec file exists
if (!fs.existsSync(specPath)) {
out.error(
`Spec file not found: ${path.relative(process.cwd(), specPath)}`,
- "Create a plot-agent.md file describing your agent, or use --spec to specify a different file"
+ "Create a plot-twist.md file describing your twist, or use --spec to specify a different file"
);
process.exit(1);
}
@@ -89,27 +89,27 @@ export async function generateCommand(options: GenerateOptions) {
process.exit(1);
}
- // Try to read package.json for agent ID
- const packageJsonPath = path.join(agentPath, "package.json");
- let agentId = options.id;
+ // Try to read package.json for twist ID
+ const packageJsonPath = path.join(twistPath, "package.json");
+ let twistId = options.id;
- if (!agentId && fs.existsSync(packageJsonPath)) {
+ if (!twistId && fs.existsSync(packageJsonPath)) {
try {
const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
- agentId = packageJson.plotAgentId;
+ twistId = packageJson.plotTwistId;
} catch {
// Ignore errors
}
}
- // Generate agent ID if not provided
- if (!agentId) {
- agentId = crypto.randomUUID();
+ // Generate twist ID if not provided
+ if (!twistId) {
+ twistId = crypto.randomUUID();
}
// Load DEPLOY_TOKEN from multiple sources
let deployToken = options.deployToken;
- const envPath = path.join(agentPath, ".env");
+ const envPath = path.join(twistPath, ".env");
if (!deployToken) {
deployToken = process.env.PLOT_DEPLOY_TOKEN;
@@ -172,9 +172,9 @@ export async function generateCommand(options: GenerateOptions) {
// Call generate API
try {
const relativeSpecPath = path.relative(process.cwd(), specPath);
- out.progress(`Generate agent from ${relativeSpecPath}...`);
+ out.progress(`Generate twist from ${relativeSpecPath}...`);
- const response = await fetch(`${options.apiUrl}/v1/agent/generate`, {
+ const response = await fetch(`${options.apiUrl}/v1/twist/generate`, {
method: "POST",
headers: {
"Content-Type": "application/json",
@@ -198,21 +198,21 @@ export async function generateCommand(options: GenerateOptions) {
onProgress: (message) => {
out.progress(message);
},
- })) as AgentSource;
+ })) as TwistSource;
- // Create agent directory if it doesn't exist
- if (!fs.existsSync(agentPath)) {
- fs.mkdirSync(agentPath, { recursive: true });
+ // Create twist directory if it doesn't exist
+ if (!fs.existsSync(twistPath)) {
+ fs.mkdirSync(twistPath, { recursive: true });
}
// Prepare list of files that will be created
- const packageJsonPath = path.join(agentPath, "package.json");
- const tsconfigPath = path.join(agentPath, "tsconfig.json");
- const readmePath = path.join(agentPath, "README.md");
- const agentsMdPath = path.join(agentPath, "AGENTS.md");
- const claudeMdPath = path.join(agentPath, "CLAUDE.md");
+ const packageJsonPath = path.join(twistPath, "package.json");
+ const tsconfigPath = path.join(twistPath, "tsconfig.json");
+ const readmePath = path.join(twistPath, "README.md");
+ const twistsMdPath = path.join(twistPath, "AGENTS.md");
+ const claudeMdPath = path.join(twistPath, "CLAUDE.md");
- const srcPath = path.join(agentPath, "src");
+ const srcPath = path.join(twistPath, "src");
const sourceFiles = Object.keys(source.files).map((filename) =>
path.join(srcPath, filename)
);
@@ -221,7 +221,7 @@ export async function generateCommand(options: GenerateOptions) {
packageJsonPath,
tsconfigPath,
readmePath,
- agentsMdPath,
+ twistsMdPath,
claudeMdPath,
...sourceFiles,
];
@@ -233,18 +233,18 @@ export async function generateCommand(options: GenerateOptions) {
const writeFile = (filePath: string, content: string) => {
if (!skip.has(filePath)) {
fs.writeFileSync(filePath, content);
- out.success(`Created ${path.relative(agentPath, filePath)}`);
+ out.success(`Created ${path.relative(twistPath, filePath)}`);
} else {
- out.info(`Skipped ${path.relative(agentPath, filePath)}`);
+ out.info(`Skipped ${path.relative(twistPath, filePath)}`);
}
};
// Write package.json
const packageJson = {
- name: agentId,
+ name: twistId,
version: "1.0.0",
displayName: source.displayName,
- plotAgentId: agentId,
+ plotTwistId: twistId,
scripts: {
lint: "plot lint",
deploy: "plot deploy",
@@ -259,7 +259,7 @@ export async function generateCommand(options: GenerateOptions) {
// Write tsconfig.json
const tsconfigContent = {
- extends: "@plotday/agent/tsconfig.base.json",
+ extends: "@plotday/twister/tsconfig.base.json",
include: ["src/*.ts"],
};
writeFile(tsconfigPath, JSON.stringify(tsconfigContent, null, 2) + "\n");
@@ -268,11 +268,11 @@ export async function generateCommand(options: GenerateOptions) {
const templatesPath = path.join(__dirname, "..", "..", "bin", "templates");
// Write AGENTS.md (no template processing needed)
- const agentsMdTemplate = fs.readFileSync(
+ const twistsMdTemplate = fs.readFileSync(
path.join(templatesPath, "AGENTS.template.md"),
"utf-8"
);
- writeFile(agentsMdPath, agentsMdTemplate);
+ writeFile(twistsMdPath, twistsMdTemplate);
// Write CLAUDE.md (no template processing needed)
const claudeMdTemplate = fs.readFileSync(
@@ -310,30 +310,30 @@ export async function generateCommand(options: GenerateOptions) {
// Detect package manager and install dependencies
const packageManager = detectPackageManager();
- // Update @plotday/agent to latest and install packages
+ // Update @plotday/twist to latest and install packages
try {
- out.progress("Updating Agent Builder to latest version...");
+ out.progress("Updating Twist Creator to latest version...");
const updateCommand =
packageManager === "npm"
- ? "npm install @plotday/agent@latest"
+ ? "npm install @plotday/twist@latest"
: packageManager === "pnpm"
- ? "pnpm add @plotday/agent@latest"
- : "yarn add @plotday/agent@latest";
+ ? "pnpm add @plotday/twist@latest"
+ : "yarn add @plotday/twist@latest";
- execSync(updateCommand, { cwd: agentPath, stdio: "ignore" });
+ execSync(updateCommand, { cwd: twistPath, stdio: "ignore" });
out.progress("Installing dependencies...");
const installCommand =
packageManager === "yarn" ? "yarn" : `${packageManager} install`;
- execSync(installCommand, { cwd: agentPath, stdio: "ignore" });
+ execSync(installCommand, { cwd: twistPath, stdio: "ignore" });
out.success("Dependencies installed.");
} catch (error) {
out.warning("Couldn't install dependencies", [
- `Run '${packageManager} install @plotday/agent@latest' in ${options.dir}`,
+ `Run '${packageManager} install @plotday/twist@latest' in ${options.dir}`,
`Then run '${
packageManager === "yarn" ? "yarn" : `${packageManager} install`
}'`,
@@ -341,11 +341,11 @@ export async function generateCommand(options: GenerateOptions) {
}
out.blank();
- out.success("Agent generated successfully!");
+ out.success("Twist generated successfully!");
out.nextSteps([
"Review the generated code in src/",
- `Run '${packageManager} run deploy' to deploy your agent`,
+ `Run '${packageManager} run deploy' to deploy your twist`,
`Run '${packageManager} run logs' to watch for activity`,
]);
} catch (error) {
diff --git a/builder/cli/commands/lint.ts b/twister/cli/commands/lint.ts
similarity index 64%
rename from builder/cli/commands/lint.ts
rename to twister/cli/commands/lint.ts
index 4186c26..9ab06b5 100644
--- a/builder/cli/commands/lint.ts
+++ b/twister/cli/commands/lint.ts
@@ -8,19 +8,19 @@ interface LintOptions {
}
export function lintCommand(options: LintOptions) {
- const agentPath = path.resolve(process.cwd(), options.dir);
+ const twistPath = path.resolve(process.cwd(), options.dir);
- // Verify we're in an agent directory by checking for package.json
- const packageJsonPath = path.join(agentPath, "package.json");
+ // Verify we're in an twist directory by checking for package.json
+ const packageJsonPath = path.join(twistPath, "package.json");
if (!fs.existsSync(packageJsonPath)) {
out.error(
- "package.json not found. Are you in an agent directory?",
- "Run this command from your agent's root directory",
+ "package.json not found. Are you in an twist directory?",
+ "Run this command from your twist's root directory",
);
process.exit(1);
}
- const tsconfigPath = path.join(agentPath, "tsconfig.json");
+ const tsconfigPath = path.join(twistPath, "tsconfig.json");
if (!fs.existsSync(tsconfigPath)) {
out.error("tsconfig.json not found");
process.exit(1);
@@ -30,7 +30,7 @@ export function lintCommand(options: LintOptions) {
try {
execSync("tsc --noEmit", {
- cwd: agentPath,
+ cwd: twistPath,
stdio: "inherit",
});
out.success("All good! No errors found");
diff --git a/builder/cli/commands/login.ts b/twister/cli/commands/login.ts
similarity index 98%
rename from builder/cli/commands/login.ts
rename to twister/cli/commands/login.ts
index 4b49309..1598398 100644
--- a/builder/cli/commands/login.ts
+++ b/twister/cli/commands/login.ts
@@ -88,7 +88,7 @@ export async function loginCommand(options: LoginOptions) {
const sessionId = crypto.randomUUID();
// Construct login URL
- const loginUrl = `${options.siteUrl}/builder/login?session=${sessionId}`;
+ const loginUrl = `${options.siteUrl}/twister/login?session=${sessionId}`;
// Open browser
openBrowser(loginUrl);
diff --git a/builder/cli/commands/priority-create.ts b/twister/cli/commands/priority-create.ts
similarity index 100%
rename from builder/cli/commands/priority-create.ts
rename to twister/cli/commands/priority-create.ts
diff --git a/builder/cli/commands/priority-list.ts b/twister/cli/commands/priority-list.ts
similarity index 100%
rename from builder/cli/commands/priority-list.ts
rename to twister/cli/commands/priority-list.ts
diff --git a/builder/cli/commands/agent-logs.ts b/twister/cli/commands/twist-logs.ts
similarity index 89%
rename from builder/cli/commands/agent-logs.ts
rename to twister/cli/commands/twist-logs.ts
index ffbbd29..fb2be33 100644
--- a/builder/cli/commands/agent-logs.ts
+++ b/twister/cli/commands/twist-logs.ts
@@ -6,11 +6,11 @@ import { getGlobalTokenPath } from "../utils/token";
import { handleSSEStream } from "../utils/sse";
interface PackageJson {
- plotAgentId?: string;
+ plotTwistId?: string;
}
-interface AgentLogsOptions {
- agentId?: string;
+interface TwistLogsOptions {
+ twistId?: string;
id?: string;
dir?: string;
environment?: string;
@@ -19,22 +19,22 @@ interface AgentLogsOptions {
}
/**
- * Stream agent logs in real-time
+ * Stream twist logs in real-time
*/
-export async function agentLogsCommand(options: AgentLogsOptions) {
+export async function twistLogsCommand(options: TwistLogsOptions) {
const { environment = "personal", apiUrl, dir = process.cwd() } = options;
- // Determine agent ID from options, positional arg, or package.json
- let agentId = options.id || options.agentId;
+ // Determine twist ID from options, positional arg, or package.json
+ let twistId = options.id || options.twistId;
- if (!agentId) {
+ if (!twistId) {
// Try to read from package.json
const packageJsonPath = path.join(dir, "package.json");
if (fs.existsSync(packageJsonPath)) {
try {
const packageJsonContent = fs.readFileSync(packageJsonPath, "utf-8");
const packageJson: PackageJson = JSON.parse(packageJsonContent);
- agentId = packageJson.plotAgentId;
+ twistId = packageJson.plotTwistId;
} catch (error) {
out.error("Failed to parse package.json", String(error));
process.exit(1);
@@ -42,10 +42,10 @@ export async function agentLogsCommand(options: AgentLogsOptions) {
}
}
- if (!agentId) {
+ if (!twistId) {
out.error(
- "Agent ID required",
- "Provide agent ID as argument, via --id flag, or add 'plotAgentId' to package.json"
+ "Twist ID required",
+ "Provide twist ID as argument, via --id flag, or add 'plotTwistId' to package.json"
);
process.exit(1);
}
@@ -81,12 +81,12 @@ export async function agentLogsCommand(options: AgentLogsOptions) {
}
// Construct API URL
- const url = new URL(`/v1/agent/${agentId}/logs`, apiUrl);
+ const url = new URL(`/v1/twist/${twistId}/logs`, apiUrl);
if (environment !== "personal") {
url.searchParams.set("environment", environment);
}
- out.info(`Streaming logs for agent ${agentId}`, [
+ out.info(`Streaming logs for twist ${twistId}`, [
`Environment: ${environment}`,
"Press Ctrl+C to stop",
]);
diff --git a/builder/cli/index.ts b/twister/cli/index.ts
similarity index 78%
rename from builder/cli/index.ts
rename to twister/cli/index.ts
index 67e0890..b791c73 100644
--- a/builder/cli/index.ts
+++ b/twister/cli/index.ts
@@ -3,7 +3,7 @@ import { Command, Option } from "commander";
import { readFileSync } from "fs";
import { join } from "path";
-import { agentLogsCommand } from "./commands/agent-logs";
+import { twistLogsCommand } from "./commands/twist-logs";
import { buildCommand } from "./commands/build";
import { createCommand } from "./commands/create";
import { deployCommand } from "./commands/deploy";
@@ -26,7 +26,7 @@ const program = new Command();
program
.name("plot")
- .description("CLI tool for building and deploying Plot agents")
+ .description("CLI tool for building and deploying Plot twists")
.version(version)
.addOption(
new Option("--api-url ", "API endpoint URL")
@@ -51,33 +51,33 @@ program
// Top-level create command
program
.command("create")
- .description("Create a new Plot agent")
- .option("-d, --dir ", "Directory to create the agent in")
+ .description("Create a new Plot twist")
+ .option("-d, --dir ", "Directory to create the twist in")
.option("-n, --name ", "Package name (kebab-case)")
- .option("--display-name ", "Display name for the agent")
+ .option("--display-name ", "Display name for the twist")
.action(createCommand);
// Top-level lint command
program
.command("lint")
.description("Check for build or lint errors")
- .option("-d, --dir ", "Agent directory to lint", process.cwd())
+ .option("-d, --dir ", "Twist directory to lint", process.cwd())
.action(lintCommand);
// Top-level build command
program
.command("build")
- .description("Bundle the agent without deploying")
- .option("-d, --dir ", "Agent directory to build", process.cwd())
+ .description("Bundle the twist without deploying")
+ .option("-d, --dir ", "Twist directory to build", process.cwd())
.action(buildCommand);
// Top-level generate command
program
.command("generate")
- .description("Generate agent code from a spec file")
- .option("-d, --dir ", "Agent directory to generate in", process.cwd())
- .option("--spec ", "Spec file to generate from (defaults to plot-agent.md)")
- .option("--id ", "Agent ID")
+ .description("Generate twist code from a spec file")
+ .option("-d, --dir ", "Twist directory to generate in", process.cwd())
+ .option("--spec ", "Spec file to generate from (defaults to plot-twist.md)")
+ .option("--id ", "Twist ID")
.option("--deploy-token ", "Authentication token")
.action(function (this: Command) {
const opts = this.optsWithGlobals() as {
@@ -93,12 +93,12 @@ program
// Top-level deploy command
program
.command("deploy")
- .description("Bundle and deploy the agent")
- .option("-d, --dir ", "Agent directory to deploy", process.cwd())
- .option("--id ", "Agent ID for deployment")
+ .description("Bundle and deploy the twist")
+ .option("-d, --dir ", "Twist directory to deploy", process.cwd())
+ .option("--id ", "Twist ID for deployment")
.option("--deploy-token ", "Authentication token for deployment")
- .option("--name ", "Agent name")
- .option("--description ", "Agent description")
+ .option("--name ", "Twist name")
+ .option("--description ", "Twist description")
.option("--dry-run", "Validate without deploying")
.option(
"-e, --environment ",
@@ -121,17 +121,17 @@ program
// Top-level logs command
program
- .command("logs [agent-id]")
- .description("Stream real-time logs from an agent")
- .option("-d, --dir ", "Agent directory", process.cwd())
- .option("--id ", "Agent ID")
+ .command("logs [twist-id]")
+ .description("Stream real-time logs from a twist")
+ .option("-d, --dir ", "Twist directory", process.cwd())
+ .option("--id ", "Twist ID")
.option(
"-e, --environment ",
- "Agent environment (personal, private, review)",
+ "Twist environment (personal, private, review)",
"personal"
)
.option("--deploy-token ", "Authentication token")
- .action(function (this: Command, agentId?: string) {
+ .action(function (this: Command, twistId?: string) {
const opts = this.optsWithGlobals() as {
dir?: string;
id?: string;
@@ -139,8 +139,8 @@ program
deployToken?: string;
apiUrl: string;
};
- return agentLogsCommand({
- agentId,
+ return twistLogsCommand({
+ twistId,
id: opts.id,
dir: opts.dir,
environment: opts.environment,
diff --git a/builder/cli/templates/AGENTS.template.md b/twister/cli/templates/AGENTS.template.md
similarity index 83%
rename from builder/cli/templates/AGENTS.template.md
rename to twister/cli/templates/AGENTS.template.md
index fd194f8..769c44c 100644
--- a/builder/cli/templates/AGENTS.template.md
+++ b/twister/cli/templates/AGENTS.template.md
@@ -1,34 +1,34 @@
-# Agent Implementation Guide for LLMs
+# Twist Implementation Guide for LLMs
-This document provides context for AI assistants generating or modifying agent code.
+This document provides context for AI assistants generating or modifying twists.
## Architecture Overview
-Plot agents are TypeScript classes that extend the `Agent` base class. Agents interact with external services and Plot's core functionality through a tool-based architecture.
+Plot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.
### Runtime Environment
-**Critical**: All agent and tool functions are executed in a sandboxed, ephemeral environment with limited resources:
+**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:
-- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the agent/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.
+- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.
- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)
- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`
- **Break long operations**: Split large operations into smaller batches that can be processed independently
- **Store intermediate state**: Use the Store tool to persist state between batches
- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations
-## Agent Structure Pattern
+## twist Structure Pattern
```typescript
import {
type Activity,
- Agent,
+ twist,
type Priority,
type ToolBuilder,
-} from "@plotday/agent";
-import { Plot } from "@plotday/agent/tools/plot";
+} from "@plotday/twister";
+import { Plot } from "@plotday/twister/tools/plot";
-export default class MyAgent extends Agent {
+export default class MyTwist extends twist {
build(build: ToolBuilder) {
return {
plot: build(Plot),
@@ -36,12 +36,12 @@ export default class MyAgent extends Agent {
}
async activate(priority: Pick) {
- // Called when agent is enabled for a priority
+ // Called when twist is enabled for a priority
// Common actions: request auth, create setup activities
}
async activity(activity: Activity) {
- // Called when an activity is routed to this agent
+ // Called when an activity is routed to this twist
// Common actions: process external events, update activities
}
}
@@ -67,19 +67,19 @@ IMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { url
### Built-in Tools (Always Available)
-For complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/agent/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.
+For complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.
**Quick reference - Available tools:**
-- `@plotday/agent/tools/plot` - Core data layer (create/update activities, priorities, contacts)
-- `@plotday/agent/tools/ai` - LLM integration (text generation, structured output, reasoning)
+- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)
+- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)
- Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)
-- `@plotday/agent/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)
-- `@plotday/agent/tools/tasks` - Queue batched work (also via `this.run()`)
-- `@plotday/agent/tools/callbacks` - Persistent function references (also via `this.callback()`)
-- `@plotday/agent/tools/integrations` - OAuth2 authentication flows
-- `@plotday/agent/tools/network` - HTTP access permissions and webhook management
-- `@plotday/agent/tools/agents` - Manage other agents
+- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)
+- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)
+- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)
+- `@plotday/twister/tools/integrations` - OAuth2 authentication flows
+- `@plotday/twister/tools/network` - HTTP access permissions and webhook management
+- `@plotday/twister/tools/twists` - Manage other Twists
**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.
@@ -90,7 +90,7 @@ Add tool dependencies to `package.json`:
```json
{
"dependencies": {
- "@plotday/agent": "workspace:^",
+ "@plotday/twister": "workspace:^",
"@plotday/tool-google-calendar": "workspace:^"
}
}
@@ -106,7 +106,7 @@ Add tool dependencies to `package.json`:
### activate(priority: Pick)
-Called when the agent is enabled for a priority. Common patterns:
+Called when the twist is enabled for a priority. Common patterns:
**Request Authentication:**
@@ -138,7 +138,7 @@ await this.set("setup_activity_id", activity.id);
### activity(activity: Activity)
-Called when an activity is routed to the agent. Common patterns:
+Called when an activity is routed to the twist. Common patterns:
**Create Activities from External Events:**
@@ -163,7 +163,7 @@ async activity(activity: Activity) {
Activity links enable user interaction:
```typescript
-import { type ActivityLink, ActivityLinkType } from "@plotday/agent";
+import { type ActivityLink, ActivityLinkType } from "@plotday/twister";
// URL link
const urlLink: ActivityLink = {
@@ -302,7 +302,7 @@ async onCalendarSelected(
## Batch Processing Pattern
-**Important**: Because agents run in an ephemeral environment with limited execution time (~10 seconds), you must break long operations into batches. Each batch runs independently in a new execution context.
+**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.
### Key Principles
@@ -383,9 +383,9 @@ try {
## Common Pitfalls
- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.
-- **Processing self-created activities** - Other users may change an Activity created by the agent, resulting in an \`activity\` call. Be sure to check the \`changes === null\` and/or \`activity.author.id !== this.id\` to avoid re-processing.
+- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \`activity\` call. Be sure to check the \`changes === null\` and/or \`activity.author.id !== this.id\` to avoid re-processing.
- Most activity should be `type = ActivityType.Note` with a `title` and `note`, and no `start` or `end`. This represents a typical message. `start` and `end` should only be used for a note if it should be displayed for a specific date or time, such as a birthday.
-- Tools are declared in the `build` method and accessed via `this.tools.toolName` in agent methods.
+- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.
- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.
- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.
- **Store auth tokens** - Don't re-request authentication unnecessarily.
diff --git a/builder/cli/templates/CLAUDE.template.md b/twister/cli/templates/CLAUDE.template.md
similarity index 100%
rename from builder/cli/templates/CLAUDE.template.md
rename to twister/cli/templates/CLAUDE.template.md
diff --git a/builder/cli/templates/README.template.md b/twister/cli/templates/README.template.md
similarity index 78%
rename from builder/cli/templates/README.template.md
rename to twister/cli/templates/README.template.md
index 3f41d17..6c49fb8 100644
--- a/builder/cli/templates/README.template.md
+++ b/twister/cli/templates/README.template.md
@@ -1,6 +1,6 @@
-# {{displayName}} Agent
+# {{displayName}} twist
-A Plot agent that [describe what your agent does].
+A Plot twist that [describe what your twist does].
## Quick Start
@@ -22,33 +22,33 @@ A Plot agent that [describe what your agent does].
```
.
├── src/
-│ └── index.ts # Main agent implementation
-├── package.json # Agent metadata and dependencies
+│ └── index.ts # Main twist implementation
+├── package.json # twist metadata and dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # This file
```
-### Agent Lifecycle
+### twist Lifecycle
-Your agent implements two key lifecycle methods:
+Your twist implements two key lifecycle methods:
#### `activate(priority: Pick)`
-Called when the agent is enabled for a priority. This is where you typically:
+Called when the twist is enabled for a priority. This is where you typically:
- Request authentication from external services
- Create initial setup activities
-- Initialize agent state
+- Initialize twist state
#### `activity(activity: Activity)`
-Called when an activity is routed to this agent. Use this to:
+Called when an activity is routed to this twist. Use this to:
- Process incoming activities
- Create new activities based on external events
- Update existing activities
### Using Tools
-Agents access functionality through tools. Declare tools in the `build` method:
+Twists access functionality through tools. Declare tools in the `build` method:
```typescript
build(build: ToolBuilder) {
@@ -62,7 +62,7 @@ build(build: ToolBuilder) {
#### Built-in Tools
- **Plot**: Create, update, and delete activities
-- **Store**: Persist data across agent invocations
+- **Store**: Persist data across twist invocations
- **Integrations**: Request OAuth authentication from external services
- **Tasks**: Queue background tasks and batch operations
- **Callbacks**: Create persistent function references for webhooks
@@ -75,13 +75,13 @@ Add external tool dependencies to `package.json`:
```json
{
"dependencies": {
- "@plotday/agent": "workspace:^",
+ "@plotday/twister": "workspace:^",
"@plotday/tool-google-calendar": "workspace:^"
}
}
```
-Then use them in your agent:
+Then use them in your twist:
```typescript
import GoogleCalendarTool from "@plotday/tool-google-calendar";
@@ -103,7 +103,7 @@ Plot supports three activity types:
### State Management
-Use Store methods (available directly on Agent and Tool classes) to persist data across agent invocations:
+Use Store methods (available directly on twist and Tool classes) to persist data across twist invocations:
```typescript
// Save state
@@ -113,13 +113,13 @@ await this.set("sync_token", token);
const token = await this.get("sync_token");
```
-**Important**: Agent instances are ephemeral. Always use Store methods for data that needs to persist.
+**Important**: twist instances are ephemeral. Always use Store methods for data that needs to persist.
### Runtime Limitations
-**Important**: All agent and tool functions are executed in a sandboxed, ephemeral environment with limited resources:
+**Important**: All twist and tool functions are executed in a sandboxed, ephemeral environment with limited resources:
-- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the agent/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.
+- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.
- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)
- **Use the Tasks tool**: Queue separate chunks of work with `this.run(callback)`
- **Break long operations**: Split large operations into smaller batches that can be processed independently
@@ -166,7 +166,7 @@ async syncBatch(args: any, context: { calendarId: string }): Promise {
## Testing
-Test your agent locally before deploying:
+Test your twist locally before deploying:
```bash
# Run linter
@@ -178,9 +178,9 @@ Test your agent locally before deploying:
## Resources
-- [Plot Agent Builder Documentation](https://github.com/plotday/plot)
-- [Agent Examples](https://github.com/plotday/plot/tree/main/libs/agent/examples)
-- [Tool Documentation](https://github.com/plotday/plot/tree/main/libs/agent/tools)
+- [Plot twist Builder Documentation](https://github.com/plotday/plot)
+- [twist Examples](https://github.com/plotday/plot/tree/main/libs/twist/examples)
+- [Tool Documentation](https://github.com/plotday/plot/tree/main/libs/twist/tools)
## Support
diff --git a/builder/cli/utils/bundle.ts b/twister/cli/utils/bundle.ts
similarity index 82%
rename from builder/cli/utils/bundle.ts
rename to twister/cli/utils/bundle.ts
index a91883d..f756743 100644
--- a/builder/cli/utils/bundle.ts
+++ b/twister/cli/utils/bundle.ts
@@ -14,37 +14,37 @@ export interface BundleResult {
}
/**
- * Bundles a Plot agent using esbuild.
+ * Bundles a Plot twist using esbuild.
*
* This function is shared between the build and deploy commands to ensure
* consistent bundling behavior.
*
- * @param agentPath - Absolute path to the agent directory
+ * @param twistPath - Absolute path to the twist directory
* @param options - Optional bundling configuration
* @returns Promise resolving to the bundled code and any warnings
* @throws Error if bundling fails
*/
-export async function bundleAgent(
- agentPath: string,
+export async function bundleTwist(
+ twistPath: string,
options: BundleOptions = {}
): Promise {
const { minify = false, sourcemap = true } = options;
- // Validate agent path exists
- if (!fs.existsSync(agentPath)) {
- throw new Error(`Agent directory not found: ${agentPath}`);
+ // Validate twist path exists
+ if (!fs.existsSync(twistPath)) {
+ throw new Error(`Twist directory not found: ${twistPath}`);
}
// Check for entry point
- const entryPoint = path.join(agentPath, "src", "index.ts");
+ const entryPoint = path.join(twistPath, "src", "index.ts");
if (!fs.existsSync(entryPoint)) {
throw new Error(
- "src/index.ts not found. Your agent needs an entry point at src/index.ts"
+ "src/index.ts not found. Your twist needs an entry point at src/index.ts"
);
}
// Create build directory
- const buildDir = path.join(agentPath, "build");
+ const buildDir = path.join(twistPath, "build");
if (fs.existsSync(buildDir)) {
fs.rmSync(buildDir, { recursive: true });
}
diff --git a/builder/cli/utils/output.ts b/twister/cli/utils/output.ts
similarity index 97%
rename from builder/cli/utils/output.ts
rename to twister/cli/utils/output.ts
index 909722d..3ceeacd 100644
--- a/builder/cli/utils/output.ts
+++ b/twister/cli/utils/output.ts
@@ -120,8 +120,8 @@ export function blank() {
* Print the CLI header with version
*/
export function cliHeader(version: string) {
- const title = "Plot";
- const subtitle = `Agent Builder v${version}`;
+ const title = "🌪️ Plot";
+ const subtitle = `Twister v${version}`;
const underline = colors.brand(
"─".repeat(title.length + subtitle.length + 1)
);
diff --git a/builder/cli/utils/packageManager.ts b/twister/cli/utils/packageManager.ts
similarity index 58%
rename from builder/cli/utils/packageManager.ts
rename to twister/cli/utils/packageManager.ts
index f5ece5c..fbb07fd 100644
--- a/builder/cli/utils/packageManager.ts
+++ b/twister/cli/utils/packageManager.ts
@@ -3,15 +3,15 @@ import * as path from "path";
/**
* Detects the package manager being used
- * Checks for npm_config_user_agent and lock files
+ * Checks for npm_config_user_twist and lock files
*/
export function detectPackageManager(): string {
- // Check npm_config_user_agent first (set by npm, yarn, pnpm)
- const userAgent = process.env.npm_config_user_agent;
- if (userAgent) {
- if (userAgent.includes("yarn")) return "yarn";
- if (userAgent.includes("pnpm")) return "pnpm";
- if (userAgent.includes("npm")) return "npm";
+ // Check npm_config_user_twist first (set by npm, yarn, pnpm)
+ const userTwist = process.env.npm_config_user_twist;
+ if (userTwist) {
+ if (userTwist.includes("yarn")) return "yarn";
+ if (userTwist.includes("pnpm")) return "pnpm";
+ if (userTwist.includes("npm")) return "npm";
}
// Check for lock files in current directory
diff --git a/builder/cli/utils/sse.ts b/twister/cli/utils/sse.ts
similarity index 100%
rename from builder/cli/utils/sse.ts
rename to twister/cli/utils/sse.ts
diff --git a/builder/cli/utils/token.ts b/twister/cli/utils/token.ts
similarity index 100%
rename from builder/cli/utils/token.ts
rename to twister/cli/utils/token.ts
diff --git a/builder/docs/ADVANCED.md b/twister/docs/ADVANCED.md
similarity index 93%
rename from builder/docs/ADVANCED.md
rename to twister/docs/ADVANCED.md
index 137ed96..20cb8d0 100644
--- a/builder/docs/ADVANCED.md
+++ b/twister/docs/ADVANCED.md
@@ -5,11 +5,11 @@ group: Guides
# Advanced Topics
-Advanced patterns and techniques for building sophisticated Plot agents.
+Advanced patterns and techniques for building sophisticated Plot twists.
## Table of Contents
-- [Complex Agent Architectures](#complex-agent-architectures)
+- [Complex twist Architectures](#complex-twist-architectures)
- [Error Handling](#error-handling)
- [Debugging and Logging](#debugging-and-logging)
- [Security Best Practices](#security-best-practices)
@@ -18,7 +18,7 @@ Advanced patterns and techniques for building sophisticated Plot agents.
---
-## Complex Agent Architectures
+## Complex twist Architectures
### Multi-Service Integration
@@ -29,10 +29,10 @@ import { GitHubTool } from "@mycompany/plot-github-tool";
import { JiraTool } from "@mycompany/plot-jira-tool";
import { SlackTool } from "@mycompany/plot-slack-tool";
-import { Agent, type Priority, type ToolBuilder } from "@plotday/agent";
-import { Plot } from "@plotday/agent/tools/plot";
+import { twist, type Priority, type ToolBuilder } from "@plotday/twister";
+import { Plot } from "@plotday/twister/tools/plot";
-export default class DevOpsAgent extends Agent {
+export default class DevOpsTwist extends twist {
build(build: ToolBuilder) {
return {
plot: build(Plot),
@@ -77,7 +77,7 @@ interface WorkflowData {
metadata: Record;
}
-class WorkflowAgent extends Agent {
+class WorkflowTwist extends twist {
async transitionTo(workflowId: string, newState: WorkflowState) {
const workflow = await this.get(`workflow:${workflowId}`);
if (!workflow) throw new Error("Workflow not found");
@@ -135,7 +135,7 @@ class WorkflowAgent extends Agent {
### Graceful Degradation
-Handle errors without breaking the agent:
+Handle errors without breaking the twist:
```typescript
async activate(priority: Pick) {
@@ -143,7 +143,7 @@ async activate(priority: Pick) {
await this.setupWebhooks();
} catch (error) {
console.error("Failed to setup webhooks:", error);
- // Agent still activates, just without webhooks
+ // twist still activates, just without webhooks
// Consider creating an activity to notify the user
await this.tools.plot.createActivity({
type: ActivityType.Note,
@@ -242,13 +242,13 @@ Use consistent log formats:
```typescript
interface LogContext {
- agentId: string;
+ twistId: string;
priorityId?: string;
operation: string;
[key: string]: any;
}
-class MyAgent extends Agent {
+class MyTwist extends twist {
private log(
level: "info" | "warn" | "error",
message: string,
@@ -258,7 +258,7 @@ class MyAgent extends Agent {
timestamp: new Date().toISOString(),
level,
message,
- agent: this.id,
+ twist: this.id,
...context,
};
@@ -266,7 +266,7 @@ class MyAgent extends Agent {
}
async activate(priority: Pick) {
- this.log("info", "Agent activating", {
+ this.log("info", "twist activating", {
priorityId: priority.id,
operation: "activate",
});
@@ -289,7 +289,7 @@ class MyAgent extends Agent {
Add debug flag for verbose logging:
```typescript
-class MyAgent extends Agent {
+class MyTwist extends twist {
private get debugMode(): Promise {
return this.get("debug_mode").then((v) => v ?? false);
}
@@ -429,15 +429,15 @@ async fetchData() {
### Version Tracking
-Track agent version for migrations:
+Track twist version for migrations:
```typescript
async activate(priority: Pick) {
- await this.set("agent_version", "1.0.0");
+ await this.set("twist_version", "1.0.0");
}
async upgrade() {
- const currentVersion = await this.get("agent_version") || "0.0.0";
+ const currentVersion = await this.get("twist_version") || "0.0.0";
if (this.compareVersions(currentVersion, "2.0.0") < 0) {
await this.migrateToV2();
@@ -447,7 +447,7 @@ async upgrade() {
await this.migrateToV21();
}
- await this.set("agent_version", "2.1.0");
+ await this.set("twist_version", "2.1.0");
}
```
@@ -514,7 +514,7 @@ async upgrade() {
Load data only when needed:
```typescript
-class MyAgent extends Agent {
+class MyTwist extends twist {
private _config: Config | null = null;
private async getConfig(): Promise {
diff --git a/builder/docs/BUILDING_TOOLS.md b/twister/docs/BUILDING_TOOLS.md
similarity index 89%
rename from builder/docs/BUILDING_TOOLS.md
rename to twister/docs/BUILDING_TOOLS.md
index 778e48d..5dd9e4d 100644
--- a/builder/docs/BUILDING_TOOLS.md
+++ b/twister/docs/BUILDING_TOOLS.md
@@ -5,7 +5,7 @@ group: Guides
# Building Custom Tools
-Custom tools let you create reusable functionality that can be shared across agents or published for others to use. This guide covers everything you need to know about building tools.
+Custom tools let you create reusable functionality that can be shared across twists or published for others to use. This guide covers everything you need to know about building tools.
## Table of Contents
@@ -28,7 +28,7 @@ Build custom tools when you need to:
- **Integrate external services** - GitHub, Slack, Notion, etc.
- **Encapsulate complex logic** - Reusable business logic
-- **Share functionality** - Between multiple agents
+- **Share functionality** - Between multiple twists
- **Abstract implementation details** - Clean interfaces for common operations
### Built-in vs. Custom Tools
@@ -37,7 +37,7 @@ Build custom tools when you need to:
| ------------------------------ | ------------------------------------ |
| Plot, Store, AI, Network, etc. | Your integrations and utilities |
| Access to Plot internals | Built on top of built-in tools |
-| Provided by Agent Builder | Created by you or installed from npm |
+| Provided by twist Builder | Created by you or installed from npm |
| Always available | Declared as dependencies |
---
@@ -49,7 +49,7 @@ Tools extend the `Tool` base class and can access other tools through depende
### Minimal Tool Example
```typescript
-import { Tool, type ToolBuilder } from "@plotday/agent";
+import { Tool, type ToolBuilder } from "@plotday/twister";
export class HelloTool extends Tool {
async sayHello(name: string): Promise {
@@ -61,11 +61,11 @@ export class HelloTool extends Tool {
### Using Your Tool
```typescript
-import { Agent, type ToolBuilder } from "@plotday/agent";
+import { twist, type ToolBuilder } from "@plotday/twister";
import { HelloTool } from "./tools/hello";
-export default class MyAgent extends Agent {
+export default class MyTwist extends twist {
build(build: ToolBuilder) {
return {
hello: build(HelloTool),
@@ -86,7 +86,7 @@ export default class MyAgent extends Agent {
### Class Definition
```typescript
-import { Tool, type ToolBuilder } from "@plotday/agent";
+import { Tool, type ToolBuilder } from "@plotday/twister";
// Tool class with type parameter
export class MyTool extends Tool {
@@ -114,15 +114,15 @@ The type parameter `` enables:
## Lifecycle Methods
-Tools have lifecycle methods that run at specific times during the agent lifecycle.
+Tools have lifecycle methods that run at specific times during the twist lifecycle.
### preActivate(priority)
-Called **before** the agent's `activate()` method, depth-first.
+Called **before** the twist's `activate()` method, depth-first.
```typescript
async preActivate(priority: Priority): Promise {
- // Setup that needs to happen before agent activation
+ // Setup that needs to happen before twist activation
console.log("Tool preparing for activation");
// Initialize connections, validate configuration, etc.
@@ -137,11 +137,11 @@ async preActivate(priority: Priority): Promise {
### postActivate(priority)
-Called **after** the agent's `activate()` method, reverse order.
+Called **after** the twist's `activate()` method, reverse order.
```typescript
async postActivate(priority: Priority): Promise {
- // Finalization after agent is activated
+ // Finalization after twist is activated
console.log("Tool finalizing activation");
// Start background processes, register webhooks, etc.
@@ -156,7 +156,7 @@ async postActivate(priority: Priority): Promise {
### preUpgrade()
-Called **before** the agent's `upgrade()` method.
+Called **before** the twist's `upgrade()` method.
```typescript
async preUpgrade(): Promise {
@@ -171,7 +171,7 @@ async preUpgrade(): Promise {
### postUpgrade()
-Called **after** the agent's `upgrade()` method.
+Called **after** the twist's `upgrade()` method.
```typescript
async postUpgrade(): Promise {
@@ -182,7 +182,7 @@ async postUpgrade(): Promise {
### preDeactivate()
-Called **before** the agent's `deactivate()` method.
+Called **before** the twist's `deactivate()` method.
```typescript
async preDeactivate(): Promise {
@@ -193,7 +193,7 @@ async preDeactivate(): Promise {
### postDeactivate()
-Called **after** the agent's `deactivate()` method.
+Called **after** the twist's `deactivate()` method.
```typescript
async postDeactivate(): Promise {
@@ -205,14 +205,14 @@ async postDeactivate(): Promise {
### Execution Order
```
-Agent Activation:
+twist Activation:
1. Tool.preActivate() (deepest dependencies first)
- 2. Agent.activate()
+ 2. twist.activate()
3. Tool.postActivate() (top-level tools first)
-Agent Deactivation:
+twist Deactivation:
1. Tool.preDeactivate() (deepest dependencies first)
- 2. Agent.deactivate()
+ 2. twist.deactivate()
3. Tool.postDeactivate() (top-level tools first)
```
@@ -225,9 +225,9 @@ Tools can depend on other tools, including built-in tools.
### Declaring Dependencies
```typescript
-import { Tool, type ToolBuilder } from "@plotday/agent";
-import { Network } from "@plotday/agent/tools/network";
-import { Store } from "@plotday/agent/tools/store";
+import { Tool, type ToolBuilder } from "@plotday/twister";
+import { Network } from "@plotday/twister/tools/network";
+import { Store } from "@plotday/twister/tools/store";
export class GitHubTool extends Tool {
// Declare dependencies
@@ -292,7 +292,7 @@ Tools can accept configuration options when declared.
### Defining Options
```typescript
-import { Tool, type ToolBuilder, type InferOptions } from "@plotday/agent";
+import { Tool, type ToolBuilder, type InferOptions } from "@plotday/twister";
export class SlackTool extends Tool {
// Define static Options type
@@ -354,10 +354,10 @@ static Options = {
A complete GitHub integration with webhooks and issue management.
```typescript
-import { type Priority, Tool, type ToolBuilder } from "@plotday/agent";
-import { ActivityLinkType, ActivityType } from "@plotday/agent";
-import { Network, type WebhookRequest } from "@plotday/agent/tools/network";
-import { Plot } from "@plotday/agent/tools/plot";
+import { type Priority, Tool, type ToolBuilder } from "@plotday/twister";
+import { ActivityLinkType, ActivityType } from "@plotday/twister";
+import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
+import { Plot } from "@plotday/twister/tools/plot";
export class GitHubTool extends Tool {
static Options = {
@@ -490,8 +490,8 @@ export class GitHubTool extends Tool {
A tool for sending Slack notifications.
```typescript
-import { Tool, type ToolBuilder } from "@plotday/agent";
-import { Network } from "@plotday/agent/tools/network";
+import { Tool, type ToolBuilder } from "@plotday/twister";
+import { Network } from "@plotday/twister/tools/network";
export class SlackTool extends Tool {
static Options = {
@@ -580,15 +580,15 @@ describe("GitHubTool", () => {
### Integration Testing
-Test your tool with a real agent:
+Test your tool with a real twist:
```typescript
-import { Agent, type ToolBuilder } from "@plotday/agent";
-import { Plot } from "@plotday/agent/tools/plot";
+import { twist, type ToolBuilder } from "@plotday/twister";
+import { Plot } from "@plotday/twister/tools/plot";
import { GitHubTool } from "./github-tool";
-class TestAgent extends Agent {
+class TestTwist extends twist {
build(build: ToolBuilder) {
return {
plot: build(Plot),
@@ -629,7 +629,7 @@ my-plot-tool/
{
"name": "@mycompany/plot-github-tool",
"version": "1.0.0",
- "description": "GitHub integration tool for Plot agents",
+ "description": "GitHub integration tool for Plot twists",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"scripts": {
@@ -637,10 +637,10 @@ my-plot-tool/
"test": "vitest"
},
"peerDependencies": {
- "@plotday/agent": "^0.16.0"
+ "@plotday/twister": "^0.16.0"
},
"devDependencies": {
- "@plotday/agent": "^0.16.0",
+ "@plotday/twister": "^0.16.0",
"typescript": "^5.0.0"
}
}
diff --git a/builder/docs/CLI_REFERENCE.md b/twister/docs/CLI_REFERENCE.md
similarity index 74%
rename from builder/docs/CLI_REFERENCE.md
rename to twister/docs/CLI_REFERENCE.md
index 64abe2c..d5e4266 100644
--- a/builder/docs/CLI_REFERENCE.md
+++ b/twister/docs/CLI_REFERENCE.md
@@ -11,7 +11,7 @@ Complete reference for the Plot CLI (`plot` command).
- [Installation](#installation)
- [Authentication](#authentication)
-- [Agent Commands](#agent-commands)
+- [twist Commands](#twist-commands)
- [Priority Commands](#priority-commands)
- [Global Options](#global-options)
@@ -23,10 +23,10 @@ The Plot CLI is included with the Builder:
```bash
# Run directly with npx
-npx @plotday/agent [command]
+npx @plotday/twister [command]
# Or install globally
-npm install -g @plotday/agent
+npm install -g @plotday/twister
plot [command]
```
@@ -46,17 +46,17 @@ This will:
1. Open your browser to the Plot authentication page
2. After authentication, save your API token locally
-3. Enable deploying and managing agents
+3. Enable deploying and managing twists
**Token Storage**: The token is stored in `~/.plot/config.json`
---
-## Agent Commands
+## twist Commands
### plot create
-Scaffold a new agent project with TypeScript.
+Scaffold a new twist project with TypeScript.
```bash
plot create [options]
@@ -71,25 +71,25 @@ plot create [options]
**Example:**
```bash
-plot create --name my-calendar-agent --display-name "My Calendar Agent"
+plot create --name my-calendar-twist --display-name "My Calendar twist"
```
**Creates:**
```
-my-calendar-agent/
+my-calendar-twist/
├── src/
│ └── index.ts
├── package.json
├── tsconfig.json
-└── plot-agent.json
+└── plot-twist.json
```
---
### plot generate
-Generate TypeScript code from a natural language `plot-agent.md` specification.
+Generate TypeScript code from a natural language `plot-twist.md` specification.
```bash
plot generate [options]
@@ -97,7 +97,7 @@ plot generate [options]
**Options:**
-- `--input ` - Path to plot-agent.md (default: `./plot-agent.md`)
+- `--input ` - Path to plot-twist.md (default: `./plot-twist.md`)
- `--output ` - Output directory (default: `./src`)
- `--overwrite` - Overwrite existing files
@@ -111,7 +111,7 @@ plot generate --input ./my-spec.md --output ./src
### plot lint
-Check agent code for errors without deploying.
+Check twist code for errors without deploying.
```bash
plot lint [options]
@@ -119,19 +119,19 @@ plot lint [options]
**Options:**
-- `--dir ` - Agent directory (default: current directory)
+- `--dir ` - twist directory (default: current directory)
**Example:**
```bash
-plot lint --dir ./my-agent
+plot lint --dir ./my-twist
```
---
### plot deploy
-Deploy an agent to Plot.
+Deploy an twist to Plot.
```bash
plot deploy [options]
@@ -139,26 +139,26 @@ plot deploy [options]
**Options:**
-- `--agent-id ` - Update existing agent (creates new if not specified)
-- `--name ` - Agent name
-- `--description ` - Agent description
+- `--twist-id ` - Update existing twist (creates new if not specified)
+- `--name ` - twist name
+- `--description ` - twist description
- `--source ` - Source directory (default: `./src`)
- `--env ` - Environment (default: `production`)
- `--dry-run` - Validate without deploying
**Behavior:**
-- If `plot-agent.md` exists: Generates code and deploys in one step
+- If `plot-twist.md` exists: Generates code and deploys in one step
- Otherwise: Deploys compiled TypeScript from `src/`
**Example:**
```bash
-# Deploy new agent
+# Deploy new twist
plot deploy
-# Update existing agent
-plot deploy --agent-id ag_1234567890
+# Update existing twist
+plot deploy --twist-id ag_1234567890
# Dry run
plot deploy --dry-run
@@ -168,27 +168,27 @@ plot deploy --dry-run
### plot logs
-Stream real-time logs from an agent.
+Stream real-time logs from an twist.
```bash
-plot logs [agent-id] [options]
+plot logs [twist-id] [options]
```
**Options:**
-- `--id ` - Agent ID
-- `--dir ` - Agent directory (default: current directory)
-- `--environment ` - Agent environment (personal, private, review) (default: personal)
+- `--id ` - twist ID
+- `--dir ` - twist directory (default: current directory)
+- `--environment ` - twist environment (personal, private, review) (default: personal)
- `--deploy-token ` - Authentication token
**Example:**
```bash
-# Stream logs for an agent
+# Stream logs for an twist
plot logs ag_1234567890
-# Stream logs using agent in current directory
-plot logs --dir ./my-agent
+# Stream logs using twist in current directory
+plot logs --dir ./my-twist
```
---
@@ -281,7 +281,7 @@ Edit the config file to set default options:
{
"defaults": {
"environment": "staging",
- "agentSourceDir": "./dist"
+ "twistSourceDir": "./dist"
}
}
```
@@ -307,16 +307,16 @@ plot deploy
## Common Workflows
-### Create and Deploy a New Agent
+### Create and Deploy a New twist
```bash
# 1. Create project
-plot create --name my-agent
+plot create --name my-twist
# 2. Navigate to directory
-cd my-agent
+cd my-twist
-# 3. Implement agent
+# 3. Implement twist
# Edit src/index.ts
# 4. Login (if not already authenticated)
@@ -326,7 +326,7 @@ plot login
npm run deploy
```
-### Update an Existing Agent
+### Update an Existing twist
```bash
# 1. Make changes to src/index.ts
@@ -335,14 +335,14 @@ npm run deploy
npm run build
# 3. Deploy update
-plot deploy --agent-id ag_1234567890
+plot deploy --twist-id ag_1234567890
```
-### No-Code Agent Deployment
+### No-Code twist Deployment
```bash
-# 1. Create plot-agent.md
-# Describe your agent in plain English
+# 1. Create plot-twist.md
+# Describe your twist in plain English
# 2. Login
plot login
@@ -389,6 +389,6 @@ plot deploy --verbose
## Next Steps
-- **[Getting Started](GETTING_STARTED.md)** - Learn how to build agents
-- **[Core Concepts](CORE_CONCEPTS.md)** - Understand the agent architecture
+- **[Getting Started](GETTING_STARTED.md)** - Learn how to build twists
+- **[Core Concepts](CORE_CONCEPTS.md)** - Understand the twist architecture
- **[Built-in Tools](TOOLS_GUIDE.md)** - Explore available tools
diff --git a/builder/docs/CORE_CONCEPTS.md b/twister/docs/CORE_CONCEPTS.md
similarity index 83%
rename from builder/docs/CORE_CONCEPTS.md
rename to twister/docs/CORE_CONCEPTS.md
index 1c66354..caa481d 100644
--- a/builder/docs/CORE_CONCEPTS.md
+++ b/twister/docs/CORE_CONCEPTS.md
@@ -5,12 +5,12 @@ group: Guides
# Core Concepts
-Understanding these core concepts will help you build effective Plot agents.
+Understanding these core concepts will help you build effective Plot Twists.
## Table of Contents
-- [Agents](#agents)
-- [Tools](#tools)
+- [Twists](#twists)
+- [Twist Tools](#twist-tools)
- [Priorities](#priorities)
- [Activities](#activities)
- [Lifecycle Methods](#lifecycle-methods)
@@ -18,26 +18,26 @@ Understanding these core concepts will help you build effective Plot agents.
---
-## Agents
+## Twists
-Agents are the core building blocks of Plot automation. They implement integrations and automations that help organize and prioritize your work.
+Twists are smart automations that connect, organize, and prioritize your work. They implement opinionated workflows and integrations.
-### What is an Agent?
+### What is a Twist?
-An agent is a class that:
+A twist is a class that:
-- Extends the `Agent` base class
+- Extends the `Twist` base class
- Declares tool dependencies in the `build()` method
- Responds to lifecycle events (`activate`, `deactivate`, `upgrade`)
- Can process activities and create new ones
-### Agent Anatomy
+### Twist Anatomy
```typescript
-import { Agent, type Priority, type ToolBuilder } from "@plotday/agent";
-import { Plot } from "@plotday/agent/tools/plot";
+import { Twist, type Priority, type ToolBuilder } from "@plotday/twister";
+import { Plot } from "@plotday/twister/tools/plot";
-export default class MyAgent extends Agent {
+export default class MyTwist extends Twist {
// 1. Declare dependencies
build(build: ToolBuilder) {
return {
@@ -47,7 +47,7 @@ export default class MyAgent extends Agent {
// 2. Initialize on activation
async activate(priority: Pick) {
- // Setup code - runs once when agent is added to a priority
+ // Setup code - runs once when twist is added to a priority
}
// 3. Handle lifecycle events
@@ -56,14 +56,14 @@ export default class MyAgent extends Agent {
}
async deactivate() {
- // Cleanup - runs when agent is removed
+ // Cleanup - runs when twist is removed
}
}
```
-### When to Use Agents
+### When to Use Twists
-Use agents for:
+Use twists for:
- **Integrations** - Connecting external services (Google Calendar, GitHub, Slack)
- **Automations** - Automatic task creation, reminders, status updates
@@ -72,15 +72,15 @@ Use agents for:
---
-## Tools
+## Twist Tools
-Tools provide functionality to agents. They encapsulate reusable capabilities and can be composed together.
+Twist tools provide capabilities to twists. They are usually unopinionated and do nothing on their own. Tools encapsulate reusable capabilities and can be composed together.
### Types of Tools
#### 1. Built-in Tools
-Core Plot functionality provided by the Builder:
+Core Plot functionality provided by the Twist Creator:
- **Plot** - Create and manage activities and priorities
- **Store** - Persistent key-value storage
@@ -104,7 +104,7 @@ See [Building Custom Tools](BUILDING_TOOLS.md) to create your own.
### Declaring Tool Dependencies
-Use the `build()` method to declare which tools your agent needs:
+Use the `build()` method to declare which tools your twist needs:
```typescript
build(build: ToolBuilder) {
@@ -128,14 +128,14 @@ async activate(priority: Pick) {
// Tools are fully typed
await this.tools.plot.createActivity({
type: ActivityType.Note,
- title: "Hello from my agent"
+ title: "Hello from my twist"
});
}
```
### Direct Access Methods
-Some tool methods are available directly on the Agent class for convenience:
+Some tool methods are available directly on the Twist class for convenience:
```typescript
// Store
@@ -185,13 +185,13 @@ const projectA = await this.tools.plot.createPriority({
});
```
-### Agent Activation
+### Twist Activation
-Agents are activated within a specific priority. When activated, the agent has access to that priority and all its children.
+Twists are activated within a specific priority. When activated, the twist has access to that priority and all its children.
```typescript
async activate(priority: Pick) {
- // This agent is now active for this priority
+ // This twist is now active for this priority
// It can create activities, set up webhooks, etc.
}
```
@@ -209,7 +209,7 @@ Activities are the core data type in Plot, representing tasks, events, and notes
- **Event** - Scheduled occurrences with start/end times
```typescript
-import { ActivityType } from "@plotday/agent";
+import { ActivityType } from "@plotday/twister";
// Note
await this.tools.plot.createActivity({
@@ -255,7 +255,7 @@ type Activity = {
Links enable user interaction with activities:
```typescript
-import { ActivityLinkType } from "@plotday/agent";
+import { ActivityLinkType } from "@plotday/twister";
await this.tools.plot.createActivity({
type: ActivityType.Task,
@@ -279,17 +279,17 @@ await this.tools.plot.createActivity({
- **external** - Opens URL in browser
- **auth** - Initiates OAuth flow
-- **callback** - Triggers agent method when clicked
+- **callback** - Triggers twist method when clicked
---
## Lifecycle Methods
-Agents have several lifecycle methods that are called at specific times.
+Twists have several lifecycle methods that are called at specific times.
### activate(priority)
-Called when the agent is first activated for a priority.
+Called when the twist is first activated for a priority.
**Use for:**
@@ -314,7 +314,7 @@ async activate(priority: Pick) {
### upgrade()
-Called when a new version of your agent is deployed to an existing priority.
+Called when a new version of your twist is deployed to an existing priority.
**Use for:**
@@ -340,7 +340,7 @@ async upgrade() {
### deactivate()
-Called when the agent is removed from a priority.
+Called when the twist is removed from a priority.
**Use for:**
@@ -371,12 +371,12 @@ Use the Store tool for persistent state, not instance variables:
```typescript
// ❌ WRONG - Instance variables don't persist
-class MyAgent extends Agent {
+class MyTwist extends Twist {
private syncToken: string; // This will be lost!
}
// ✅ CORRECT - Use Store
-class MyAgent extends Agent {
+class MyTwist extends Twist {
async getSyncToken() {
return await this.get("sync_token");
}
@@ -396,11 +396,11 @@ async activate(priority: Pick) {
try {
await this.tools.plot.createActivity({
type: ActivityType.Note,
- title: "Agent activated"
+ title: "Twist activated"
});
} catch (error) {
console.error("Failed to create activity:", error);
- // Agent activation continues even if this fails
+ // Twist activation continues even if this fails
}
}
```
diff --git a/builder/docs/GETTING_STARTED.md b/twister/docs/GETTING_STARTED.md
similarity index 58%
rename from builder/docs/GETTING_STARTED.md
rename to twister/docs/GETTING_STARTED.md
index 43e0ffe..de8abef 100644
--- a/builder/docs/GETTING_STARTED.md
+++ b/twister/docs/GETTING_STARTED.md
@@ -3,29 +3,29 @@ title: Getting Started
group: Guides
---
-# Getting Started with Plot Agents
+# Getting Started with Plot Twists
-This guide will walk you through creating your first Plot agent. There are two ways to build agents: with natural language (no code) or with TypeScript code for maximum flexibility.
+This guide will walk you through creating your first Plot Twist. There are two ways to build twists: with natural language (no code) or with TypeScript code for maximum flexibility.
## Choose Your Path
-- **[No-Code Agents](#no-code-agents)** - Perfect for non-developers or rapid prototyping
-- **[Developer Agents](#developer-agents)** - Full control with TypeScript
+- **[No-Code Twists](#no-code-twists)** - Perfect for non-developers or rapid prototyping
+- **[Developer Twists](#developer-twists)** - Full control with TypeScript
---
-## No-Code Agents
+## No-Code Twists
-Create agents using natural language descriptions - no programming required!
+Create twists using natural language descriptions - no programming required!
-### Step 1: Create a plot-agent.md File
+### Step 1: Create a plot-twist.md File
-Create a file named `plot-agent.md` in your project directory and describe what you want your agent to do:
+Create a file named `plot-twist.md` in your project directory and describe what you want your twist to do:
```markdown
-# My Calendar Agent
+# My Calendar Twist
-I want an agent that:
+I want a twist that:
- Syncs my Google Calendar events into Plot as activities
- Creates tasks for upcoming meetings
@@ -36,22 +36,22 @@ I want an agent that:
**Be specific about:**
- **Data sources** - Which services to connect (Google Calendar, GitHub, Slack, etc.)
-- **Actions** - What the agent should do (create tasks, send notifications, update status)
+- **Actions** - What the twist should do (create tasks, send notifications, update status)
- **Triggers** - When actions should happen (on new events, on schedule, when activities change)
-### Step 2: Deploy Your Agent
+### Step 2: Deploy Your Twist
-You'll need a [Plot account](https://plot.day) to deploy agents.
+You'll need a [Plot account](https://plot.day) to deploy twists.
```bash
# Login to Plot
-npx @plotday/agent login
+npx @plotday/twister login
# Deploy directly from your spec
-npx @plotday/agent deploy
+npx @plotday/twister deploy
```
-That's it! Your agent is now live in Plot.
+That's it! Your twist is now live in Plot.
### Optional: Generate Code First
@@ -59,64 +59,64 @@ If you want to review or customize the generated code before deploying:
```bash
# Generate TypeScript code from your spec
-npx @plotday/agent generate
+npx @plotday/twister generate
# Review and edit the generated src/index.ts
# Then deploy
-npx @plotday/agent deploy
+npx @plotday/twister deploy
```
-The `generate` command creates a complete TypeScript agent that you can modify and extend.
+The `generate` command creates a complete TypeScript twist that you can modify and extend.
---
-## Developer Agents
+## Developer Twists
-Build agents with full control using TypeScript.
+Build twists with full control using TypeScript.
-### Step 1: Create a New Agent Project
+### Step 1: Create a New Twist Project
-Use the Plot CLI to scaffold a new agent:
+Use the Plot CLI to scaffold a new twist:
```bash
-npx @plotday/agent create
+npx @plotday/twister create
# or
-yarn dlx @plotday/agent create
+yarn dlx @plotday/twister create
# or
-pnpm dlx @plotday/agent create
+pnpm dlx @plotday/twister create
```
You'll be prompted for:
-- **Package name** (kebab-case, e.g., `my-calendar-agent`)
-- **Display name** (human-readable, e.g., "My Calendar Agent")
+- **Package name** (kebab-case, e.g., `my-calendar-twist`)
+- **Display name** (human-readable, e.g., "My Calendar Twist")
This creates a new directory with:
```
-my-calendar-agent/
+my-calendar-twist/
├── src/
-│ └── index.ts # Your agent code
+│ └── index.ts # Your twist code
├── package.json
├── tsconfig.json
-└── plot-agent.json # Agent configuration
+└── plot-twist.json # Twist configuration
```
-### Step 2: Implement Your Agent
+### Step 2: Implement Your Twist
-Edit `src/index.ts` to add your agent logic:
+Edit `src/index.ts` to add your twist logic:
```typescript
import {
type Activity,
ActivityType,
- Agent,
+ Twist,
type Priority,
type ToolBuilder,
-} from "@plotday/agent";
-import { Plot } from "@plotday/agent/tools/plot";
+} from "@plotday/twister";
+import { Plot } from "@plotday/twister/tools/plot";
-export default class MyAgent extends Agent {
+export default class MyTwist extends Twist {
// Declare tool dependencies
build(build: ToolBuilder) {
return {
@@ -124,15 +124,15 @@ export default class MyAgent extends Agent {
};
}
- // Called when the agent is activated for a priority
+ // Called when the twist is activated for a priority
async activate(priority: Pick) {
await this.tools.plot.createActivity({
type: ActivityType.Note,
- title: "Welcome! Your agent is now active.",
+ title: "Welcome! Your twist is now active.",
});
}
- // Called when an activity is routed to this agent
+ // Called when an activity is routed to this twist
async activity(activity: Activity) {
console.log("Processing activity:", activity.title);
}
@@ -151,39 +151,39 @@ pnpm build
### Step 4: Deploy
-You'll need a [Plot account](https://plot.day) to deploy agents.
+You'll need a [Plot account](https://plot.day) to deploy twists.
```bash
# Login to Plot
npm run plot login
-# Deploy your agent
+# Deploy your twist
npm run deploy
```
-Your agent is now deployed and ready to activate in Plot!
+Your twist is now deployed and ready to activate in Plot!
---
## Understanding the Project Structure
-### Agent File (src/index.ts)
+### Twist File (src/index.ts)
-Your agent extends the `Agent` class and implements:
+Your twist extends the `Twist` class and implements:
- **`build()`** - Declares tool dependencies
- **`activate()`** - Initialization when added to a priority
- **`deactivate()`** - Cleanup when removed from a priority
- **`upgrade()`** - Migration when deploying a new version
-### Configuration (plot-agent.json)
+### Configuration (plot-twist.json)
-Contains agent metadata:
+Contains twist metadata:
```json
{
- "name": "my-calendar-agent",
- "displayName": "My Calendar Agent",
+ "name": "my-calendar-twist",
+ "displayName": "My Calendar Twist",
"version": "1.0.0",
"description": "Syncs calendar events to Plot"
}
@@ -191,11 +191,11 @@ Contains agent metadata:
### TypeScript Config (tsconfig.json)
-Extends the Builder's base configuration:
+Extends the Twist Creator's base configuration:
```json
{
- "extends": "@plotday/agent/tsconfig.base.json",
+ "extends": "@plotday/twister/tsconfig.base.json",
"include": ["src/*.ts"]
}
```
@@ -204,11 +204,11 @@ Extends the Builder's base configuration:
## Next Steps
-Now that you have a basic agent running, explore:
+Now that you have a basic twist running, explore:
-- **[Core Concepts](CORE_CONCEPTS.md)** - Understand agents, tools, and the Plot architecture
+- **[Core Concepts](CORE_CONCEPTS.md)** - Understand twists, tools, and the Plot architecture
- **[Built-in Tools](TOOLS_GUIDE.md)** - Learn about Plot, Store, Integrations, AI, and more
-- **[Building Custom Tools](BUILDING_TOOLS.md)** - Create your own reusable tools
+- **[Building Custom Tools](BUILDING_TOOLS.md)** - Create your own reusable twist tools
- **[Runtime Environment](RUNTIME.md)** - Understand execution constraints and optimization
## Common First Tasks
@@ -256,5 +256,5 @@ await this.runTask(callback, {
## Need Help?
- **Documentation**: Continue reading the guides
-- **Examples**: Check the [examples directory](https://github.com/plotday/plot/tree/main/agents)
+- **Examples**: Check the [examples directory](https://github.com/plotday/plot/tree/main/twists)
- **Issues**: [Report bugs or request features](https://github.com/plotday/plot/issues)
diff --git a/builder/docs/RUNTIME.md b/twister/docs/RUNTIME.md
similarity index 97%
rename from builder/docs/RUNTIME.md
rename to twister/docs/RUNTIME.md
index 53ed1a8..849a851 100644
--- a/builder/docs/RUNTIME.md
+++ b/twister/docs/RUNTIME.md
@@ -5,7 +5,7 @@ group: Guides
# Runtime Environment
-Understanding the Plot runtime environment will help you build efficient, reliable agents.
+Understanding the Plot runtime environment will help you build efficient, reliable twists.
## Table of Contents
@@ -21,7 +21,7 @@ Understanding the Plot runtime environment will help you build efficient, reliab
## Execution Model
-Plot agents run in a **sandboxed, serverless environment** with the following characteristics:
+Plot twists run in a **sandboxed, serverless environment** with the following characteristics:
### Ephemeral Execution
@@ -32,7 +32,7 @@ Plot agents run in a **sandboxed, serverless environment** with the following ch
### Event-Driven
-Agents respond to events:
+Twists respond to events:
- **Lifecycle events** - activate, upgrade, deactivate
- **Activity events** - New or updated activities
@@ -57,7 +57,7 @@ Instance variables don't survive between invocations:
```typescript
// ❌ WRONG - This doesn't work!
-class MyAgent extends Agent {
+class MyTwist extends twist {
private syncToken: string = ""; // Lost after execution!
async activate() {
@@ -70,7 +70,7 @@ class MyAgent extends Agent {
}
// ✅ CORRECT - Use Store
-class MyAgent extends Agent {
+class MyTwist extends twist {
async activate() {
await this.set("sync_token", "abc123"); // Persisted
}
@@ -550,4 +550,4 @@ async longOperation() {
- **[Built-in Tools Guide](TOOLS_GUIDE.md)** - Learn about Store and Tasks tools
- **[Advanced Topics](ADVANCED.md)** - Complex patterns and techniques
-- **[Core Concepts](CORE_CONCEPTS.md)** - Understanding the agent architecture
+- **[Core Concepts](CORE_CONCEPTS.md)** - Understanding the twist architecture
diff --git a/builder/docs/TOOLS_GUIDE.md b/twister/docs/TOOLS_GUIDE.md
similarity index 95%
rename from builder/docs/TOOLS_GUIDE.md
rename to twister/docs/TOOLS_GUIDE.md
index bda6072..661344b 100644
--- a/builder/docs/TOOLS_GUIDE.md
+++ b/twister/docs/TOOLS_GUIDE.md
@@ -5,7 +5,7 @@ group: Guides
# Built-in Tools
-Plot provides a comprehensive set of built-in tools that give your agents powerful capabilities. This guide covers all built-in tools with detailed examples and best practices.
+Plot provides a comprehensive set of built-in tools that give your twists powerful capabilities. This guide covers all built-in tools with detailed examples and best practices.
## Table of Contents
@@ -26,7 +26,7 @@ The Plot tool is the core interface for creating and managing activities and pri
### Setup
```typescript
-import { Plot } from "@plotday/agent/tools/plot";
+import { Plot } from "@plotday/twister/tools/plot";
build(build: ToolBuilder) {
return {
@@ -38,7 +38,7 @@ build(build: ToolBuilder) {
### Creating Activities
```typescript
-import { ActivityLinkType, ActivityType } from "@plotday/agent";
+import { ActivityLinkType, ActivityType } from "@plotday/twister";
// Create a note
await this.tools.plot.createActivity({
@@ -136,7 +136,7 @@ const activity = await this.tools.plot.getActivityByMeta({
## Store
-Persistent key-value storage for agent state. Store methods are available directly on the Agent class.
+Persistent key-value storage for twist state. Store methods are available directly on the twist class.
### Setup
@@ -178,7 +178,7 @@ if (value === null) {
// Clear a specific key
await this.clear("last_sync");
-// Clear all data for this agent
+// Clear all data for this twist
await this.clearAll();
```
@@ -236,7 +236,7 @@ OAuth authentication for external services (Google, Microsoft, etc.).
### Setup
```typescript
-import { Integrations } from "@plotday/agent/tools/integrations";
+import { Integrations } from "@plotday/twister/tools/integrations";
build(build: ToolBuilder) {
return {
@@ -248,8 +248,8 @@ build(build: ToolBuilder) {
### Requesting Authentication
```typescript
-import { AuthLevel, AuthProvider, type Authorization } from "@plotday/agent/tools/integrations";
-import { ActivityLinkType } from "@plotday/agent";
+import { AuthLevel, AuthProvider, type Authorization } from "@plotday/twister/tools/integrations";
+import { ActivityLinkType } from "@plotday/twister";
async activate(priority: Pick) {
// Create callback for auth completion
@@ -329,7 +329,7 @@ if (authorization) {
## Tasks
-Queue background tasks and schedule operations. Tasks methods are available directly on the Agent class.
+Queue background tasks and schedule operations. Tasks methods are available directly on the twist class.
### Setup
@@ -376,7 +376,7 @@ if (token) {
await this.cancelTask(token);
}
-// Cancel all scheduled tasks for this agent
+// Cancel all scheduled tasks for this twist
await this.cancelAllTasks();
```
@@ -432,7 +432,7 @@ Request HTTP access and create webhook endpoints for real-time notifications.
### Setup
```typescript
-import { Network, type WebhookRequest } from "@plotday/agent/tools/network";
+import { Network, type WebhookRequest } from "@plotday/twister/tools/network";
build(build: ToolBuilder) {
return {
@@ -516,7 +516,7 @@ async deactivate() {
## Callbacks
-Create persistent function references that survive worker restarts. Callbacks methods are available directly on the Agent class.
+Create persistent function references that survive worker restarts. Callbacks methods are available directly on the twist class.
### Setup
@@ -574,7 +574,7 @@ if (callback) {
await this.deleteCallback(callback);
}
-// Delete all callbacks for this agent
+// Delete all callbacks for this twist
await this.deleteAllCallbacks();
```
@@ -596,7 +596,7 @@ Prompt large language models with support for structured output and tool calling
### Setup
```typescript
-import { AI } from "@plotday/agent/tools/ai";
+import { AI } from "@plotday/twister/tools/ai";
build(build: ToolBuilder) {
return {
diff --git a/builder/docs/index.md b/twister/docs/index.md
similarity index 71%
rename from builder/docs/index.md
rename to twister/docs/index.md
index 4bbf279..c036e10 100644
--- a/builder/docs/index.md
+++ b/twister/docs/index.md
@@ -1,15 +1,15 @@
-Welcome to the Plot Agent Builder documentation! This comprehensive guide will help you build powerful agents that organize and prioritize activities in Plot.
+Welcome to the Plot Twist Creator documentation! This comprehensive guide will help you build powerful Twists that organize and prioritize your work.
-## What are Plot Agents?
+## What are Plot Twists?
-Plot agents are intelligent assistants that automatically manage your activities, tasks, and events. They can integrate with external services, process data, and help you stay organized across all your apps and messages.
+Plot Twists are smart automations that connect, organize, and prioritize your work. They implement opinionated workflows, integrate with external services, and help you stay organized across all your apps and messages.
## Documentation Structure
### Getting Started
-- **[Getting Started Guide](GETTING_STARTED.md)** - Complete walkthrough for building your first agent
- - No-code agent creation with `plot-agent.md`
+- **[Getting Started Guide](GETTING_STARTED.md)** - Complete walkthrough for building your first twist
+ - No-code twist creation with `plot-twist.md`
- Developer quick start with TypeScript
- Project structure and setup
@@ -17,12 +17,12 @@ Plot agents are intelligent assistants that automatically manage your activities
- **[Core Concepts](CORE_CONCEPTS.md)** - Understanding the Plot architecture
- - Agents and their lifecycle
- - Tools and dependencies
+ - Twists and their lifecycle
+ - Twist tools and dependencies
- Priorities and Activities
- Best practices and patterns
-- **[Built-in Tools Guide](TOOLS_GUIDE.md)** - Complete reference for all built-in tools
+- **[Built-in Tools Guide](TOOLS_GUIDE.md)** - Complete reference for all built-in twist tools
- Plot - Managing activities and priorities
- Store - Persistent key-value storage
@@ -32,7 +32,7 @@ Plot agents are intelligent assistants that automatically manage your activities
- Callbacks - Persistent function references
- AI - Language model integration
-- **[Building Custom Tools](BUILDING_TOOLS.md)** - Create your own tools
+- **[Building Custom Tools](BUILDING_TOOLS.md)** - Create your own twist tools
- Tool class structure
- Lifecycle methods
- Dependencies and configuration
@@ -43,7 +43,7 @@ Plot agents are intelligent assistants that automatically manage your activities
- **[CLI Reference](CLI_REFERENCE.md)** - Complete command-line interface documentation
- - Agent management commands
+ - Twist management commands
- Priority management
- Authentication
- Deployment
@@ -56,7 +56,7 @@ Plot agents are intelligent assistants that automatically manage your activities
- Performance optimization
- **[Advanced Topics](ADVANCED.md)** - Complex patterns and techniques
- - Multi-agent coordination
+ - Multi-twist coordination
- Error handling
- Debugging and logging
- Security best practices
@@ -65,7 +65,7 @@ Plot agents are intelligent assistants that automatically manage your activities
Explore the complete API documentation using the navigation on the left:
-- **Classes** - Agent, Tool, and all built-in tool classes
+- **Classes** - Twist, Tool, and all built-in tool classes
- **Interfaces** - Activity, Priority, Contact, and data structures
- **Enums** - ActivityType, ActorType, and other enumerations
- **Type Aliases** - Helper types and utilities
@@ -74,25 +74,25 @@ Explore the complete API documentation using the navigation on the left:
- [Plot Website](https://plot.day)
- [GitHub Repository](https://github.com/plotday/plot)
-- [NPM Package](https://www.npmjs.com/package/@plotday/agent)
+- [NPM Package](https://www.npmjs.com/package/@plotday/twister)
- [Report Issues](https://github.com/plotday/plot/issues)
## Examples
Check out these examples to get started:
-### Simple Note Agent
+### Simple Note Twist
```typescript
import {
ActivityType,
- Agent,
+ Twist,
type Priority,
type ToolBuilder,
-} from "@plotday/agent";
-import { Plot } from "@plotday/agent/tools/plot";
+} from "@plotday/twister";
+import { Plot } from "@plotday/twister/tools/plot";
-export default class WelcomeAgent extends Agent {
+export default class WelcomeTwist extends Twist {
build(build: ToolBuilder) {
return {
plot: build(Plot),
@@ -108,14 +108,14 @@ export default class WelcomeAgent extends Agent {
}
```
-### Calendar Sync Agent
+### Calendar Sync Twist
```typescript
-import { type Activity, Agent, type ToolBuilder } from "@plotday/agent";
-import { Network } from "@plotday/agent/tools/network";
-import { Plot } from "@plotday/agent/tools/plot";
+import { type Activity, Twist, type ToolBuilder } from "@plotday/twister";
+import { Network } from "@plotday/twister/tools/network";
+import { Plot } from "@plotday/twister/tools/plot";
-export default class CalendarAgent extends Agent {
+export default class CalendarTwist extends Twist {
build(build: ToolBuilder) {
return {
plot: build(Plot),
diff --git a/builder/package.json b/twister/package.json
similarity index 86%
rename from builder/package.json
rename to twister/package.json
index 45a7f6f..abcd8a3 100644
--- a/builder/package.json
+++ b/twister/package.json
@@ -1,7 +1,7 @@
{
- "name": "@plotday/agent",
+ "name": "@plotday/twister",
"version": "0.19.1",
- "description": "Plot Agent Builder - Build intelligent agents that organize and prioritize your activities",
+ "description": "Plot Twist Creator - Build intelligent Twists that organize and prioritize your activities",
"packageManager": "pnpm@10.18.3",
"type": "module",
"main": "./dist/index.js",
@@ -14,9 +14,9 @@
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
},
- "./agent": {
- "types": "./dist/agent.d.ts",
- "default": "./dist/agent.js"
+ "./twist": {
+ "types": "./dist/twist.d.ts",
+ "default": "./dist/twist.js"
},
"./tool": {
"types": "./dist/tool.d.ts",
@@ -30,9 +30,9 @@
"types": "./dist/tag.d.ts",
"default": "./dist/tag.js"
},
- "./tools/agents": {
- "types": "./dist/tools/agents.d.ts",
- "default": "./dist/tools/agents.js"
+ "./tools/twists": {
+ "types": "./dist/tools/twists.d.ts",
+ "default": "./dist/tools/twists.js"
},
"./tools/ai": {
"types": "./dist/tools/ai.d.ts",
@@ -74,13 +74,13 @@
"types": "./dist/common/messaging.d.ts",
"default": "./dist/common/messaging.js"
},
- "./agents-guide": {
- "types": "./dist/agents-guide.d.ts",
- "default": "./dist/agents-guide.js"
+ "./twist-guide": {
+ "types": "./dist/twist-guide.d.ts",
+ "default": "./dist/twist-guide.js"
},
- "./builder-docs": {
- "types": "./dist/builder-docs.d.ts",
- "default": "./dist/builder-docs.js"
+ "./creator-docs": {
+ "types": "./dist/creator-docs.d.ts",
+ "default": "./dist/creator-docs.js"
},
"./llm-docs": {
"types": "./dist/llm-docs/index.d.ts",
@@ -90,9 +90,9 @@
"types": "./dist/llm-docs/index.d.ts",
"default": "./dist/llm-docs/index.js"
},
- "./llm-docs/agent": {
- "types": "./dist/llm-docs/agent.d.ts",
- "default": "./dist/llm-docs/agent.js"
+ "./llm-docs/twist": {
+ "types": "./dist/llm-docs/twist.d.ts",
+ "default": "./dist/llm-docs/twist.js"
},
"./llm-docs/plot": {
"types": "./dist/llm-docs/plot.d.ts",
@@ -102,9 +102,9 @@
"types": "./dist/llm-docs/tag.d.ts",
"default": "./dist/llm-docs/tag.js"
},
- "./llm-docs/tools/agents": {
- "types": "./dist/llm-docs/tools/agents.d.ts",
- "default": "./dist/llm-docs/tools/agents.js"
+ "./llm-docs/tools/twists": {
+ "types": "./dist/llm-docs/tools/twists.d.ts",
+ "default": "./dist/llm-docs/tools/twists.js"
},
"./llm-docs/tools/ai": {
"types": "./dist/llm-docs/tools/ai.d.ts",
@@ -184,7 +184,7 @@
"repository": {
"type": "git",
"url": "https://github.com/plotday/plot.git",
- "directory": "builder"
+ "directory": "twist"
},
"homepage": "https://build.plot.day",
"bugs": {
@@ -192,8 +192,8 @@
},
"keywords": [
"plot",
- "agent",
- "builder",
+ "twist",
+ "creator",
"automation",
"productivity",
"calendar",
diff --git a/builder/postbuild.js b/twister/postbuild.js
similarity index 100%
rename from builder/postbuild.js
rename to twister/postbuild.js
diff --git a/builder/prebuild.ts b/twister/prebuild.ts
similarity index 87%
rename from builder/prebuild.ts
rename to twister/prebuild.ts
index a5c08ff..0ca9e20 100644
--- a/builder/prebuild.ts
+++ b/twister/prebuild.ts
@@ -9,8 +9,8 @@ const __dirname = dirname(__filename);
interface TypeFile {
file: string;
importPath: string;
- docFilePath: string; // Path where doc file will be written (e.g., "tools/agents.ts")
- varName: string; // Valid JS identifier for imports (e.g., "toolsAgents")
+ docFilePath: string; // Path where doc file will be written (e.g., "tools/twists.ts")
+ varName: string; // Valid JS identifier for imports (e.g., "toolsTwists")
}
// Generate SDK documentation files for LLM consumption
@@ -34,7 +34,7 @@ for (const [exportPath, exportValue] of Object.entries(exports)) {
if (
exportPath === "." ||
exportPath === "./tsconfig.base.json" ||
- exportPath === "./agents-guide" ||
+ exportPath === "./twist-guide" ||
exportPath === "./sdk-docs" ||
exportPath.startsWith("./llm-docs") ||
exportPath.startsWith("./utils/")
@@ -61,13 +61,13 @@ for (const [exportPath, exportValue] of Object.entries(exports)) {
const importPath =
exportPath === "." ? "@plotday/sdk" : `@plotday/sdk${exportPath.slice(1)}`;
- // docFilePath mirrors the source file structure (e.g., "tools/agents.ts")
+ // docFilePath mirrors the source file structure (e.g., "tools/twists.ts")
// This is the path where the doc file will be written
const docFilePath = sourceFile;
// varName is a valid JavaScript identifier for use in index.ts imports
// Convert path separators and hyphens to create valid identifiers
- // e.g., "tools/agents.ts" -> "toolsAgents", "common/calendar.ts" -> "commonCalendar"
+ // e.g., "tools/twists.ts" -> "toolsTwists", "common/calendar.ts" -> "commonCalendar"
const varName = sourceFile
.replace(/\.ts$/, "") // Remove .ts extension
.replace(/\//g, "_") // Replace / with _
@@ -154,30 +154,30 @@ export default llmDocs;
const indexPath = join(llmDocsDir, "index.ts");
writeFileSync(indexPath, indexContent, "utf-8");
-// Generate agents-guide-template.ts from AGENTS.template.md
-const agentsTemplatePath = join(
+// Generate twist-guide-template.ts from AGENTS.template.md
+const twistsTemplatePath = join(
__dirname,
"cli",
"templates",
"AGENTS.template.md"
);
-if (existsSync(agentsTemplatePath)) {
- const agentsTemplateContent = readFileSync(agentsTemplatePath, "utf-8");
- const agentsGuideContent = `/**
- * Generated agents guide template
+if (existsSync(twistsTemplatePath)) {
+ const twistsTemplateContent = readFileSync(twistsTemplatePath, "utf-8");
+ const twistsGuideContent = `/**
+ * Generated twists guide template
*
* This file is auto-generated during build. Do not edit manually.
* Generated from: cli/templates/AGENTS.template.md
*/
-export default ${JSON.stringify(agentsTemplateContent)};
+export default ${JSON.stringify(twistsTemplateContent)};
`;
- const agentsGuideOutputPath = join(llmDocsDir, "agents-guide-template.ts");
- writeFileSync(agentsGuideOutputPath, agentsGuideContent, "utf-8");
- console.log(`✓ Generated agents-guide-template.ts from AGENTS.template.md`);
+ const twistsGuideOutputPath = join(llmDocsDir, "twist-guide-template.ts");
+ writeFileSync(twistsGuideOutputPath, twistsGuideContent, "utf-8");
+ console.log(`✓ Generated twist-guide-template.ts from AGENTS.template.md`);
} else {
console.warn(
- `Warning: AGENTS.template.md not found at ${agentsTemplatePath}`
+ `Warning: AGENTS.template.md not found at ${twistsTemplatePath}`
);
}
diff --git a/builder/src/common/calendar.ts b/twister/src/common/calendar.ts
similarity index 99%
rename from builder/src/common/calendar.ts
rename to twister/src/common/calendar.ts
index 62c98e6..21bfefc 100644
--- a/builder/src/common/calendar.ts
+++ b/twister/src/common/calendar.ts
@@ -61,7 +61,7 @@ export interface SyncOptions {
* @example
* ```typescript
* // Typical calendar integration flow
- * class MyCalendarAgent extends Agent {
+ * class MyCalendarTwist extends Twist {
* private googleCalendar: GoogleCalendar;
*
* async activate() {
diff --git a/builder/src/common/messaging.ts b/twister/src/common/messaging.ts
similarity index 100%
rename from builder/src/common/messaging.ts
rename to twister/src/common/messaging.ts
diff --git a/builder/src/builder-docs.ts b/twister/src/creator-docs.ts
similarity index 71%
rename from builder/src/builder-docs.ts
rename to twister/src/creator-docs.ts
index e7c62c7..679a721 100644
--- a/builder/src/builder-docs.ts
+++ b/twister/src/creator-docs.ts
@@ -1,20 +1,20 @@
import llmDocs from "./llm-docs/index.js";
/**
- * Gets complete Agent Builder type definitions with import paths for LLM context.
+ * Gets complete Twist Creator type definitions with import paths for LLM context.
*
* This function returns pre-generated Builder documentation that was bundled
- * at build time. Used by agent generators to provide complete type
+ * at build time. Used by twist generators to provide complete type
* information to LLMs.
*
- * @returns Formatted string containing all Agent Builder type definitions with import paths
+ * @returns Formatted string containing all Twist Creator type definitions with import paths
*/
export function getBuilderDocumentation(): string {
- let documentation = "# Plot Agent Builder Type Definitions\n\n";
+ let documentation = "# Plot Twist Creator Type Definitions\n\n";
documentation +=
- "Complete type definitions with JSDoc documentation for all Plot Agent Builder types.\n";
+ "Complete type definitions with JSDoc documentation for all Plot Twist Creator types.\n";
documentation +=
- "These are the source files - use the import paths shown to import types in your agent code.\n\n";
+ "These are the source files - use the import paths shown to import types in your twist code.\n\n";
// Format each Builder file with headers and code fences
for (const [importPath, content] of Object.entries(llmDocs)) {
diff --git a/builder/src/index.ts b/twister/src/index.ts
similarity index 53%
rename from builder/src/index.ts
rename to twister/src/index.ts
index abc78c3..6479911 100644
--- a/builder/src/index.ts
+++ b/twister/src/index.ts
@@ -1,6 +1,6 @@
-export * from "./agent";
+export * from "./twist";
export * from "./plot";
export * from "./tag";
export * from "./tool";
export * from "./tools";
-export { getBuilderDocumentation } from "./builder-docs";
+export { getBuilderDocumentation } from "./creator-docs";
diff --git a/builder/src/plot.ts b/twister/src/plot.ts
similarity index 94%
rename from builder/src/plot.ts
rename to twister/src/plot.ts
index 4ac8c20..3167092 100644
--- a/builder/src/plot.ts
+++ b/twister/src/plot.ts
@@ -1,12 +1,13 @@
import { type Tag } from "./tag";
+import { type Callback } from "./tools/callbacks";
export { Tag } from "./tag";
/**
- * Represents a unique user, contact, or agent in Plot.
+ * Represents a unique user, contact, or twist in Plot.
*
* Note contacts (i.e. people not using Plot) are also represented by ActorIds. They may be
- * people interacting with other services that are connected.
+ * people interacting with other connected services (e.g. an email sender or event attendee).
*/
export type ActorId = string & { readonly __brand: "ActorId" };
@@ -60,7 +61,7 @@ export enum ActivityLinkType {
external = "external",
/** Authentication flows for connecting services */
auth = "auth",
- /** Callback links that trigger agent methods when clicked */
+ /** Callback links that trigger twist methods when clicked */
callback = "callback",
/** Video conferencing links with provider-specific handling */
conferencing = "conferencing",
@@ -117,7 +118,7 @@ export enum ConferencingProvider {
* callback: "callback-token-for-auth-completion"
* };
*
- * // Callback link - triggers agent method
+ * // Callback link - triggers a twist method
* const callbackLink: ActivityLink = {
* type: ActivityLinkType.callback,
* title: "📅 Primary Calendar",
@@ -154,15 +155,15 @@ export type ActivityLink =
/** Array of OAuth scopes to request */
scopes: string[];
/** Callback token for auth completion notification */
- callback: string;
+ callback: Callback;
}
| {
- /** Callback link that triggers agent method when clicked */
+ /** Callback link that triggers a twist method when clicked */
type: ActivityLinkType.callback;
/** Display text for the callback button */
title: string;
/** Token identifying the callback to execute */
- token: string;
+ callback: Callback;
};
/**
@@ -295,7 +296,7 @@ export type Activity = {
meta: ActivityMeta | null;
/** Tags attached to this activity. Maps tag ID to array of actor IDs who added that tag. */
tags: Partial> | null;
- /** Array of actor IDs (users, contacts, or agents) mentioned in this activity via @-mentions */
+ /** Array of actor IDs (users, contacts, or twists) mentioned in this activity via @-mentions */
mentions: ActorId[] | null;
};
@@ -433,21 +434,21 @@ export type ActivityUpdate = Pick &
/**
* Full tags object from Activity. Maps tag ID to array of actor IDs who added that tag.
- * Only allowed for activities created by the agent.
- * Use agentTags instead for adding/removing the agent's tags on other activities.
+ * Only allowed for activities created by the twist.
+ * Use twistTags instead for adding/removing the twist's tags on other activities.
*/
tags?: Partial>;
/**
- * Add or remove the agent's tags.
+ * Add or remove the twist's tags.
* Maps tag ID to boolean: true = add tag, false = remove tag.
- * This is allowed on all activities the agent has access to.
+ * This is allowed on all activities the twist has access to.
*/
- agentTags?: Partial>;
+ twistTags?: Partial>;
};
/**
- * Represents an actor in Plot - a user, contact, or agent.
+ * Represents an actor in Plot - a user, contact, or twist.
*
* Actors can be associated with activities as authors, assignees, or mentions.
* The email field is only included when ContactAccess.Read permission is granted.
@@ -465,7 +466,7 @@ export type ActivityUpdate = Pick &
export type Actor = {
/** Unique identifier for the actor */
id: ActorId;
- /** Type of actor (User, Contact, or Agent) */
+ /** Type of actor (User, Contact, or Twist) */
type: ActorType;
/** Email address (only included with ContactAccess.Read permission) */
email?: string;
@@ -484,8 +485,8 @@ export enum ActorType {
User,
/** Activities created by external contacts */
Contact,
- /** Activities created by automated agents */
- Agent,
+ /** Activities created by automated twists */
+ Twist,
}
/**
diff --git a/builder/src/tag.ts b/twister/src/tag.ts
similarity index 92%
rename from builder/src/tag.ts
rename to twister/src/tag.ts
index c80dc8c..c429105 100644
--- a/builder/src/tag.ts
+++ b/twister/src/tag.ts
@@ -21,7 +21,7 @@ export enum Tag {
Blocked = 106,
Warning = 107,
Question = 108,
- Agent = 109,
+ Twist = 109,
Star = 110,
Idea = 111,
Attachment = 112,
@@ -41,9 +41,7 @@ export enum Tag {
Thanks = 1010,
Smile = 1011,
Wave = 1012,
- Praise = 1013,
- Joy = 1014,
- Admiration = 1015,
+ Praise = 1015,
Applause = 1016,
Cool = 1017,
Sad = 1018,
diff --git a/builder/src/tool.ts b/twister/src/tool.ts
similarity index 95%
rename from builder/src/tool.ts
rename to twister/src/tool.ts
index 660de18..ef968e9 100644
--- a/builder/src/tool.ts
+++ b/twister/src/tool.ts
@@ -227,10 +227,10 @@ export abstract class Tool implements ITool {
}
/**
- * Called before the agent's activate method, starting from the deepest tool dependencies.
+ * Called before the twist's activate method, starting from the deepest tool dependencies.
*
* This method is called in a depth-first manner, with the deepest dependencies
- * being called first, bubbling up to the top-level tools before the agent's
+ * being called first, bubbling up to the top-level tools before the twist's
* activate method is called.
*
* @param priority - The priority context containing the priority ID
@@ -242,7 +242,7 @@ export abstract class Tool implements ITool {
}
/**
- * Called after the agent's activate method, starting from the top-level tools.
+ * Called after the twist's activate method, starting from the top-level tools.
*
* This method is called in reverse order, with top-level tools being called
* first, then cascading down to the deepest dependencies.
@@ -256,10 +256,10 @@ export abstract class Tool implements ITool {
}
/**
- * Called before the agent's upgrade method, starting from the deepest tool dependencies.
+ * Called before the twist's upgrade method, starting from the deepest tool dependencies.
*
* This method is called in a depth-first manner, with the deepest dependencies
- * being called first, bubbling up to the top-level tools before the agent's
+ * being called first, bubbling up to the top-level tools before the twist's
* upgrade method is called.
*
* @returns Promise that resolves when pre-upgrade is complete
@@ -269,7 +269,7 @@ export abstract class Tool implements ITool {
}
/**
- * Called after the agent's upgrade method, starting from the top-level tools.
+ * Called after the twist's upgrade method, starting from the top-level tools.
*
* This method is called in reverse order, with top-level tools being called
* first, then cascading down to the deepest dependencies.
@@ -281,10 +281,10 @@ export abstract class Tool implements ITool {
}
/**
- * Called before the agent's deactivate method, starting from the deepest tool dependencies.
+ * Called before the twist's deactivate method, starting from the deepest tool dependencies.
*
* This method is called in a depth-first manner, with the deepest dependencies
- * being called first, bubbling up to the top-level tools before the agent's
+ * being called first, bubbling up to the top-level tools before the twist's
* deactivate method is called.
*
* @returns Promise that resolves when pre-deactivation is complete
@@ -294,7 +294,7 @@ export abstract class Tool implements ITool {
}
/**
- * Called after the agent's deactivate method, starting from the top-level tools.
+ * Called after the twist's deactivate method, starting from the top-level tools.
*
* This method is called in reverse order, with top-level tools being called
* first, then cascading down to the deepest dependencies.
diff --git a/builder/src/tools/ai.ts b/twister/src/tools/ai.ts
similarity index 99%
rename from builder/src/tools/ai.ts
rename to twister/src/tools/ai.ts
index 34a24a3..0fd142c 100644
--- a/builder/src/tools/ai.ts
+++ b/twister/src/tools/ai.ts
@@ -5,7 +5,7 @@ import { ITool } from "..";
/**
* Built-in tool for prompting Large Language Models (LLMs).
*
- * The AI tool provides agents and tools with access to LLM capabilities
+ * The AI tool provides twists and tools with access to LLM capabilities
* for natural language processing, text generation, data extraction,
* and intelligent decision making within their workflows.
*
diff --git a/builder/src/tools/callbacks.ts b/twister/src/tools/callbacks.ts
similarity index 94%
rename from builder/src/tools/callbacks.ts
rename to twister/src/tools/callbacks.ts
index ee6110f..71e6907 100644
--- a/builder/src/tools/callbacks.ts
+++ b/twister/src/tools/callbacks.ts
@@ -7,7 +7,7 @@ export type { CallbackMethods, NoFunctions, NonFunction };
/**
* Represents a callback token for persistent function references.
*
- * Callbacks enable tools and agents to create persistent references to functions
+ * Callbacks enable tools and twists to create persistent references to functions
* that can survive worker restarts and be invoked across different execution contexts.
*
* This is a branded string type to prevent mixing callback tokens with regular strings.
@@ -22,12 +22,12 @@ export type Callback = string & { readonly __brand: "Callback" };
/**
* Built-in tool for creating and managing persistent callback references.
*
- * The Callbacks tool enables agents and tools to create callback links that persist
+ * The Callbacks tool enables twists and tools to create callback links that persist
* across worker invocations and restarts. This is essential for webhook handlers,
* scheduled operations, and user interaction flows that need to survive runtime
* boundaries.
*
- * **Note:** Callback methods are also available directly on Agent and Tool classes
+ * **Note:** Callback methods are also available directly on Twist and Tool classes
* via `this.callback()`, `this.deleteCallback()`, `this.deleteAllCallbacks()`, and
* `this.run()`. This is the recommended approach for most use cases.
*
@@ -70,7 +70,7 @@ export abstract class Callbacks extends ITool {
): Promise;
/**
- * Creates a persistent callback to a function from the parent agent/tool.
+ * Creates a persistent callback to a function from the parent twist/tool.
* Use this when the callback function is passed in from outside this class.
*
* @param fn - The function to callback
diff --git a/builder/src/tools/index.ts b/twister/src/tools/index.ts
similarity index 87%
rename from builder/src/tools/index.ts
rename to twister/src/tools/index.ts
index 0baf6b4..76d26eb 100644
--- a/builder/src/tools/index.ts
+++ b/twister/src/tools/index.ts
@@ -1,4 +1,4 @@
-export * from "./agents";
+export * from "./twists";
export * from "./ai";
export * from "./callbacks";
export * from "./integrations";
diff --git a/builder/src/tools/integrations.ts b/twister/src/tools/integrations.ts
similarity index 98%
rename from builder/src/tools/integrations.ts
rename to twister/src/tools/integrations.ts
index d47e6cb..004d5ca 100644
--- a/builder/src/tools/integrations.ts
+++ b/twister/src/tools/integrations.ts
@@ -113,7 +113,7 @@ export enum AuthProvider {
* Different levels determine the scope and storage of authentication tokens.
*/
export enum AuthLevel {
- /** Priority-scoped authorization shared across agents in a priority */
+ /** Priority-scoped authorization shared across twists in a priority */
Priority = "priority",
/** User-scoped authorization specific to individual users */
User = "user",
diff --git a/builder/src/tools/network.ts b/twister/src/tools/network.ts
similarity index 96%
rename from builder/src/tools/network.ts
rename to twister/src/tools/network.ts
index 3977403..0c8932c 100644
--- a/builder/src/tools/network.ts
+++ b/twister/src/tools/network.ts
@@ -33,10 +33,10 @@ export type WebhookRequest = {
* Built-in tool for requesting HTTP access permissions and managing webhooks.
*
* The Network tool serves two purposes:
- * 1. Declares which URLs an agent or tool is allowed to access via HTTP/HTTPS
+ * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS
* 2. Provides webhook creation and management for receiving HTTP callbacks
*
- * **IMPORTANT**: Must be requested in the Agent or Tool Init method to declare
+ * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare
* HTTP access permissions. Without requesting this tool with the appropriate URLs,
* all outbound HTTP requests (fetch, etc.) will be blocked.
*
@@ -48,13 +48,13 @@ export type WebhookRequest = {
*
* **Webhook Characteristics:**
* - Persistent across worker restarts
- * - Automatic callback routing to parent tool/agent
+ * - Automatic callback routing to parent tool/twist
* - Support for all HTTP methods
* - Context preservation for callback execution
*
* @example
* ```typescript
- * class MyAgent extends Agent {
+ * class MyTwist extends Twist {
* build(build: ToolBuilder) {
* return {
* // Request HTTP access to specific APIs
diff --git a/builder/src/tools/plot.ts b/twister/src/tools/plot.ts
similarity index 91%
rename from builder/src/tools/plot.ts
rename to twister/src/tools/plot.ts
index 1a536b4..e211b67 100644
--- a/builder/src/tools/plot.ts
+++ b/twister/src/tools/plot.ts
@@ -14,13 +14,13 @@ import {
export enum ActivityAccess {
/**
- * Create new Activity on a thread where the agent was mentioned.
- * Add/remove tags on Activity where the agent was mentioned.
+ * Create new Activity on a thread where the twist was mentioned.
+ * Add/remove tags on Activity where the twist was mentioned.
*/
Respond,
/**
* Create new, top-level Activity.
- * Create new Activity in a thread the agent created.
+ * Create new Activity in a thread the twist created.
* All Respond permissions.
*/
Create,
@@ -28,14 +28,14 @@ export enum ActivityAccess {
export enum PriorityAccess {
/**
- * Create a new Priority within the agent's Priority.
- * Update Priority created by the agent.
+ * Create a new Priority within the twist's Priority.
+ * Update Priority created by the twist.
*/
Create,
/**
- * Read all Priority within the agent's Priority.
- * Create a new Priority within the agent's Priority.
- * Update and archive any Priority within the agent's Priority.
+ * Read all Priority within the twist's Priority.
+ * Create a new Priority within the twist's Priority.
+ * Update and archive any Priority within the twist's Priority.
*/
Full,
}
@@ -49,7 +49,7 @@ export enum ContactAccess {
/**
* Intent handler for activity mentions.
- * Defines how the agent should respond when mentioned in an activity.
+ * Defines how the twist should respond when mentioned in an activity.
*/
export type ActivityIntentHandler = {
/** Human-readable description of what this intent handles */
@@ -63,13 +63,13 @@ export type ActivityIntentHandler = {
/**
* Built-in tool for interacting with the core Plot data layer.
*
- * The Plot tool provides agents with the ability to create and manage activities,
+ * The Plot tool provides twists with the ability to create and manage activities,
* priorities, and contacts within the Plot system. This is the primary interface
- * for agents to persist data and interact with the Plot database.
+ * for twists to persist data and interact with the Plot database.
*
* @example
* ```typescript
- * class MyAgent extends Agent {
+ * class MyTwist extends Twist {
* private plot: Plot;
*
* constructor(id: string, tools: ToolBuilder) {
@@ -117,7 +117,7 @@ export abstract class Plot extends ITool {
/**
* Intent handlers for activity mentions.
- * When an activity mentions this agent, the system will match the activity
+ * When an activity mentions this twist, the system will match the activity
* content against these intent descriptions and call the matching handler.
*
* @example
@@ -252,7 +252,7 @@ export abstract class Plot extends ITool {
/**
* Creates a new priority in the Plot system.
*
- * Priorities serve as organizational containers for activities and agents.
+ * Priorities serve as organizational containers for activities and twists.
* The created priority will be automatically assigned a unique ID.
*
* @param priority - The priority data to create
@@ -278,7 +278,7 @@ export abstract class Plot extends ITool {
/**
* Retrieves actors by their IDs.
*
- * Actors represent users, contacts, or agents in the Plot system.
+ * Actors represent users, contacts, or twists in the Plot system.
* This method requires ContactAccess.Read permission.
*
* @param ids - Array of actor IDs to retrieve
diff --git a/builder/src/tools/store.ts b/twister/src/tools/store.ts
similarity index 90%
rename from builder/src/tools/store.ts
rename to twister/src/tools/store.ts
index b38c7d3..5e2b0d2 100644
--- a/builder/src/tools/store.ts
+++ b/twister/src/tools/store.ts
@@ -3,17 +3,17 @@ import { ITool } from "..";
/**
* Built-in tool for persistent key-value storage.
*
- * The Store tool provides agents and tools with a simple, persistent storage
- * mechanism that survives worker restarts and invocations. Each agent/tool
+ * The Store tool provides twists and tools with a simple, persistent storage
+ * mechanism that survives worker restarts and invocations. Each twist/tool
* instance gets its own isolated storage namespace.
*
- * **Note:** Store methods are also available directly on Agent and Tool classes
+ * **Note:** Store methods are also available directly on Twist and Tool classes
* via `this.get()`, `this.set()`, `this.clear()`, and `this.clearAll()`.
* This is the recommended approach for most use cases.
*
* **Storage Characteristics:**
* - Persistent across worker restarts
- * - Isolated per agent/tool instance
+ * - Isolated per twist/tool instance
* - Supports any JSON-serializable data
* - Async operations for scalability
*
@@ -87,8 +87,8 @@ export abstract class Store extends ITool {
/**
* Removes all keys from this storage instance.
*
- * This operation clears all data stored by this agent/tool instance
- * but does not affect storage for other agents or tools.
+ * This operation clears all data stored by this twist/tool instance
+ * but does not affect storage for other twists or tools.
*
* @returns Promise that resolves when all keys are removed
*/
diff --git a/builder/src/tools/tasks.ts b/twister/src/tools/tasks.ts
similarity index 94%
rename from builder/src/tools/tasks.ts
rename to twister/src/tools/tasks.ts
index a697c80..1c3e837 100644
--- a/builder/src/tools/tasks.ts
+++ b/twister/src/tools/tasks.ts
@@ -4,12 +4,12 @@ import type { Callback } from "./callbacks";
/**
* Run background tasks and scheduled jobs.
*
- * The Run tool enables agents and tools to queue callbacks. This is especially
- * iportant for long-running operations and batch processing, since agents
+ * The Run tool enables twists and tools to queue callbacks. This is especially
+ * iportant for long-running operations and batch processing, since twists
* operate within runtime limits. Run callbacks also benefit from automatic
* retries on failure.
*
- * **Note:** Run methods are also available directly on Agent and Tool classes
+ * **Note:** Run methods are also available directly on Twist and Tool classes
* via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.
* This is the recommended approach for most use cases.
*
@@ -87,9 +87,9 @@ export abstract class Tasks extends ITool {
abstract cancelTask(token: string): Promise;
/**
- * Cancels all scheduled executions for this tool/agent.
+ * Cancels all scheduled executions for this tool/twist.
*
- * Cancels all pending scheduled executions created by this tool or agent
+ * Cancels all pending scheduled executions created by this tool or twist
* instance. Immediate executions cannot be cancelled.
*
* @returns Promise that resolves when all cancellations are processed
diff --git a/builder/src/tools/agents.ts b/twister/src/tools/twists.ts
similarity index 63%
rename from builder/src/tools/agents.ts
rename to twister/src/tools/twists.ts
index 59d315d..e325f77 100644
--- a/builder/src/tools/agents.ts
+++ b/twister/src/tools/twists.ts
@@ -1,9 +1,9 @@
import { type Callback, ITool } from "..";
/**
- * Agent source code structure containing dependencies and source files.
+ * Twist source code structure containing dependencies and source files.
*/
-export interface AgentSource {
+export interface TwistSource {
/**
* Package dependencies with version specifiers
* @example { "@plotday/sdk": "workspace:^", "@plotday/tool-google-calendar": "^1.0.0" }
@@ -13,13 +13,13 @@ export interface AgentSource {
/**
* Source files with their content
* Must include "index.ts" as the entry point
- * @example { "index.ts": "export default class MyAgent extends Agent {...}" }
+ * @example { "index.ts": "export default class MyTwist extends Twist {...}" }
*/
files: Record;
}
/**
- * Represents a log entry from an agent execution.
+ * Represents a log entry from a twist execution.
*/
export type Log = {
timestamp: Date;
@@ -29,7 +29,7 @@ export type Log = {
};
/**
- * Agent permissions returned after deployment.
+ * Twist permissions returned after deployment.
* Nested structure mapping domains to entities to permission flags.
*
* Format: { domain: { entity: flags[] } }
@@ -51,62 +51,62 @@ export type Log = {
* }
* ```
*/
-export type AgentPermissions = Record>;
+export type TwistPermissions = Record>;
/**
- * Built-in tool for managing agents and deployments.
+ * Built-in tool for managing twists and deployments.
*
- * The Agent tool provides agents with the ability to create agent IDs
- * and programmatically deploy agents.
+ * The Twists tool provides twists with the ability to create twist IDs
+ * and programmatically deploy twists.
*
* @example
* ```typescript
- * class AgentBuilderAgent extends Agent {
+ * class TwistBuilderTwist extends Twist {
* build(build: ToolBuilder) {
* return {
- * agents: build.get(Agents)
+ * twists: build.get(Twists)
* }
* }
*
* async activate() {
- * const agentId = await this.tools.agents.create();
- * // Display agent ID to user
+ * const twistId = await this.tools.twists.create();
+ * // Display twist ID to user
* }
* }
* ```
*/
-export abstract class Agents extends ITool {
+export abstract class Twists extends ITool {
/**
- * Creates a new agent ID and grants access to people in the current priority.
+ * Creates a new twist ID and grants access to people in the current priority.
*
- * @returns Promise resolving to the generated agent ID
- * @throws When agent creation fails
+ * @returns Promise resolving to the generated twist ID
+ * @throws When twist creation fails
*
* @example
* ```typescript
- * const agentId = await agent.create();
- * console.log(`Your agent ID: ${agentId}`);
+ * const twistId = await twist.create();
+ * console.log(`Your twist ID: ${twistId}`);
* ```
*/
abstract create(): Promise;
/**
- * Generates agent source code from a specification using AI.
+ * Generates twist source code from a specification using AI.
*
* This method uses Claude AI to generate TypeScript source code and dependencies
* from a markdown specification. The generated source is validated by attempting
* to build it, with iterative error correction (up to 3 attempts).
*
- * @param spec - Markdown specification describing the agent functionality
- * @returns Promise resolving to agent source (dependencies and files)
+ * @param spec - Markdown specification describing the twist functionality
+ * @returns Promise resolving to twist source (dependencies and files)
* @throws When generation fails after maximum attempts
*
* @example
* ```typescript
- * const source = await agent.generate(`
- * # Calendar Sync Agent
+ * const source = await twist.generate(`
+ * # Calendar Sync Twist
*
- * This agent syncs Google Calendar events to Plot activities.
+ * This twist syncs Google Calendar events to Plot activities.
*
* ## Features
* - Authenticate with Google
@@ -119,23 +119,23 @@ export abstract class Agents extends ITool {
* ```
*/
// eslint-disable-next-line @typescript-eslint/no-unused-vars
- abstract generate(spec: string): Promise;
+ abstract generate(spec: string): Promise;
/**
- * Deploys an agent programmatically.
+ * Deploys a twist programmatically.
*
* This method provides the same functionality as the plot deploy CLI
- * command, but can be called from within an agent. Accepts either:
+ * command, but can be called from within a twist. Accepts either:
* - A pre-bundled module (JavaScript code)
* - A source object (dependencies + files) which is built in a sandbox
*
* @param options - Deployment configuration
- * @param options.agentId - Agent ID for deployment
- * @param options.module - Pre-bundled agent module code (mutually exclusive with source)
- * @param options.source - Agent source code with dependencies (mutually exclusive with module)
+ * @param options.twistId - Twist ID for deployment
+ * @param options.module - Pre-bundled twist module code (mutually exclusive with source)
+ * @param options.source - Twist source code with dependencies (mutually exclusive with module)
* @param options.environment - Target environment (defaults to "personal")
- * @param options.name - Optional agent name (required for first deploy)
- * @param options.description - Optional agent description (required for first deploy)
+ * @param options.name - Optional twist name (required for first deploy)
+ * @param options.description - Optional twist description (required for first deploy)
* @param options.dryRun - If true, validates without deploying (returns errors if any)
* @returns Promise resolving to deployment result with version and optional errors
* @throws When deployment fails or user lacks access
@@ -143,27 +143,27 @@ export abstract class Agents extends ITool {
* @example
* ```typescript
* // Deploy with a module
- * const result = await agent.deploy({
- * agentId: 'abc-123-...',
- * module: 'export default class MyAgent extends Agent {...}',
+ * const result = await twist.deploy({
+ * twistId: 'abc-123-...',
+ * module: 'export default class MyTwist extends Twist {...}',
* environment: 'personal',
- * name: 'My Agent',
+ * name: 'My Twist',
* description: 'Does something cool'
* });
* console.log(`Deployed version ${result.version}`);
*
* // Deploy with source
- * const source = await agent.generate(spec);
- * const result = await agent.deploy({
- * agentId: 'abc-123-...',
+ * const source = await twist.generate(spec);
+ * const result = await twist.deploy({
+ * twistId: 'abc-123-...',
* source,
* environment: 'personal',
- * name: 'My Agent',
+ * name: 'My Twist',
* });
*
* // Validate with dryRun
- * const result = await agent.deploy({
- * agentId: 'abc-123-...',
+ * const result = await twist.deploy({
+ * twistId: 'abc-123-...',
* source,
* dryRun: true,
* });
@@ -175,7 +175,7 @@ export abstract class Agents extends ITool {
// eslint-disable-next-line @typescript-eslint/no-unused-vars
abstract deploy(
options: {
- agentId: string;
+ twistId: string;
environment?: "personal" | "private" | "review";
name?: string;
description?: string;
@@ -185,35 +185,35 @@ export abstract class Agents extends ITool {
module: string;
}
| {
- source: AgentSource;
+ source: TwistSource;
}
)
): Promise<{
version: string;
- permissions: AgentPermissions;
+ permissions: TwistPermissions;
errors?: string[];
}>;
/**
- * Subscribes to logs from an agent.
+ * Subscribes to logs from a twist.
*
- * This method registers a callback to receive batches of logs from agent executions.
+ * This method registers a callback to receive batches of logs from twist executions.
* The callback will be invoked with an array of logs whenever new logs are captured
- * from the agent's console output.
+ * from the twist's console output.
*
- * @param agentId - Agent ID (root ID) to watch logs for
+ * @param twistId - Twist ID (root ID) to watch logs for
* @param callback - Callback token created via CallbackTool that will receive log batches
* @returns Promise that resolves when the subscription is created
* @throws When subscription fails
*
* @example
* ```typescript
- * // Create agent and callback
- * const agentId = await this.agent.create();
+ * // Create twist and callback
+ * const twistId = await this.twist.create();
* const callback = await this.callback.create("onLogs");
*
* // Subscribe to logs
- * await this.agent.watchLogs(agentId, callback);
+ * await this.twist.watchLogs(twistId, callback);
*
* // Implement handler
* async onLogs(logs: Log[]) {
@@ -224,5 +224,5 @@ export abstract class Agents extends ITool {
* ```
*/
// eslint-disable-next-line @typescript-eslint/no-unused-vars
- abstract watchLogs(agentId: string, callback: Callback): Promise;
+ abstract watchLogs(twistId: string, callback: Callback): Promise;
}
diff --git a/twister/src/twist-guide.ts b/twister/src/twist-guide.ts
new file mode 100644
index 0000000..ce6a5ae
--- /dev/null
+++ b/twister/src/twist-guide.ts
@@ -0,0 +1,9 @@
+/**
+ * Twist Implementation Guide
+ *
+ * This guide is used by AI systems to generate Plot twists.
+ * Auto-generated from cli/templates/AGENTS.template.md during build.
+ */
+import twistsGuideTemplate from "./llm-docs/twist-guide-template.js";
+
+export const TWIST_GUIDE = twistsGuideTemplate;
diff --git a/builder/src/agent.ts b/twister/src/twist.ts
similarity index 89%
rename from builder/src/agent.ts
rename to twister/src/twist.ts
index f4ebae9..bcb3089 100644
--- a/builder/src/agent.ts
+++ b/twister/src/twist.ts
@@ -4,16 +4,16 @@ import type { Callback } from "./tools/callbacks";
import type { InferTools, ToolBuilder, ToolShed } from "./utils/types";
/**
- * Base class for all agents.
+ * Base class for all twists.
*
- * Agents are activated in a Plot priority and have access to that priority and all
+ * Twists are activated in a Plot priority and have access to that priority and all
* its descendants.
*
* Override build() to declare tool dependencies and lifecycle methods to handle events.
*
* @example
* ```typescript
- * class FlatteringAgent extends Agent {
+ * class FlatteringTwist extends Twist {
* build(build: ToolBuilder) {
* return {
* plot: build(Plot),
@@ -21,7 +21,7 @@ import type { InferTools, ToolBuilder, ToolShed } from "./utils/types";
* }
*
* async activate(priority: Pick) {
- * // Initialize agent for the given priority
+ * // Initialize twist for the given priority
* await this.tools.plot.createActivity({
* type: ActivityType.Note,
* note: "Hello, good looking!",
@@ -30,11 +30,11 @@ import type { InferTools, ToolBuilder, ToolShed } from "./utils/types";
* }
* ```
*/
-export abstract class Agent {
+export abstract class Twist {
constructor(protected id: string, private toolShed: ToolShed) {}
/**
- * Gets the initialized tools for this agent.
+ * Gets the initialized tools for this twist.
* @throws Error if called before initialization is complete
*/
protected get tools(): InferTools {
@@ -42,7 +42,7 @@ export abstract class Agent {
}
/**
- * Declares tool dependencies for this agent.
+ * Declares tool dependencies for this twist.
* Return an object mapping tool names to build() promises.
*
* @param build - The build function to use for declaring dependencies
@@ -61,7 +61,7 @@ export abstract class Agent {
abstract build(build: ToolBuilder): Record>;
/**
- * Creates a persistent callback to a method on this agent.
+ * Creates a persistent callback to a method on this twist.
*
* ExtraArgs are strongly typed to match the method's signature after the first argument.
*
@@ -92,7 +92,7 @@ export abstract class Agent {
}
/**
- * Deletes all callbacks for this agent.
+ * Deletes all callbacks for this twist.
*
* @returns Promise that resolves when all callbacks are deleted
*/
@@ -164,7 +164,7 @@ export abstract class Agent {
}
/**
- * Removes all keys from this agent's storage.
+ * Removes all keys from this twist's storage.
*
* @returns Promise that resolves when all keys are removed
*/
@@ -198,7 +198,7 @@ export abstract class Agent {
}
/**
- * Cancels all scheduled executions for this agent.
+ * Cancels all scheduled executions for this twist.
*
* @returns Promise that resolves when all cancellations are processed
*/
@@ -207,7 +207,7 @@ export abstract class Agent {
}
/**
- * Called when the agent is activated for a specific priority.
+ * Called when the twist is activated for a specific priority.
*
* This method should contain initialization logic such as setting up
* initial activities, configuring webhooks, or establishing external connections.
@@ -221,11 +221,11 @@ export abstract class Agent {
}
/**
- * Called when a new version of the agent is deployed to an existing priority.
+ * Called when a new version of the twist is deployed to an existing priority.
*
* This method should contain migration logic for updating old data structures
* or setting up new resources that weren't needed by the previous version.
- * It is called with the new version for each active priorityAgent.
+ * It is called with the new version for each active priorityTwist.
*
* @returns Promise that resolves when upgrade is complete
*/
@@ -234,7 +234,7 @@ export abstract class Agent {
}
/**
- * Called when the agent is removed from a priority.
+ * Called when the twist is removed from a priority.
*
* This method should contain cleanup logic such as removing webhooks,
* cleaning up external resources, or performing final data operations.
diff --git a/builder/src/utils/types.ts b/twister/src/utils/types.ts
similarity index 92%
rename from builder/src/utils/types.ts
rename to twister/src/utils/types.ts
index 120e934..5da39f8 100644
--- a/builder/src/utils/types.ts
+++ b/twister/src/utils/types.ts
@@ -4,7 +4,7 @@
* This file contains advanced TypeScript type utilities used internally
* by the SDK to provide type-safe APIs. Most developers don't need to
* reference these types directly - they work behind the scenes to power
- * the Agent and Tool APIs.
+ * the Twist and Tool APIs.
*
* @internal
*/
@@ -13,7 +13,7 @@ import type { Store } from "../tools/store";
import type { Tasks } from "../tools/tasks";
// ============================================================================
-// Type utilities for agent.ts
+// Type utilities for twist.ts
// ============================================================================
/**
@@ -34,7 +34,7 @@ export type ExtractBuildReturn = T extends {
: {};
/**
- * Built-in tools available to all agents and tools.
+ * Built-in tools available to all twists and tools.
*/
export type BuiltInTools = {
callbacks: Callbacks;
@@ -43,7 +43,7 @@ export type BuiltInTools = {
};
/**
- * Infers the complete set of tools available to an agent or tool,
+ * Infers the complete set of tools available to an twist or tool,
* combining tools declared in build with built-in tools.
*/
export type InferTools = PromiseValues> & BuiltInTools;
@@ -68,7 +68,7 @@ export type ToolBuilder = any>(
/**
* Interface for managing tool initialization and lifecycle.
- * Implemented by the agent runtime to provide tools to agents and tools.
+ * Implemented by the twist runtime to provide tools to twists and tools.
*/
export interface ToolShed {
/**
diff --git a/builder/tsconfig.base.json b/twister/tsconfig.base.json
similarity index 83%
rename from builder/tsconfig.base.json
rename to twister/tsconfig.base.json
index 858599f..f0b749c 100644
--- a/builder/tsconfig.base.json
+++ b/twister/tsconfig.base.json
@@ -1,9 +1,9 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
- "display": "Plot Agent Base Configuration",
+ "display": "Plot Twist Base Configuration",
"compilerOptions": {
- "target": "ESNext",
- "lib": ["ES2021", "ES2022.error", "WebWorker"],
+ "target": "ES2020",
+ "lib": ["ES2020", "ES2021", "ES2022.error", "WebWorker"],
"module": "ESNext",
"moduleResolution": "bundler",
"resolveJsonModule": true,
diff --git a/builder/tsconfig.build.json b/twister/tsconfig.build.json
similarity index 100%
rename from builder/tsconfig.build.json
rename to twister/tsconfig.build.json
diff --git a/builder/tsconfig.cli.json b/twister/tsconfig.cli.json
similarity index 100%
rename from builder/tsconfig.cli.json
rename to twister/tsconfig.cli.json
diff --git a/builder/tsconfig.json b/twister/tsconfig.json
similarity index 95%
rename from builder/tsconfig.json
rename to twister/tsconfig.json
index b4742bf..b49377d 100644
--- a/builder/tsconfig.json
+++ b/twister/tsconfig.json
@@ -1,6 +1,6 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
- "display": "Plot Agent Builder",
+ "display": "Plot Twist Creator",
"compilerOptions": {
"target": "ESNext",
"lib": ["ES2021", "ES2022.error", "WebWorker"],
diff --git a/builder/typedoc.json b/twister/typedoc.json
similarity index 89%
rename from builder/typedoc.json
rename to twister/typedoc.json
index 93e89c1..0352727 100644
--- a/builder/typedoc.json
+++ b/twister/typedoc.json
@@ -2,11 +2,11 @@
"$schema": "https://typedoc.org/schema.json",
"entryPoints": [
"src/index.ts",
- "src/agent.ts",
+ "src/twist.ts",
"src/tool.ts",
"src/plot.ts",
"src/tag.ts",
- "src/tools/agents.ts",
+ "src/tools/twists.ts",
"src/tools/ai.ts",
"src/tools/callbacks.ts",
"src/tools/integrations.ts",
@@ -23,8 +23,8 @@
"**/*+(.spec|.test).ts",
"**/llm-docs/**",
"**/cli/**",
- "src/agents-guide.ts",
- "src/builder-docs.ts",
+ "src/twist-guide.ts",
+ "src/creator-docs.ts",
"prebuild.ts",
"postbuild.js"
],
@@ -42,17 +42,17 @@
"docs/RUNTIME.md",
"docs/ADVANCED.md"
],
- "name": "Plot Agent Builder",
+ "name": "Plot Twist Creator",
"includeVersion": false,
"disableSources": false,
- "sourceLinkTemplate": "https://github.com/plotday/plot/blob/main/builder/{path}#L{line}",
+ "sourceLinkTemplate": "https://github.com/plotday/plot/blob/main/twist/{path}#L{line}",
"navigation": {
"includeCategories": true,
"includeGroups": true
},
"categorizeByGroup": true,
"categoryOrder": [
- "Agent",
+ "Twist",
"Tool",
"Data Types",
"Tools",
@@ -87,7 +87,7 @@
"navigationLinks": {
"Plot": "https://plot.day",
"GitHub": "https://github.com/plotday/plot",
- "NPM": "https://www.npmjs.com/package/@plotday/agent"
+ "NPM": "https://www.npmjs.com/package/@plotday/twister"
},
"titleLink": "/",
"favicon": "assets/favicon.svg",
diff --git a/agents/events/package.json b/twists/calendar-sync/package.json
similarity index 72%
rename from agents/events/package.json
rename to twists/calendar-sync/package.json
index 9441a0b..32ce7f2 100644
--- a/agents/events/package.json
+++ b/twists/calendar-sync/package.json
@@ -1,7 +1,7 @@
{
- "name": "@plotday/agent-events",
- "plotAgentId": "0199b6f4-85b8-7b21-aeb2-ac4169e351af",
- "displayName": "Events",
+ "name": "@plotday/twist-calendar-sync",
+ "plotTwistId": "0199b6f4-85b8-7b21-aeb2-ac4169e351af",
+ "displayName": "Calendar Sync",
"description": "Sync calendar events",
"main": "src/index.ts",
"types": "src/index.ts",
@@ -14,7 +14,7 @@
"logs": "plot logs"
},
"dependencies": {
- "@plotday/agent": "workspace:^",
+ "@plotday/twister": "workspace:^",
"@plotday/tool-google-calendar": "workspace:^",
"@plotday/tool-outlook-calendar": "workspace:^"
},
diff --git a/agents/events/src/index.ts b/twists/calendar-sync/src/index.ts
similarity index 96%
rename from agents/events/src/index.ts
rename to twists/calendar-sync/src/index.ts
index 0fcd83f..af61bfc 100644
--- a/agents/events/src/index.ts
+++ b/twists/calendar-sync/src/index.ts
@@ -1,21 +1,21 @@
+import { GoogleCalendar } from "@plotday/tool-google-calendar";
+import { OutlookCalendar } from "@plotday/tool-outlook-calendar";
import {
type Activity,
type ActivityLink,
ActivityLinkType,
ActivityType,
- Agent,
type Priority,
type ToolBuilder,
-} from "@plotday/agent";
+ Twist,
+} from "@plotday/twister";
import type {
Calendar,
CalendarAuth,
CalendarTool,
SyncOptions,
-} from "@plotday/agent/common/calendar";
-import { ActivityAccess, Plot } from "@plotday/agent/tools/plot";
-import { GoogleCalendar } from "@plotday/tool-google-calendar";
-import { OutlookCalendar } from "@plotday/tool-outlook-calendar";
+} from "@plotday/twister/common/calendar";
+import { ActivityAccess, Plot } from "@plotday/twister/tools/plot";
type CalendarProvider = "google" | "outlook";
@@ -24,7 +24,7 @@ type StoredCalendarAuth = {
authToken: string;
};
-export default class EventsAgent extends Agent {
+export default class CalendarSyncTwist extends Twist {
build(build: ToolBuilder) {
return {
googleCalendar: build(GoogleCalendar),
@@ -235,13 +235,13 @@ export default class EventsAgent extends Agent {
links.unshift({
title: `📅 ${calendar.name} (Primary)`,
type: ActivityLinkType.callback,
- token: token,
+ callback: token,
});
} else {
links.push({
title: `📅 ${calendar.name}`,
type: ActivityLinkType.callback,
- token: token,
+ callback: token,
});
}
}
diff --git a/agents/events/tsconfig.json b/twists/calendar-sync/tsconfig.json
similarity index 62%
rename from agents/events/tsconfig.json
rename to twists/calendar-sync/tsconfig.json
index 47e94ca..280de0f 100644
--- a/agents/events/tsconfig.json
+++ b/twists/calendar-sync/tsconfig.json
@@ -1,5 +1,5 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
- "extends": "@plotday/agent/tsconfig.base.json",
+ "extends": "@plotday/twister/tsconfig.base.json",
"include": ["src/**/*.ts"]
}
diff --git a/agents/chat/package.json b/twists/chat/package.json
similarity index 75%
rename from agents/chat/package.json
rename to twists/chat/package.json
index 7de86ad..4f75bdd 100644
--- a/agents/chat/package.json
+++ b/twists/chat/package.json
@@ -1,6 +1,6 @@
{
- "name": "@plotday/agent-chat",
- "plotAgentId": "0199b6f3-fa1b-7c18-bb91-52800f250609",
+ "name": "@plotday/twist-chat",
+ "plotTwistId": "0199b6f3-fa1b-7c18-bb91-52800f250609",
"displayName": "AI Chat",
"description": "Chat with AI models",
"main": "src/index.ts",
@@ -14,7 +14,7 @@
"logs": "plot logs"
},
"dependencies": {
- "@plotday/agent": "workspace:^",
+ "@plotday/twister": "workspace:^",
"typebox": "^1.0.35"
},
"devDependencies": {
diff --git a/agents/chat/src/index.ts b/twists/chat/src/index.ts
similarity index 89%
rename from agents/chat/src/index.ts
rename to twists/chat/src/index.ts
index aabe202..e75150c 100644
--- a/agents/chat/src/index.ts
+++ b/twists/chat/src/index.ts
@@ -3,15 +3,15 @@ import { Type } from "typebox";
import {
type Activity,
ActivityType,
- Agent,
+ Twist,
ActorType,
Tag,
type ToolBuilder,
-} from "@plotday/agent";
-import { AI, type AIMessage } from "@plotday/agent/tools/ai";
-import { ActivityAccess, Plot } from "@plotday/agent/tools/plot";
+} from "@plotday/twister";
+import { AI, type AIMessage } from "@plotday/twister/tools/ai";
+import { ActivityAccess, Plot } from "@plotday/twister/tools/plot";
-export default class ChatAgent extends Agent {
+export default class ChatTwist extends Twist {
build(build: ToolBuilder) {
return {
ai: build(AI),
@@ -40,8 +40,8 @@ export default class ChatAgent extends Agent {
// Add Thinking tag to indicate processing has started
await this.tools.plot.updateActivity({
id: activity.id,
- agentTags: {
- [Tag.Agent]: true,
+ twistTags: {
+ [Tag.Twist]: true,
},
});
@@ -58,7 +58,7 @@ You can also create tasks, but should only do so when the user explicitly asks y
(prevActivity) =>
({
role:
- prevActivity.author.type === ActorType.Agent
+ prevActivity.author.type === ActorType.Twist
? "assistant"
: "user",
content: (prevActivity.note ?? prevActivity.title)!,
@@ -123,8 +123,8 @@ You can also create tasks, but should only do so when the user explicitly asks y
// Remove Thinking tag after response is created
await this.tools.plot.updateActivity({
id: activity.id,
- agentTags: {
- [Tag.Agent]: false,
+ twistTags: {
+ [Tag.Twist]: false,
},
});
}
diff --git a/agents/message-tasks/tsconfig.json b/twists/chat/tsconfig.json
similarity index 62%
rename from agents/message-tasks/tsconfig.json
rename to twists/chat/tsconfig.json
index 47e94ca..280de0f 100644
--- a/agents/message-tasks/tsconfig.json
+++ b/twists/chat/tsconfig.json
@@ -1,5 +1,5 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
- "extends": "@plotday/agent/tsconfig.base.json",
+ "extends": "@plotday/twister/tsconfig.base.json",
"include": ["src/**/*.ts"]
}
diff --git a/agents/message-tasks/package.json b/twists/message-tasks/package.json
similarity index 77%
rename from agents/message-tasks/package.json
rename to twists/message-tasks/package.json
index e6e3638..cec44f7 100644
--- a/agents/message-tasks/package.json
+++ b/twists/message-tasks/package.json
@@ -1,6 +1,6 @@
{
- "name": "@plotday/agent-message-tasks",
- "plotAgentId": "0193c8a0-0000-7000-8000-000000000001",
+ "name": "@plotday/twist-message-tasks",
+ "plotTwistId": "0193c8a0-0000-7000-8000-000000000001",
"displayName": "Message Tasks",
"description": "Create tasks from actionable message threads",
"main": "src/index.ts",
@@ -14,7 +14,7 @@
"logs": "plot logs"
},
"dependencies": {
- "@plotday/agent": "workspace:^",
+ "@plotday/twister": "workspace:^",
"@plotday/tool-slack": "workspace:^",
"typebox": "^1.0.35"
},
diff --git a/agents/message-tasks/src/index.ts b/twists/message-tasks/src/index.ts
similarity index 97%
rename from agents/message-tasks/src/index.ts
rename to twists/message-tasks/src/index.ts
index ab3c804..5670ac9 100644
--- a/agents/message-tasks/src/index.ts
+++ b/twists/message-tasks/src/index.ts
@@ -1,23 +1,23 @@
import { Type } from "typebox";
+import { Slack } from "@plotday/tool-slack";
import {
type Activity,
type ActivityLink,
ActivityLinkType,
ActivityType,
- Agent,
type Priority,
type ToolBuilder,
-} from "@plotday/agent";
+ Twist,
+} from "@plotday/twister";
import type {
MessageChannel,
MessageSyncOptions,
MessagingAuth,
MessagingTool,
-} from "@plotday/agent/common/messaging";
-import { AI, type AIMessage } from "@plotday/agent/tools/ai";
-import { ActivityAccess, Plot } from "@plotday/agent/tools/plot";
-import { Slack } from "@plotday/tool-slack";
+} from "@plotday/twister/common/messaging";
+import { AI, type AIMessage } from "@plotday/twister/tools/ai";
+import { ActivityAccess, Plot } from "@plotday/twister/tools/plot";
type MessageProvider = "slack";
@@ -40,7 +40,7 @@ type ThreadTask = {
lastChecked: string;
};
-export default class MessageTasksAgent extends Agent {
+export default class MessageTasksTwist extends Twist {
build(build: ToolBuilder) {
return {
slack: build(Slack),
@@ -243,13 +243,13 @@ export default class MessageTasksAgent extends Agent {
links.unshift({
title: `💬 ${channel.name} (Primary)`,
type: ActivityLinkType.callback,
- token: token,
+ callback: token,
});
} else {
links.push({
title: `💬 ${channel.name}`,
type: ActivityLinkType.callback,
- token: token,
+ callback: token,
});
}
}
diff --git a/agents/chat/tsconfig.json b/twists/message-tasks/tsconfig.json
similarity index 62%
rename from agents/chat/tsconfig.json
rename to twists/message-tasks/tsconfig.json
index 47e94ca..280de0f 100644
--- a/agents/chat/tsconfig.json
+++ b/twists/message-tasks/tsconfig.json
@@ -1,5 +1,5 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
- "extends": "@plotday/agent/tsconfig.base.json",
+ "extends": "@plotday/twister/tsconfig.base.json",
"include": ["src/**/*.ts"]
}