Skip to content

Commit 59ae641

Browse files
KrisBraunKrisBraun
committed
Reference sdk types in AGENTS rather than duplicating
1 parent 7cd2d7e commit 59ae641

7 files changed

Lines changed: 171 additions & 209 deletions

File tree

‎agents/chat/src/index.ts‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,22 @@
1+
import { Type } from "typebox";
2+
13
import {
24
type Activity,
35
ActivityType,
46
Agent,
57
AuthorType,
68
Tag,
7-
Tools,
9+
type Tools,
810
} from "@plotday/sdk";
9-
import { AI, AIModel, type AIMessage } from "@plotday/sdk/tools/ai";
11+
import { AI, type AIMessage } from "@plotday/sdk/tools/ai";
1012
import { Plot } from "@plotday/sdk/tools/plot";
11-
import { Type } from "typebox";
1213

1314
export default class extends Agent {
1415
private ai: AI;
1516
private plot: Plot;
1617

1718
constructor(protected tools: Tools) {
18-
super();
19+
super(tools);
1920
this.ai = tools.get(AI);
2021
this.plot = tools.get(Plot);
2122
}
@@ -26,7 +27,7 @@ export default class extends Agent {
2627
previous: Activity;
2728
tagsAdded: Record<number, string[]>;
2829
tagsRemoved: Record<number, string[]>;
29-
},
30+
}
3031
) {
3132
if (changes) return;
3233

@@ -35,7 +36,7 @@ export default class extends Agent {
3536
if (
3637
activity.note?.includes("@chat") ||
3738
previousActivities.some((activity: any) =>
38-
activity.note.includes("@chat"),
39+
activity.note.includes("@chat")
3940
)
4041
) {
4142
// Add Thinking tag to indicate processing has started
@@ -63,7 +64,7 @@ You can also create tasks, but should only do so when the user explicitly asks y
6364
? "assistant"
6465
: "user",
6566
content: (prevActivity.note ?? prevActivity.title)!,
66-
}) satisfies AIMessage,
67+
} satisfies AIMessage)
6768
),
6869
];
6970

@@ -81,7 +82,7 @@ You can also create tasks, but should only do so when the user explicitly asks y
8182
Type.String({
8283
description:
8384
"Optional detailed description of the action item. Can include markdown. Only add when important details are needed beyond the title.",
84-
}),
85+
})
8586
),
8687
title: Type.String({
8788
description:
@@ -90,13 +91,13 @@ You can also create tasks, but should only do so when the user explicitly asks y
9091
}),
9192
{
9293
description: "Tasks to create in response to the user's request.",
93-
},
94-
),
94+
}
95+
)
9596
),
9697
});
9798

9899
const response = await this.ai.prompt({
99-
model: AIModel.LLAMA_33_70B,
100+
model: { speed: "balanced", cost: "low" },
100101
messages,
101102
outputSchema: schema,
102103
});
@@ -117,7 +118,7 @@ You can also create tasks, but should only do so when the user explicitly asks y
117118
priority: activity.priority,
118119
type: ActivityType.Task,
119120
start: new Date(),
120-
}),
121+
})
121122
) ?? []),
122123
]);
123124

‎sdk/cli/templates/AGENTS.template.md‎

Lines changed: 12 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,7 @@ Plot agents are TypeScript classes that extend the `Agent` base class. Agents in
2020
## Agent Structure Pattern
2121

