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

main
ts 251 lines 9.32 KB
Raw
1 import * as bedrock from "@distilled.cloud/aws/bedrock-agent";
2 import { isResolved } from "alchemy/Diff";
3 import { createPhysicalName } from "alchemy/PhysicalName";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Effect from "effect/Effect";
7 import * as Schedule from "effect/Schedule";
8
9 /**
10 * The connector configuration for a data source. Passed through to the
11 * Bedrock API unchanged — see the AWS SDK `DataSourceConfiguration` shape.
12 * The common case is a `S3` type with `s3Configuration.bucketArn` set.
13 */
14 export type DataSourceConfiguration = bedrock.DataSourceConfiguration;
15
16 /**
17 * Controls document chunking, parsing, and custom transformation before
18 * embedding. Passed through unchanged — see the AWS SDK
19 * `VectorIngestionConfiguration` shape.
20 */
21 export type VectorIngestionConfiguration = bedrock.VectorIngestionConfiguration;
22
23 /**
24 * What happens to the vector embeddings when the data source is deleted.
25 * `DELETE` removes them; `RETAIN` leaves them in the vector store.
26 */
27 export type DataDeletionPolicy = "RETAIN" | "DELETE";
28
29 export interface DataSourceProps {
30 /**
31 * The id of the {@link KnowledgeBase} this data source feeds. Accepts a
32 * knowledge base's `knowledgeBaseId` output. Changing the knowledge base
33 * triggers a replacement.
34 */
35 knowledgeBaseId: string;
36 /**
37 * Name of the data source (1-100 characters). If omitted, a deterministic
38 * physical name is generated from the app, stage, and logical ID. Changing
39 * the name triggers a replacement.
40 */
41 name?: string;
42 /**
43 * A description of the data source.
44 */
45 description?: string;
46 /**
47 * The connector configuration (S3 bucket, web crawler, Confluence, ...).
48 */
49 dataSourceConfiguration: DataSourceConfiguration;
50 /**
51 * What happens to vector embeddings when the data source is deleted.
52 * @default "RETAIN"
53 */
54 dataDeletionPolicy?: DataDeletionPolicy;
55 /**
56 * Document chunking / parsing configuration applied before embedding.
57 */
58 vectorIngestionConfiguration?: VectorIngestionConfiguration;
59 }
60
61 export interface DataSource extends Resource<
62 "AWS.Bedrock.DataSource",
63 DataSourceProps,
64 {
65 /**
66 * The unique identifier of the knowledge base the data source belongs to.
67 */
68 knowledgeBaseId: string;
69 /**
70 * The unique identifier of the data source.
71 */
72 dataSourceId: string;
73 /**
74 * Name of the data source.
75 */
76 name: string;
77 }
78 > {}
79
80 /**
81 * A data source attached to an Amazon Bedrock {@link KnowledgeBase} — the
82 * origin of the documents the knowledge base embeds and indexes.
83 *
84 * The most common source is an S3 bucket. After the data source is created,
85 * start an ingestion job (`bedrock-agent:StartIngestionJob`) to crawl the
86 * source, chunk + embed the documents, and write them to the vector store.
87 * Ingestion is not part of the desired-state lifecycle — trigger it whenever
88 * the underlying documents change.
89 *
90 * ### Creating Data Sources
91 * **Example:** S3 Data Source
92 * ```typescript
93 * import * as Bedrock from "@alchemy.run/aws/Bedrock";
94 *
95 * const source = yield* Bedrock.DataSource("docs-bucket", {
96 * knowledgeBaseId: kb.knowledgeBaseId,
97 * dataSourceConfiguration: {
98 * type: "S3",
99 * s3Configuration: { bucketArn: bucket.bucketArn },
100 * },
101 * dataDeletionPolicy: "DELETE",
102 * });
103 * ```
104 *
105 * @resource
106 */
107 export const DataSource = Resource<DataSource>("AWS.Bedrock.DataSource");
108
109 /** Data-source status values indicating an in-flight transition. */
110 const DS_TRANSIENT = new Set(["CREATING", "UPDATING", "DELETING"]);
111
112 /**
113 * A data source rejects deletion with a `ConflictException` while the parent
114 * knowledge base is busy. Bounded retry (~60s), wrapped in an explicitly-typed
115 * helper so the `Effect.retry` return type does not widen the provider layer's
116 * requirement to `unknown` (see PATTERNS §7).
117 */
118 const retryWhileConflict = <A, E extends { _tag: string }, R>(
119 self: Effect.Effect<A, E, R>,
120 ): Effect.Effect<A, E, R> =>
121 Effect.retry(self, {
122 while: (e) => e._tag === "ConflictException",
123 schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]),
124 });
125
126 export const DataSourceProvider = () =>
127 Provider.effect(
128 DataSource,
129 Effect.gen(function* () {
130 const createName = Effect.fn(function* (id: string, props: Pick<DataSourceProps, "name">) {
131 return props.name ?? (yield* createPhysicalName({ id, maxLength: 100 }));
132 });
133
134 const getDsOrUndefined = Effect.fn(function* (knowledgeBaseId: string, dataSourceId: string) {
135 return yield* bedrock.getDataSource({ knowledgeBaseId, dataSourceId }).pipe(
136 Effect.map((r) => r.dataSource),
137 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
138 );
139 });
140
141 const waitForSettled = Effect.fn(function* (knowledgeBaseId: string, dataSourceId: string) {
142 return yield* bedrock.getDataSource({ knowledgeBaseId, dataSourceId }).pipe(
143 Effect.map((r) => r.dataSource),
144 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
145 Effect.repeat({
146 schedule: Schedule.fixed("3 seconds"),
147 until: (ds) => ds === undefined || !DS_TRANSIENT.has(ds.status),
148 times: 40,
149 }),
150 );
151 });
152
153 return DataSource.Provider.of({
154 stables: ["knowledgeBaseId", "dataSourceId", "name"],
155
156 // Data sources are scoped to a parent knowledge base — enumeration
157 // requires the KB id, so this returns empty (the engine keys off state).
158 list: () => Effect.succeed([]),
159
160 read: Effect.fn(function* ({ olds, output }) {
161 const knowledgeBaseId = output?.knowledgeBaseId ?? olds?.knowledgeBaseId;
162 const dataSourceId = output?.dataSourceId;
163 if (knowledgeBaseId === undefined || dataSourceId === undefined) {
164 return undefined;
165 }
166 const ds = yield* getDsOrUndefined(knowledgeBaseId, dataSourceId);
167 if (ds === undefined || ds.status === "DELETING") return undefined;
168 return {
169 knowledgeBaseId: ds.knowledgeBaseId,
170 dataSourceId: ds.dataSourceId,
171 name: ds.name,
172 };
173 }),
174
175 diff: Effect.fn(function* ({ id, news, olds }) {
176 if (!isResolved(news)) return undefined;
177 if ((olds?.knowledgeBaseId ?? undefined) !== (news?.knowledgeBaseId ?? undefined)) {
178 return { action: "replace" } as const;
179 }
180 const oldName = yield* createName(id, olds ?? ({} as DataSourceProps));
181 const newName = yield* createName(id, news ?? ({} as DataSourceProps));
182 if (oldName !== newName) {
183 return { action: "replace" } as const;
184 }
185 // description, config, and deletion policy converge via update.
186 }),
187
188 reconcile: Effect.fn(function* ({ id, news = {} as DataSourceProps, output, session }) {
189 const name = output?.name ?? (yield* createName(id, news));
190 const knowledgeBaseId = news.knowledgeBaseId;
191
192 // 1. OBSERVE
193 let ds = output?.dataSourceId
194 ? yield* getDsOrUndefined(knowledgeBaseId, output.dataSourceId)
195 : undefined;
196
197 if (ds === undefined) {
198 // 2. ENSURE
199 const created = yield* bedrock.createDataSource({
200 knowledgeBaseId,
201 name,
202 description: news.description,
203 dataSourceConfiguration: news.dataSourceConfiguration,
204 dataDeletionPolicy: news.dataDeletionPolicy,
205 vectorIngestionConfiguration: news.vectorIngestionConfiguration,
206 });
207 ds = created.dataSource;
208 ds = (yield* waitForSettled(knowledgeBaseId, ds.dataSourceId)) ?? ds;
209 } else {
210 // 3. SYNC
211 ds = (yield* waitForSettled(knowledgeBaseId, ds.dataSourceId)) ?? ds;
212 const drifted =
213 ds.description !== news.description ||
214 JSON.stringify(ds.dataSourceConfiguration) !==
215 JSON.stringify(news.dataSourceConfiguration) ||
216 (ds.dataDeletionPolicy ?? undefined) !== (news.dataDeletionPolicy ?? undefined) ||
217 JSON.stringify(ds.vectorIngestionConfiguration ?? null) !==
218 JSON.stringify(news.vectorIngestionConfiguration ?? null);
219 if (drifted) {
220 yield* bedrock.updateDataSource({
221 knowledgeBaseId,
222 dataSourceId: ds.dataSourceId,
223 name,
224 description: news.description,
225 dataSourceConfiguration: news.dataSourceConfiguration,
226 dataDeletionPolicy: news.dataDeletionPolicy,
227 vectorIngestionConfiguration: news.vectorIngestionConfiguration,
228 });
229 ds = (yield* waitForSettled(knowledgeBaseId, ds.dataSourceId)) ?? ds;
230 }
231 }
232
233 yield* session.note(ds.dataSourceId);
234 return {
235 knowledgeBaseId,
236 dataSourceId: ds.dataSourceId,
237 name,
238 };
239 }),
240
241 delete: Effect.fn(function* ({ output }) {
242 yield* retryWhileConflict(
243 bedrock.deleteDataSource({
244 knowledgeBaseId: output.knowledgeBaseId,
245 dataSourceId: output.dataSourceId,
246 }),
247 ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
248 }),
249 });
250 }),
251 );