@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 533 lines 19.8 KB
Raw
1 import * as bedrock from "@distilled.cloud/aws/bedrock-agent";
2 import * as iam from "@distilled.cloud/aws/iam";
3 import { Unowned } from "alchemy/AdoptPolicy";
4 import { isResolved } from "alchemy/Diff";
5 import { createPhysicalName } from "alchemy/PhysicalName";
6 import * as Provider from "alchemy/Provider";
7 import { Resource } from "alchemy/Resource";
8 import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
9 import { toWireDays, toWireSeconds } from "alchemy/Util/Duration";
10 import type * as Duration from "effect/Duration";
11 import * as Effect from "effect/Effect";
12 import * as Schedule from "effect/Schedule";
13 import * as Stream from "effect/Stream";
14 import { AWSEnvironment } from "../Environment.ts";
15 import { bedrockModelArns } from "./ModelArns.ts";
16
17 /**
18 * A guardrail attached to an agent to apply content filters, denied topics,
19 * word filters, and sensitive-information policies to model interactions.
20 */
21 export interface AgentGuardrailConfiguration {
22 /** The unique identifier of the guardrail. */
23 guardrailIdentifier?: string;
24 /** The version of the guardrail. */
25 guardrailVersion?: string;
26 }
27
28 /**
29 * Long-term memory configuration for an agent — lets the agent retain
30 * conversational context across sessions as asynchronously generated
31 * session summaries, readable at runtime via the `GetAgentMemory` binding.
32 */
33 export interface AgentMemoryConfiguration {
34 /**
35 * The types of memory to enable. `"SESSION_SUMMARY"` is currently the
36 * only supported type.
37 */
38 enabledMemoryTypes: bedrock.MemoryType[];
39 /**
40 * How long the agent retains memory (e.g. `"30 days"` or
41 * `Duration.days(30)`; a bare number is milliseconds). Between 1 and
42 * 365 days. Sent to the API as whole days (`storageDays`).
43 * @default 30 days
44 */
45 storage?: Duration.Input;
46 /**
47 * Configuration for `SESSION_SUMMARY` memory.
48 */
49 sessionSummaryConfiguration?: {
50 /** The maximum number of recent session summaries to include. */
51 maxRecentSessions?: number;
52 };
53 }
54
55 export interface AgentProps {
56 /**
57 * Name of the agent (1-100 characters; letters, digits, and the
58 * characters `_-`). If omitted, a deterministic physical name is
59 * generated from the app, stage, and logical ID. Changing the name
60 * triggers a replacement.
61 */
62 agentName?: string;
63 /**
64 * The foundation model or inference-profile id the agent uses for
65 * orchestration — a foundation-model id
66 * (`anthropic.claude-3-5-sonnet-20240620-v1:0`), a cross-region inference
67 * profile id (`us.anthropic.claude-3-5-sonnet-20240620-v1:0`), or a full
68 * Bedrock ARN. Model access must be enabled in the account.
69 */
70 foundationModel: string;
71 /**
72 * Instructions that tell the agent what it should do and how it should
73 * interact with users. Must be at least 40 characters for the agent to be
74 * preparable.
75 */
76 instruction: string;
77 /**
78 * A description of the agent.
79 */
80 description?: string;
81 /**
82 * The ARN of an existing IAM role for the agent to assume. When omitted,
83 * an execution role is created automatically with `bedrock.amazonaws.com`
84 * trust and `bedrock:InvokeModel` granted on {@link AgentProps.foundationModel}.
85 */
86 agentResourceRoleArn?: string;
87 /**
88 * How long the agent retains an idle session before it is ended (e.g.
89 * `"30 minutes"` or `Duration.minutes(30)`; a bare number is milliseconds).
90 * Between 1 minute and 1 hour. Sent to the API as whole seconds
91 * (`idleSessionTTLInSeconds`).
92 * @default 600 seconds
93 */
94 idleSessionTTL?: Duration.Input;
95 /**
96 * The ARN of a KMS key to encrypt the agent with.
97 */
98 customerEncryptionKeyArn?: string;
99 /**
100 * A guardrail to apply to the agent's model interactions.
101 */
102 guardrailConfiguration?: AgentGuardrailConfiguration;
103 /**
104 * Long-term memory configuration. When enabled the agent summarizes each
105 * session after it ends and retains the summaries for
106 * {@link AgentMemoryConfiguration.storage}, making them available to
107 * later sessions that share the same memory id (and to the
108 * `GetAgentMemory` / `DeleteAgentMemory` runtime bindings).
109 */
110 memoryConfiguration?: AgentMemoryConfiguration;
111 /**
112 * Whether to prepare the agent (compile the DRAFT version) after every
113 * create and update so it is invocable and can back an
114 * {@link AgentAlias}. Preparation is polled to completion.
115 * @default true
116 */
117 prepare?: boolean;
118 /**
119 * Tags to apply to the agent. Merged with internal Alchemy tags.
120 */
121 tags?: Record<string, string>;
122 }
123
124 export interface Agent extends Resource<
125 "AWS.Bedrock.Agent",
126 AgentProps,
127 {
128 /**
129 * The unique identifier of the agent.
130 */
131 agentId: string;
132 /**
133 * The ARN of the agent.
134 */
135 agentArn: string;
136 /**
137 * Name of the agent.
138 */
139 agentName: string;
140 /** The DRAFT version identifier (always `"DRAFT"`). */
141 agentVersion: string;
142 /** The ARN of the role the agent assumes. */
143 agentResourceRoleArn: string;
144 /**
145 * Name of the auto-created execution role. `undefined` when an explicit
146 * {@link AgentProps.agentResourceRoleArn} is used.
147 */
148 roleName: string | undefined;
149 }
150 > {}
151
152 /**
153 * An Amazon Bedrock agent — a foundation model driven by natural-language
154 * instructions that can orchestrate multi-step tasks.
155 *
156 * `Agent` owns the lifecycle of the agent's DRAFT version. An IAM execution
157 * role is created automatically (trusted by `bedrock.amazonaws.com`, granted
158 * `bedrock:InvokeModel` on the foundation model) unless an explicit
159 * `agentResourceRoleArn` is supplied. After every create/update the agent is
160 * prepared (unless `prepare: false`) so it is immediately invocable and can
161 * back an {@link AgentAlias}.
162 *
163 * ### Creating Agents
164 * **Example:** Minimal Agent
165 * ```typescript
166 * import * as Bedrock from "@alchemy.run/aws/Bedrock";
167 *
168 * const agent = yield* Bedrock.Agent("assistant", {
169 * foundationModel: "us.anthropic.claude-3-5-sonnet-20240620-v1:0",
170 * instruction:
171 * "You are a helpful assistant that answers questions concisely.",
172 * });
173 * ```
174 *
175 * **Example:** Agent with a Guardrail and Custom Session TTL
176 * ```typescript
177 * const agent = yield* Bedrock.Agent("assistant", {
178 * foundationModel: "us.anthropic.claude-3-5-sonnet-20240620-v1:0",
179 * instruction: "You are a careful, policy-compliant support agent.",
180 * idleSessionTTL: "30 minutes",
181 * guardrailConfiguration: {
182 * guardrailIdentifier: guardrail.guardrailId,
183 * guardrailVersion: "DRAFT",
184 * },
185 * });
186 * ```
187 *
188 * **Example:** Agent with Long-Term Memory
189 * ```typescript
190 * // Session summaries are retained for 30 days and readable at runtime
191 * // through the GetAgentMemory binding.
192 * const agent = yield* Bedrock.Agent("assistant", {
193 * foundationModel: "us.anthropic.claude-3-5-sonnet-20240620-v1:0",
194 * instruction: "You are a helpful assistant that remembers past sessions.",
195 * memoryConfiguration: {
196 * enabledMemoryTypes: ["SESSION_SUMMARY"],
197 * storage: "30 days",
198 * },
199 * });
200 * ```
201 *
202 * @resource
203 */
204 export const Agent = Resource<Agent>("AWS.Bedrock.Agent");
205
206 /** Map the declared memory props onto the wire `MemoryConfiguration`. */
207 const toWireMemoryConfiguration = (
208 memory: AgentMemoryConfiguration | undefined,
209 ): bedrock.MemoryConfiguration | undefined =>
210 memory === undefined
211 ? undefined
212 : {
213 enabledMemoryTypes: [...memory.enabledMemoryTypes],
214 storageDays: toWireDays(memory.storage),
215 sessionSummaryConfiguration: memory.sessionSummaryConfiguration,
216 };
217
218 /** Agent status values from which no further transition is pending. */
219 const _AGENT_SETTLED = new Set(["NOT_PREPARED", "PREPARED", "FAILED"]);
220
221 /** Agent status values indicating an in-flight transition to wait out. */
222 const AGENT_TRANSIENT = new Set(["CREATING", "UPDATING", "PREPARING", "VERSIONING"]);
223
224 /**
225 * A freshly created IAM role is eventually consistent; `createAgent` can
226 * transiently reject a role it cannot yet assume with a `ValidationException`.
227 * Wrapped in an explicitly-typed generic helper so the `Effect.retry`
228 * conditional return type does not leak into declaration emit and widen the
229 * provider layer's requirement to `unknown` (see PATTERNS §7).
230 */
231 const retryWhileRoleAssumeFails = <A, E extends { _tag: string }, R>(
232 self: Effect.Effect<A, E, R>,
233 ): Effect.Effect<A, E, R> =>
234 Effect.retry(self, {
235 while: (e) =>
236 e._tag === "ValidationException" &&
237 "message" in e &&
238 typeof e.message === "string" &&
239 e.message.toLowerCase().includes("unable to assume"),
240 schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
241 });
242
243 export const AgentProvider = () =>
244 Provider.effect(
245 Agent,
246 Effect.gen(function* () {
247 const createName = Effect.fn(function* (id: string, props: AgentProps) {
248 return props.agentName ?? (yield* createPhysicalName({ id, maxLength: 100 }));
249 });
250
251 const createRoleName = (id: string) => createPhysicalName({ id, maxLength: 64 });
252
253 const getAgentOrUndefined = Effect.fn(function* (agentId: string) {
254 return yield* bedrock.getAgent({ agentId }).pipe(
255 Effect.map((r) => r.agent),
256 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
257 );
258 });
259
260 const findByName = Effect.fn(function* (name: string) {
261 const pages = yield* bedrock.listAgents.pages({}).pipe(Stream.runCollect);
262 const summary = Array.from(pages)
263 .flatMap((page) => page.agentSummaries ?? [])
264 .find((s) => s.agentName === name);
265 return summary?.agentId;
266 });
267
268 const fetchObservedTags = Effect.fn(function* (resourceArn: string) {
269 return yield* bedrock.listTagsForResource({ resourceArn }).pipe(
270 Effect.map((r) => (r.tags ?? {}) as Record<string, string>),
271 Effect.catchTag("ResourceNotFoundException", () =>
272 Effect.succeed({} as Record<string, string>),
273 ),
274 );
275 });
276
277 // Poll the agent to a settled (non-transient) status. Bounded: creation
278 // and preparation both complete within seconds to ~1 minute.
279 const waitForSettled = Effect.fn(function* (agentId: string) {
280 return yield* bedrock.getAgent({ agentId }).pipe(
281 Effect.map((r) => r.agent),
282 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
283 Effect.repeat({
284 schedule: Schedule.fixed("3 seconds"),
285 until: (agent) => agent === undefined || !AGENT_TRANSIENT.has(agent.agentStatus),
286 times: 40,
287 }),
288 );
289 });
290
291 const ensureExecutionRole = Effect.fn(function* ({
292 id,
293 roleName,
294 region,
295 accountId,
296 foundationModel,
297 }: {
298 id: string;
299 roleName: string;
300 region: string;
301 accountId: string;
302 foundationModel: string;
303 }) {
304 const tags = yield* createInternalTags(id);
305 const role = yield* iam
306 .createRole({
307 RoleName: roleName,
308 AssumeRolePolicyDocument: JSON.stringify({
309 Version: "2012-10-17",
310 Statement: [
311 {
312 Effect: "Allow",
313 Principal: { Service: "bedrock.amazonaws.com" },
314 Action: "sts:AssumeRole",
315 Condition: {
316 StringEquals: { "aws:SourceAccount": accountId },
317 ArnLike: {
318 "aws:SourceArn": `arn:aws:bedrock:${region}:${accountId}:agent/*`,
319 },
320 },
321 },
322 ],
323 }),
324 Tags: Object.entries(tags).map(([Key, Value]) => ({ Key, Value })),
325 })
326 .pipe(
327 Effect.catchTag("EntityAlreadyExistsException", () =>
328 iam.getRole({ RoleName: roleName }),
329 ),
330 );
331
332 yield* iam.putRolePolicy({
333 RoleName: roleName,
334 PolicyName: "BedrockAgentInvokeModel",
335 PolicyDocument: JSON.stringify({
336 Version: "2012-10-17",
337 Statement: [
338 {
339 Effect: "Allow",
340 Action: ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
341 Resource: bedrockModelArns(region, accountId, foundationModel),
342 },
343 ],
344 }),
345 });
346
347 return role.Role.Arn;
348 });
349
350 return Agent.Provider.of({
351 stables: ["agentId", "agentArn", "agentName"],
352
353 list: () =>
354 Effect.gen(function* () {
355 const { region, accountId } = yield* AWSEnvironment.current;
356 const pages = yield* bedrock.listAgents.pages({}).pipe(Stream.runCollect);
357 const summaries = Array.from(pages).flatMap((page) => page.agentSummaries ?? []);
358 return summaries.map((s) => ({
359 agentId: s.agentId,
360 agentArn: `arn:aws:bedrock:${region}:${accountId}:agent/${s.agentId}`,
361 agentName: s.agentName,
362 agentVersion: "DRAFT",
363 agentResourceRoleArn: "",
364 roleName: undefined as string | undefined,
365 }));
366 }),
367
368 read: Effect.fn(function* ({ id, olds, output }) {
369 const agentId =
370 output?.agentId ??
371 (yield* findByName(
372 output?.agentName ?? (yield* createName(id, olds ?? ({} as AgentProps))),
373 ));
374 if (agentId === undefined) return undefined;
375 const agent = yield* getAgentOrUndefined(agentId);
376 if (agent === undefined || agent.agentStatus === "DELETING") {
377 return undefined;
378 }
379 const attrs = {
380 agentId: agent.agentId,
381 agentArn: agent.agentArn,
382 agentName: agent.agentName,
383 agentVersion: agent.agentVersion ?? "DRAFT",
384 agentResourceRoleArn: agent.agentResourceRoleArn,
385 roleName: output?.roleName,
386 };
387 const tags = yield* fetchObservedTags(agent.agentArn);
388 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
389 }),
390
391 diff: Effect.fn(function* ({ id, news, olds }) {
392 if (!isResolved(news)) return undefined;
393 const oldName = yield* createName(id, olds ?? ({} as AgentProps));
394 const newName = yield* createName(id, news ?? ({} as AgentProps));
395 if (oldName !== newName) {
396 return { action: "replace" } as const;
397 }
398 // foundationModel, instruction, description, guardrail, TTL, and
399 // tags all converge via updateAgent.
400 }),
401
402 reconcile: Effect.fn(function* ({ id, news = {} as AgentProps, output, session }) {
403 const { accountId, region } = yield* AWSEnvironment.current;
404 const name = output?.agentName ?? (yield* createName(id, news));
405 const internalTags = yield* createInternalTags(id);
406 const desiredTags = { ...news.tags, ...internalTags };
407
408 // Ensure the execution role first — the agent cannot exist without
409 // one. Managed unless an explicit agentResourceRoleArn is provided.
410 let roleArn = news.agentResourceRoleArn;
411 let roleName = output?.roleName;
412 if (roleArn === undefined) {
413 roleName = roleName ?? (yield* createRoleName(id));
414 roleArn = yield* ensureExecutionRole({
415 id,
416 roleName,
417 region,
418 accountId,
419 foundationModel: news.foundationModel,
420 });
421 }
422
423 // 1. OBSERVE — cloud state is authoritative; output is only an id
424 // cache. Fall back to a name lookup after state loss.
425 let agent = output?.agentId ? yield* getAgentOrUndefined(output.agentId) : undefined;
426 if (agent === undefined) {
427 const foundId = yield* findByName(name);
428 if (foundId !== undefined) {
429 agent = yield* getAgentOrUndefined(foundId);
430 }
431 }
432
433 if (agent === undefined) {
434 // 2. ENSURE — create.
435 const created = yield* retryWhileRoleAssumeFails(
436 bedrock.createAgent({
437 agentName: name,
438 foundationModel: news.foundationModel,
439 instruction: news.instruction,
440 description: news.description,
441 agentResourceRoleArn: roleArn,
442 idleSessionTTLInSeconds: toWireSeconds(news.idleSessionTTL),
443 customerEncryptionKeyArn: news.customerEncryptionKeyArn,
444 guardrailConfiguration: news.guardrailConfiguration,
445 memoryConfiguration: toWireMemoryConfiguration(news.memoryConfiguration),
446 tags: desiredTags,
447 }),
448 );
449 agent = created.agent;
450 agent = (yield* waitForSettled(agent.agentId)) ?? agent;
451 } else {
452 // 3. SYNC — wait for any in-flight transition, then update.
453 agent = (yield* waitForSettled(agent.agentId)) ?? agent;
454 yield* bedrock.updateAgent({
455 agentId: agent.agentId,
456 agentName: name,
457 foundationModel: news.foundationModel,
458 instruction: news.instruction,
459 description: news.description,
460 agentResourceRoleArn: roleArn,
461 idleSessionTTLInSeconds: toWireSeconds(news.idleSessionTTL),
462 customerEncryptionKeyArn: news.customerEncryptionKeyArn,
463 guardrailConfiguration: news.guardrailConfiguration,
464 memoryConfiguration: toWireMemoryConfiguration(news.memoryConfiguration),
465 });
466 agent = (yield* waitForSettled(agent.agentId)) ?? agent;
467 }
468
469 const agentId = agent.agentId;
470 const agentArn = agent.agentArn;
471
472 // 3b. SYNC TAGS — diff against OBSERVED cloud tags (create-time tags
473 // only apply on first create; adoption may carry foreign tags).
474 const observedTags = yield* fetchObservedTags(agentArn);
475 const { upsert, removed } = diffTags(observedTags, desiredTags);
476 if (upsert.length > 0) {
477 yield* bedrock.tagResource({
478 resourceArn: agentArn,
479 tags: Object.fromEntries(upsert.map(({ Key, Value }) => [Key, Value])),
480 });
481 }
482 if (removed.length > 0) {
483 yield* bedrock.untagResource({
484 resourceArn: agentArn,
485 tagKeys: removed,
486 });
487 }
488
489 // 4. PREPARE — compile the DRAFT so the agent is invocable and can
490 // back an alias. Bounded poll to PREPARED/FAILED.
491 if (news.prepare !== false) {
492 yield* bedrock.prepareAgent({ agentId });
493 agent = (yield* waitForSettled(agentId)) ?? agent;
494 }
495
496 yield* session.note(agentArn);
497 return {
498 agentId,
499 agentArn,
500 agentName: name,
501 agentVersion: agent.agentVersion ?? "DRAFT",
502 agentResourceRoleArn: roleArn,
503 roleName,
504 };
505 }),
506
507 delete: Effect.fn(function* ({ output }) {
508 yield* bedrock
509 .deleteAgent({
510 agentId: output.agentId,
511 skipResourceInUseCheck: true,
512 })
513 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
514
515 // Tear down the managed execution role (absent when an explicit
516 // agentResourceRoleArn was supplied). Every step tolerates a
517 // partially or fully removed role.
518 if (output.roleName !== undefined) {
519 const roleName = output.roleName;
520 yield* iam
521 .deleteRolePolicy({
522 RoleName: roleName,
523 PolicyName: "BedrockAgentInvokeModel",
524 })
525 .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
526 yield* iam
527 .deleteRole({ RoleName: roleName })
528 .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
529 }
530 }),
531 });
532 }),
533 );