2222
```typescript
23-
import {
24-
type Activity,
25-
Agent,
26-
type Priority,
27-
type Tools,
28-
} from "@plotday/sdk";
23+
import { type Activity, Agent, type Priority, type Tools } from "@plotday/sdk";
2924
import { Plot } from "@plotday/sdk/tools/plot";
3025

3126
export default class MyAgent extends Agent {
@@ -66,99 +61,22 @@ All `tools.get()` calls must occur in the constructor as they are used for depen
6661

6762
### Built-in Tools (Always Available)
6863

69-
#### Plot Tool
64+
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/sdk/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.
7065

71-
Core functionality for managing activities:
66+
**Quick reference - Available tools:**
7267

73-
```typescript
74-
import { Plot } from "@plotday/sdk/tools/plot";
75-
76-
// Create activity
77-
await this.plot.createActivity({
78-
type: ActivityType.Task,
79-
title: "Task title",
80-
start: new Date(),
81-
end: null,
82-
links: [], // Optional activity links
83-
parent: { id: "parent-activity-id" }, // Optional parent
84-
});
85-
86-
// Update activity
87-
await this.plot.updateActivity(activityId, {
88-
title: "New title",
89-
completed: true,
90-
});
91-
92-
// Delete activity
93-
await this.plot.deleteActivity(activityId);
94-
95-
// Add contacts
96-
await this.plot.addContacts(contacts);
97-
```
98-
99-
#### Store Tool
100-
101-
Persistent key-value storage (available directly via `this`):
102-
103-
```typescript
104-
// Set value (no import needed)
105-
await this.set("key", value);
106-
107-
// Get value
108-
const value = await this.get<Type>("key");
109-
110-
// Clear value
111-
await this.clear("key");
112-
113-
// Clear all values
114-
await this.clearAll();
115-
```
68+
- `@plotday/sdk/tools/plot` - Core data layer (create/update activities, priorities, contacts)
69+
- `@plotday/sdk/tools/ai` - LLM integration (text generation, structured output, reasoning)
70+
- Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)
71+
- `@plotday/sdk/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)
72+
- `@plotday/sdk/tools/run` - Queue batched work (also via `this.run()`)
73+
- `@plotday/sdk/tools/callback` - Persistent function references (also via `this.callback()`)
74+
- `@plotday/sdk/tools/auth` - OAuth2 authentication flows
75+
- `@plotday/sdk/tools/webhook` - HTTP webhook management
76+
- `@plotday/sdk/tools/agent` - Manage other agents
11677

11778
**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.
11879

119-
#### Run Tool
120-
121-
Queue separate chunks of work (available directly via `this`):
122-
123-
```typescript
124-
// Create callback and queue execution (no import needed)
125-
const callback = await this.callback("functionName", { context: "data" });
126-
await this.run(callback);
127-
128-
// The function must exist on the agent class
129-
async functionName(args: any, context: { context: string }) {
130-
// Process batch and queue next if needed
131-
if (hasMore) {
132-
const nextCallback = await this.callback("functionName", { context: "next" });
133-
await this.run(nextCallback);
134-
}
135-
}
136-
```
137-
138-
#### Callback Tool
139-
140-
Create persistent function references (for webhooks, auth callbacks - available directly via `this`):
141-
142-
```typescript
143-
// Create callback (no import needed)
144-
const token = await this.callback("onAuthComplete", {
145-
provider: "google",
146-
});
147-
148-
// Pass token to external service or store it
149-
await this.set("webhook_token", token);
150-
151-
// When callback is invoked, your function is called
152-
async onAuthComplete(authResult: any, context?: any) {
153-
// Handle callback
154-
const provider = context?.provider;
155-
}
156-
157-
// Clean up
158-
await this.deleteCallback(token);
159-
await this.deleteAllCallbacks(); // Delete all for this agent
160-
```
161-
16280
### External Tools (Add to package.json)
16381

16482
Add tool dependencies to `package.json`:

‎sdk/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,10 @@
6666
"types": "./dist/agents-guide.d.ts",
6767
"default": "./dist/agents-guide.js"
6868
},
69+
"./sdk-docs": {
70+
"types": "./dist/sdk-docs.d.ts",
71+
"default": "./dist/sdk-docs.js"
72+
},
6973
"./tsconfig.base.json": "./tsconfig.base.json"
7074
},
7175
"files": [

‎sdk/src/agents-guide.ts‎

Lines changed: 12 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -80,99 +80,23 @@ Assign tool instances to class properties for use in other methods.
8080
8181
### Built-in Tools (Always Available)
8282
83-
#### Plot Tool
83+
The following tools are always available to agents. For complete API documentation including all methods, parameters, return types, and detailed examples, refer to the TypeScript definitions which are provided with full JSDoc when generating agents.
8484
85-
Core functionality for managing activities:
85+
**Available Built-in Tools:**
86+
- **Plot** (\`@plotday/sdk/tools/plot\`): Core data layer - create/update activities, priorities, contacts
87+
- **AI** (\`@plotday/sdk/tools/ai\`): LLM access for text generation, structured output, reasoning
88+
- Use ModelPreferences to specify \`speed\` (fast/balanced/capable) and \`cost\` (low/medium/high)
89+
- **Store** (\`@plotday/sdk/tools/store\`): Persistent key-value storage (also available via \`this.set()\`, \`this.get()\`)
90+
- **Run** (\`@plotday/sdk/tools/run\`): Queue batched work (also available via \`this.run()\`)
91+
- **Callback** (\`@plotday/sdk/tools/callback\`): Persistent function references (also available via \`this.callback()\`)
92+
- **Auth** (\`@plotday/sdk/tools/auth\`): OAuth2 authentication flows
93+
- **Webhook** (\`@plotday/sdk/tools/webhook\`): HTTP webhook management
94+
- **AgentManager** (\`@plotday/sdk/tools/agent\`): Manage other agents
8695
87-
\`\`\`typescript
88-
import { Plot } from "@plotday/sdk/tools/plot";
89-
90-
// Create activity
91-
await this.plot.createActivity({
92-
type: ActivityType.Task,
93-
title: "Task title",
94-
start: new Date(),
95-
end: null,
96-
links: [], // Optional activity links
97-
parent: { id: "parent-activity-id" }, // Optional parent
98-
});
99-
100-
// Update activity
101-
await this.plot.updateActivity(activityId, {
102-
title: "New title",
103-
completed: true,
104-
});
105-
106-
// Delete activity
107-
await this.plot.deleteActivity(activityId);
108-
109-
// Add contacts
110-
await this.plot.addContacts(contacts);
111-
\`\`\`
112-
113-
#### Store Tool
114-
115-
Persistent key-value storage (available directly via \`this\`):
116-
117-
\`\`\`typescript
118-
// Set value (no import needed)
119-
await this.set("key", value);
120-
121-
// Get value
122-
const value = await this.get<Type>("key");
123-
124-
// Clear value
125-
await this.clear("key");
126-
127-
// Clear all values
128-
await this.clearAll();
129-
\`\`\`
96+
See the SDK type definitions for full API documentation with usage examples.
13097
13198
**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.
13299
133-
#### Run Tool
134-
135-
Queue separate chunks of work (available directly via \`this\`):
136-
137-
\`\`\`typescript
138-
// Create callback and queue execution (no import needed)
139-
const callback = await this.callback("functionName", { context: "data" });
140-
await this.run(callback);
141-
142-
// The function must exist on the agent class
143-
async functionName(args: any, context: { context: string }) {
144-
// Process batch and queue next if needed
145-
if (hasMore) {
146-
const nextCallback = await this.callback("functionName", { context: "next" });
147-
await this.run(nextCallback);
148-
}
149-
}
150-
\`\`\`
151-
152-
#### Callback Tool
153-
154-
Create persistent function references (for webhooks, auth callbacks - available directly via \`this\`):
155-
156-
\`\`\`typescript
157-
// Create callback (no import needed)
158-
const token = await this.callback("onAuthComplete", {
159-
provider: "google",
160-
});
161-
162-
// Pass token to external service or store it
163-
await this.set("webhook_token", token);
164-
165-
// When callback is invoked, your function is called
166-
async onAuthComplete(authResult: any, context?: any) {
167-
// Handle callback
168-
const provider = context?.provider;
169-
}
170-
171-
// Clean up
172-
await this.deleteCallback(token);
173-
await this.deleteAllCallbacks(); // Delete all for this agent
174-
\`\`\`
175-
176100
### External Tools (Add to package.json)
177101
178102
Add tool dependencies to \`package.json\`:

‎sdk/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ export * from "./agent";
22
export * from "./plot";
33
export * from "./tag";
44
export * from "./tools";
5+
export { getSDKDocumentation } from "./sdk-docs";

0 commit comments

Comments
 (0)