@relkit/langchain 0.0.0-stage → 0.7.11

package/dist/deepagent-bucket-format.d.ts

@@ -0,0 +1,59 @@
+/** Formats bucket file records into the native DeepAgents listing and content shapes consumed by backend callers. */
+import { Effect } from "effect";
+/** Normalizes paging arguments to nonnegative integers.
+ * @param offset - Candidate starting position.
+ * @param limit - Candidate page size.
+ * @returns An Effect with normalized paging values.
+ * @example Effect.runSync(normalizedPageEffect(0, 500));
+ */
+export declare const normalizedPageEffect: (offset: number, limit: number) => Effect.Effect<{
+    offset: number;
+    limit: number;
+}, never, never>;
+/** Normalizes paging for existing synchronous callers.
+ * @param offset - Candidate starting position.
+ * @param limit - Candidate page size.
+ * @returns Nonnegative integer paging values.
+ * @example normalizedPage(0, 500);
+ */
+export declare function normalizedPage(offset?: number, limit?: number): {
+    offset: number;
+    limit: number;
+};
+/** Classifies cancellation and timeout control failures.
+ * @param cause - Candidate failure.
+ * @returns An Effect with a boolean.
+ * @example Effect.runSync(isControlFailureEffect(error));
+ */
+export declare const isControlFailureEffect: (cause: unknown) => Effect.Effect<boolean, never, never>;
+/** Classifies a control failure for existing synchronous callers.
+ * @param cause - Candidate failure.
+ * @returns Whether it represents cancellation or timeout.
+ * @example isControlFailure(error);
+ */
+export declare function isControlFailure(cause: unknown): boolean;
+/** Reads a failure message without requiring an Error instance.
+ * @param cause - Candidate failure.
+ * @returns An Effect with message text.
+ * @example Effect.runSync(errorMessageEffect(error));
+ */
+export declare const errorMessageEffect: (cause: unknown) => Effect.Effect<string, never, never>;
+/** Reads a failure message for existing synchronous callers.
+ * @param cause - Candidate failure.
+ * @returns Message text.
+ * @example errorMessage(error);
+ */
+export declare function errorMessage(cause: unknown): string;
+/** Checks whether a MIME type should be decoded as text.
+ * @param mimeType - MIME type.
+ * @returns An Effect with a boolean.
+ * @example Effect.runSync(isTextMimeTypeEffect("text/plain"));
+ */
+export declare const isTextMimeTypeEffect: (mimeType: string) => Effect.Effect<boolean, never, never>;
+/** Checks a text MIME type for existing synchronous callers.
+ * @param mimeType - MIME type.
+ * @returns Whether it should be decoded as text.
+ * @example isTextMimeType("text/plain");
+ */
+export declare function isTextMimeType(mimeType: string): boolean;
+//# sourceMappingURL=deepagent-bucket-format.d.ts.map

package/dist/deepagent-bucket-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepagent-bucket-format.d.ts","sourceRoot":"","sources":["../src/deepagent-bucket-format.ts"],"names":[],"mappings":"AAAA,qHAAqH;AAErH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;gBAOhC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,SAAI,EAAE,KAAK,SAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAEzF;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,0DAYlC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAExD;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,yDAG9B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,4DAIhC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD"}

package/dist/deepagent-bucket-format.js

@@ -0,0 +1,72 @@
+/** Formats bucket file records into the native DeepAgents listing and content shapes consumed by backend callers. */
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+const TEXT_MIME_TYPES = new Set(["application/javascript", "application/json", "image/svg+xml"]);
+/** Normalizes paging arguments to nonnegative integers.
+ * @param offset - Candidate starting position.
+ * @param limit - Candidate page size.
+ * @returns An Effect with normalized paging values.
+ * @example Effect.runSync(normalizedPageEffect(0, 500));
+ */
+export const normalizedPageEffect = Effect.fn("Agents.bucket.page")((offset, limit) => Effect.sync(() => ({
+    offset: Number.isFinite(offset) ? Math.max(0, Math.floor(offset)) : 0,
+    limit: Number.isFinite(limit) ? Math.max(0, Math.floor(limit)) : 0,
+})), (effect) => observeAgent("bucket.page", effect));
+/** Normalizes paging for existing synchronous callers.
+ * @param offset - Candidate starting position.
+ * @param limit - Candidate page size.
+ * @returns Nonnegative integer paging values.
+ * @example normalizedPage(0, 500);
+ */
+export function normalizedPage(offset = 0, limit = 500) {
+    return Effect.runSync(normalizedPageEffect(offset, limit));
+}
+/** Classifies cancellation and timeout control failures.
+ * @param cause - Candidate failure.
+ * @returns An Effect with a boolean.
+ * @example Effect.runSync(isControlFailureEffect(error));
+ */
+export const isControlFailureEffect = Effect.fn("Agents.bucket.controlFailure")((cause) => Effect.sync(() => {
+    const value = cause;
+    return (value?.name === "AbortError" ||
+        value?.name === "TimeoutError" ||
+        value?.code === "ABORT_ERR" ||
+        value?.code === "ETIMEDOUT");
+}), (effect) => observeAgent("bucket.control-failure", effect));
+/** Classifies a control failure for existing synchronous callers.
+ * @param cause - Candidate failure.
+ * @returns Whether it represents cancellation or timeout.
+ * @example isControlFailure(error);
+ */
+export function isControlFailure(cause) {
+    return Effect.runSync(isControlFailureEffect(cause));
+}
+/** Reads a failure message without requiring an Error instance.
+ * @param cause - Candidate failure.
+ * @returns An Effect with message text.
+ * @example Effect.runSync(errorMessageEffect(error));
+ */
+export const errorMessageEffect = Effect.fn("Agents.bucket.errorMessage")((cause) => Effect.sync(() => (cause instanceof Error ? cause.message : String(cause))), (effect) => observeAgent("bucket.error-message", effect));
+/** Reads a failure message for existing synchronous callers.
+ * @param cause - Candidate failure.
+ * @returns Message text.
+ * @example errorMessage(error);
+ */
+export function errorMessage(cause) {
+    return Effect.runSync(errorMessageEffect(cause));
+}
+/** Checks whether a MIME type should be decoded as text.
+ * @param mimeType - MIME type.
+ * @returns An Effect with a boolean.
+ * @example Effect.runSync(isTextMimeTypeEffect("text/plain"));
+ */
+export const isTextMimeTypeEffect = Effect.fn("Agents.bucket.textMimeType")((mimeType) => Effect.sync(() => mimeType.startsWith("text/") || TEXT_MIME_TYPES.has(mimeType)), (effect) => observeAgent("bucket.text-mime-type", effect));
+/** Checks a text MIME type for existing synchronous callers.
+ * @param mimeType - MIME type.
+ * @returns Whether it should be decoded as text.
+ * @example isTextMimeType("text/plain");
+ */
+export function isTextMimeType(mimeType) {
+    return Effect.runSync(isTextMimeTypeEffect(mimeType));
+}
+//# sourceMappingURL=deepagent-bucket-format.js.map

package/dist/deepagent-bucket-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepagent-bucket-format.js","sourceRoot":"","sources":["../src/deepagent-bucket-format.ts"],"names":[],"mappings":"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"}

package/dist/deepagent-bucket-glob.d.ts

@@ -0,0 +1,26 @@
+/** Matches normalized bucket paths against DeepAgents glob patterns so search traverses only the backend's visible file namespace. */
+import type { FileInfo, GlobResult } from "deepagents";
+import { Effect } from "effect";
+import { DeepAgentBucket } from "./deepagent-bucket-service.js";
+import { type DeepAgentBucketContext } from "./deepagent-bucket-files.js";
+/** Finds matching bucket files and orders them by modification time.
+ * @param pattern - Glob pattern relative to the search path.
+ * @param path - Virtual search path.
+ * @returns An Effect with matching files or a tagged bucket failure.
+ * @example Effect.runPromise(Effect.provide(globFilesEffect("*.md"), deepAgentBucketLayer(context)));
+ */
+export declare const globFilesEffect: (pattern: string, path?: any) => Effect.Effect<{
+    files: FileInfo[];
+}, import("./deepagent-bucket-error.js").DeepAgentBucketFailure, DeepAgentBucket>;
+/** Finds files for existing DeepAgents Promise callers.
+ * @param context - Bound bucket client and prefix.
+ * @param pattern - Glob pattern relative to the search path.
+ * @param path - Virtual search path.
+ * @returns Matching files or a legacy error result.
+ * @throws A cancellation or timeout failure from the bucket client.
+ * @example await globFiles(context, "*.md", "/notes");
+ */
+export declare function globFiles(context: DeepAgentBucketContext, pattern: string, path?: string): Promise<GlobResult>;
+/** Validates and normalizes a user glob without changing match semantics. */
+export declare function compileGlob(pattern: string): string;
+//# sourceMappingURL=deepagent-bucket-glob.d.ts.map

package/dist/deepagent-bucket-glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepagent-bucket-glob.d.ts","sourceRoot":"","sources":["../src/deepagent-bucket-glob.ts"],"names":[],"mappings":"AAAA,sIAAsI;AAGtI,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AAGxC,OAAO,EAAE,eAAe,EAAwB,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAKL,KAAK,sBAAsB,EAC5B,MAAM,6BAA6B,CAAC;AAGrC;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;iFAmC3B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,MAAM,EACf,IAAI,SAAM,GACT,OAAO,CAAC,UAAU,CAAC,CAWrB;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAUnD"}

package/dist/deepagent-bucket-glob.js

@@ -0,0 +1,66 @@
+/** Matches normalized bucket paths against DeepAgents glob patterns so search traverses only the backend's visible file namespace. */
+import { matchesGlob } from "node:path";
+import { Effect, Result } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { deepAgentBucketFailure } from "./deepagent-bucket-error.js";
+import { DeepAgentBucket, deepAgentBucketLayer } from "./deepagent-bucket-service.js";
+import { errorMessage, filePath, isControlFailure, virtualPath, } from "./deepagent-bucket-files.js";
+import { infoForEffect, scopedKeysEffect } from "./deepagent-bucket-file-index.js";
+/** Finds matching bucket files and orders them by modification time.
+ * @param pattern - Glob pattern relative to the search path.
+ * @param path - Virtual search path.
+ * @returns An Effect with matching files or a tagged bucket failure.
+ * @example Effect.runPromise(Effect.provide(globFilesEffect("*.md"), deepAgentBucketLayer(context)));
+ */
+export const globFilesEffect = Effect.fn("Agents.bucket.glob")(function* (pattern, path = "/") {
+    const context = yield* DeepAgentBucket;
+    const { glob, base } = yield* Effect.try({
+        try: () => ({ glob: compileGlob(pattern), base: virtualPath(path, true) }),
+        catch: deepAgentBucketFailure,
+    });
+    const keys = yield* scopedKeysEffect(path);
+    const matching = yield* Effect.try({
+        try: () => keys.filter((key) => {
+            const absolute = filePath(context, key);
+            const relative = absolute.startsWith(base)
+                ? absolute.slice(base.length)
+                : absolute.split("/").at(-1);
+            return relative !== "" && matchesGlob(relative, glob);
+        }),
+        catch: deepAgentBucketFailure,
+    });
+    const outcomes = yield* Effect.forEach(matching, (key) => Effect.result(infoForEffect(key)), {
+        concurrency: 8,
+    });
+    const firstFailure = outcomes.find(Result.isFailure);
+    if (firstFailure !== undefined)
+        return yield* Effect.fail(firstFailure.failure);
+    const infos = outcomes.flatMap((outcome) => Result.isSuccess(outcome) && outcome.success !== undefined ? [outcome.success] : []);
+    infos.sort((left, right) => (right.modified_at ?? "").localeCompare(left.modified_at ?? "") ||
+        left.path.localeCompare(right.path));
+    return { files: infos };
+}, (effect) => observeAgent("bucket.glob", effect));
+/** Finds files for existing DeepAgents Promise callers.
+ * @param context - Bound bucket client and prefix.
+ * @param pattern - Glob pattern relative to the search path.
+ * @param path - Virtual search path.
+ * @returns Matching files or a legacy error result.
+ * @throws A cancellation or timeout failure from the bucket client.
+ * @example await globFiles(context, "*.md", "/notes");
+ */
+export function globFiles(context, pattern, path = "/") {
+    return Effect.runPromise(globFilesEffect(pattern, path).pipe(Effect.catchTag("DeepAgentBucketFailure", (failure) => isControlFailure(failure.cause)
+        ? Effect.fail(failure.cause)
+        : Effect.succeed({ error: errorMessage(failure.cause) })), Effect.provide(deepAgentBucketLayer(context))));
+}
+/** Validates and normalizes a user glob without changing match semantics. */
+export function compileGlob(pattern) {
+    if (typeof pattern !== "string" ||
+        pattern.trim() === "" ||
+        pattern.includes("\0") ||
+        pattern.replaceAll("\\", "/").split("/").includes("..")) {
+        throw new TypeError("Glob pattern is invalid");
+    }
+    return pattern.startsWith("/") ? pattern.slice(1) : pattern;
+}
+//# sourceMappingURL=deepagent-bucket-glob.js.map

package/dist/deepagent-bucket-glob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepagent-bucket-glob.js","sourceRoot":"","sources":["../src/deepagent-bucket-glob.ts"],"names":[],"mappings":"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"}

package/dist/deepagent-bucket-grep.d.ts

@@ -0,0 +1,32 @@
+/** Searches bucket file content for native grep requests and projects matching lines into DeepAgents results. */
+import type { GrepResult } from "deepagents";
+import { Effect } from "effect";
+import { DeepAgentBucket } from "./deepagent-bucket-service.js";
+import { type DeepAgentBucketContext } from "./deepagent-bucket-files.js";
+/** Searches text files in key order and stops as soon as the match cap is exceeded.
+ * @param pattern - Literal text to find in each line.
+ * @param path - Optional virtual search path.
+ * @param globPattern - Optional filename glob.
+ * @param maxCount - Optional maximum returned matches.
+ * @returns An Effect with matches or a tagged bucket failure.
+ * @example Effect.runPromise(Effect.provide(grepFilesEffect("TODO"), deepAgentBucketLayer(context)));
+ */
+export declare const grepFilesEffect: (pattern: string, path?: string | null | undefined, globPattern?: string | null | undefined, maxCount?: number | null | undefined) => Effect.Effect<{
+    matches: import("deepagents").GrepMatch[];
+    truncated: boolean;
+} | {
+    matches: import("deepagents").GrepMatch[];
+    truncated?: never;
+}, import("./deepagent-bucket-error.js").DeepAgentBucketFailure, DeepAgentBucket>;
+/** Searches text files for existing DeepAgents Promise callers.
+ * @param context - Bound bucket client and prefix.
+ * @param pattern - Literal text to find.
+ * @param path - Optional virtual search path.
+ * @param globPattern - Optional filename glob.
+ * @param maxCount - Optional maximum returned matches.
+ * @returns Matches or a legacy error result.
+ * @throws A cancellation or timeout failure from the bucket client.
+ * @example await grepFiles(context, "TODO", "/notes", "*.md", 10);
+ */
+export declare function grepFiles(context: DeepAgentBucketContext, pattern: string, path?: string | null, globPattern?: string | null, maxCount?: number | null): Promise<GrepResult>;
+//# sourceMappingURL=deepagent-bucket-grep.d.ts.map

package/dist/deepagent-bucket-grep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepagent-bucket-grep.d.ts","sourceRoot":"","sources":["../src/deepagent-bucket-grep.ts"],"names":[],"mappings":"AAAA,iHAAiH;AAGjH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,EAAE,eAAe,EAAwB,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAKL,KAAK,sBAAsB,EAC5B,MAAM,6BAA6B,CAAC;AAKrC;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;;;iFA6C3B,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,GAAG,IAAW,EAC1B,WAAW,GAAE,MAAM,GAAG,IAAW,EACjC,QAAQ,GAAE,MAAM,GAAG,IAAW,GAC7B,OAAO,CAAC,UAAU,CAAC,CAWrB"}

package/dist/deepagent-bucket-grep.js

@@ -0,0 +1,73 @@
+/** Searches bucket file content for native grep requests and projects matching lines into DeepAgents results. */
+import { matchesGlob } from "node:path";
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { deepAgentBucketFailure } from "./deepagent-bucket-error.js";
+import { DeepAgentBucket, deepAgentBucketLayer } from "./deepagent-bucket-service.js";
+import { errorMessage, filePath, isControlFailure, isTextMimeType, } from "./deepagent-bucket-files.js";
+import { readFileDataEffect } from "./deepagent-bucket-file-data.js";
+import { scopedKeysEffect } from "./deepagent-bucket-file-index.js";
+import { compileGlob } from "./deepagent-bucket-glob.js";
+/** Searches text files in key order and stops as soon as the match cap is exceeded.
+ * @param pattern - Literal text to find in each line.
+ * @param path - Optional virtual search path.
+ * @param globPattern - Optional filename glob.
+ * @param maxCount - Optional maximum returned matches.
+ * @returns An Effect with matches or a tagged bucket failure.
+ * @example Effect.runPromise(Effect.provide(grepFilesEffect("TODO"), deepAgentBucketLayer(context)));
+ */
+export const grepFilesEffect = Effect.fn("Agents.bucket.grep")(function* (pattern, path = null, globPattern = null, maxCount = null) {
+    const context = yield* DeepAgentBucket;
+    const glob = yield* Effect.try({
+        try: () => {
+            if (typeof pattern !== "string")
+                throw new TypeError("Grep pattern must be a string");
+            return globPattern === null ? undefined : compileGlob(globPattern);
+        },
+        catch: deepAgentBucketFailure,
+    });
+    const keys = yield* scopedKeysEffect(path);
+    const cap = maxCount === null || !Number.isFinite(maxCount)
+        ? Number.POSITIVE_INFINITY
+        : Math.max(0, Math.floor(maxCount));
+    const matches = [];
+    for (const key of keys) {
+        const absolute = yield* Effect.try({
+            try: () => filePath(context, key),
+            catch: deepAgentBucketFailure,
+        });
+        const name = absolute.split("/").at(-1);
+        if (glob !== undefined && !matchesGlob(name, glob))
+            continue;
+        const data = yield* readFileDataEffect(absolute);
+        if (data === undefined ||
+            !isTextMimeType(data.mimeType) ||
+            typeof data.content !== "string") {
+            continue;
+        }
+        for (const [index, text] of data.content.split("\n").entries()) {
+            if (!text.includes(pattern))
+                continue;
+            matches.push({ path: absolute, line: index + 1, text });
+            if (matches.length > cap)
+                return { matches: matches.slice(0, cap), truncated: true };
+        }
+    }
+    return { matches };
+}, (effect) => observeAgent("bucket.grep", effect));
+/** Searches text files for existing DeepAgents Promise callers.
+ * @param context - Bound bucket client and prefix.
+ * @param pattern - Literal text to find.
+ * @param path - Optional virtual search path.
+ * @param globPattern - Optional filename glob.
+ * @param maxCount - Optional maximum returned matches.
+ * @returns Matches or a legacy error result.
+ * @throws A cancellation or timeout failure from the bucket client.
+ * @example await grepFiles(context, "TODO", "/notes", "*.md", 10);
+ */
+export function grepFiles(context, pattern, path = null, globPattern = null, maxCount = null) {
+    return Effect.runPromise(grepFilesEffect(pattern, path, globPattern, maxCount).pipe(Effect.catchTag("DeepAgentBucketFailure", (failure) => isControlFailure(failure.cause)
+        ? Effect.fail(failure.cause)
+        : Effect.succeed({ error: errorMessage(failure.cause) })), Effect.provide(deepAgentBucketLayer(context))));
+}
+//# sourceMappingURL=deepagent-bucket-grep.js.map

package/dist/deepagent-bucket-grep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepagent-bucket-grep.js","sourceRoot":"","sources":["../src/deepagent-bucket-grep.ts"],"names":[],"mappings":"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"}

package/dist/deepagent-bucket-path.d.ts

@@ -0,0 +1,67 @@
+/** Normalizes native file paths into scoped bucket keys and rejects paths that would escape the configured backend prefix. */
+import { Effect } from "effect";
+import type { DeepAgentBucketClient, DeepAgentBucketContext } from "./deepagent-bucket-files.types.js";
+/** Validates a bucket client and creates its private prefix context.
+ * @param bucket - RELKIT bucket client.
+ * @param prefix - Backend prefix.
+ * @returns An Effect with context or DeepAgentBucketFailure.
+ * @example Effect.runSync(createBucketContextEffect(bucket));
+ */
+export declare const createBucketContextEffect: (bucket: DeepAgentBucketClient, prefix?: any) => Effect.Effect<Readonly<{
+    bucket: DeepAgentBucketClient;
+    prefix: string;
+}>, import("./deepagent-bucket-error.js").DeepAgentBucketFailure, never>;
+/** Creates a bucket context for existing synchronous callers.
+ * @param bucket - RELKIT bucket client.
+ * @param prefix - Backend prefix.
+ * @returns Frozen bucket context.
+ * @throws The original invalid bucket or prefix error.
+ * @example createBucketContext(bucket, "agents");
+ */
+export declare function createBucketContext(bucket: DeepAgentBucketClient, prefix?: string): DeepAgentBucketContext;
+/** Normalizes a virtual backend path and rejects traversal.
+ * @param value - Candidate virtual path.
+ * @param directory - Whether to retain a trailing slash.
+ * @returns An Effect with a normalized path or DeepAgentBucketFailure.
+ * @example Effect.runSync(virtualPathEffect("/docs/readme.md"));
+ */
+export declare const virtualPathEffect: (value: string, directory?: any) => Effect.Effect<string, import("./deepagent-bucket-error.js").DeepAgentBucketFailure, never>;
+/** Normalizes a virtual path for existing synchronous callers.
+ * @param value - Candidate virtual path.
+ * @param directory - Whether to retain a trailing slash.
+ * @returns Normalized absolute virtual path.
+ * @throws Error for empty, unsafe, or traversing paths.
+ * @example virtualPath("docs/readme.md");
+ */
+export declare function virtualPath(value: string, directory?: boolean): string;
+/** Converts a virtual path to its bucket key.
+ * @param context - Private bucket context.
+ * @param path - Virtual file path.
+ * @returns An Effect with a bucket key or DeepAgentBucketFailure.
+ * @example Effect.runSync(bucketKeyEffect(context, "/readme.md"));
+ */
+export declare const bucketKeyEffect: (context: DeepAgentBucketContext, path: string) => Effect.Effect<string, import("./deepagent-bucket-error.js").DeepAgentBucketFailure, never>;
+/** Converts a virtual path to a bucket key for synchronous callers.
+ * @param context - Private bucket context.
+ * @param path - Virtual file path.
+ * @returns Prefixed bucket key.
+ * @throws The original invalid path error.
+ * @example bucketKey(context, "/readme.md");
+ */
+export declare function bucketKey(context: DeepAgentBucketContext, path: string): string;
+/** Converts a scoped bucket key to a virtual path.
+ * @param context - Private bucket context.
+ * @param key - Bucket key.
+ * @returns An Effect with a virtual path or DeepAgentBucketFailure.
+ * @example Effect.runSync(filePathEffect(context, "agents/readme.md"));
+ */
+export declare const filePathEffect: (context: DeepAgentBucketContext, key: string) => Effect.Effect<string, import("./deepagent-bucket-error.js").DeepAgentBucketFailure, never>;
+/** Converts a scoped bucket key for existing synchronous callers.
+ * @param context - Private bucket context.
+ * @param key - Bucket key.
+ * @returns Virtual file path.
+ * @throws Error for a key outside the context prefix.
+ * @example filePath(context, "agents/readme.md");
+ */
+export declare function filePath(context: DeepAgentBucketContext, key: string): string;
+//# sourceMappingURL=deepagent-bucket-path.d.ts.map

package/dist/deepagent-bucket-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepagent-bucket-path.d.ts","sourceRoot":"","sources":["../src/deepagent-bucket-path.ts"],"names":[],"mappings":"AAAA,8HAA8H;AAE9H,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,mCAAmC,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;wEAUrC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,qBAAqB,EAC7B,MAAM,SAAe,GACpB,sBAAsB,CAMxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,gIAI7B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,MAAM,CAMpE;AAcD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,+IAO3B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,sBAAsB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM/E;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,8IAW1B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM7E"}

package/dist/deepagent-bucket-path.js

@@ -0,0 +1,121 @@
+/** Normalizes native file paths into scoped bucket keys and rejects paths that would escape the configured backend prefix. */
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { deepAgentBucketFailure } from "./deepagent-bucket-error.js";
+/** Validates a bucket client and creates its private prefix context.
+ * @param bucket - RELKIT bucket client.
+ * @param prefix - Backend prefix.
+ * @returns An Effect with context or DeepAgentBucketFailure.
+ * @example Effect.runSync(createBucketContextEffect(bucket));
+ */
+export const createBucketContextEffect = Effect.fn("Agents.bucket.context")((bucket, prefix = "deepagents") => Effect.try({
+    try: () => {
+        assertBucketClient(bucket);
+        return Object.freeze({ bucket, prefix: normalizeKeyPrefix(prefix) });
+    },
+    catch: deepAgentBucketFailure,
+}), (effect) => observeAgent("bucket.context", effect));
+/** Creates a bucket context for existing synchronous callers.
+ * @param bucket - RELKIT bucket client.
+ * @param prefix - Backend prefix.
+ * @returns Frozen bucket context.
+ * @throws The original invalid bucket or prefix error.
+ * @example createBucketContext(bucket, "agents");
+ */
+export function createBucketContext(bucket, prefix = "deepagents") {
+    return Effect.runSync(createBucketContextEffect(bucket, prefix).pipe(Effect.catchTag("DeepAgentBucketFailure", (failure) => Effect.fail(failure.cause))));
+}
+/** Normalizes a virtual backend path and rejects traversal.
+ * @param value - Candidate virtual path.
+ * @param directory - Whether to retain a trailing slash.
+ * @returns An Effect with a normalized path or DeepAgentBucketFailure.
+ * @example Effect.runSync(virtualPathEffect("/docs/readme.md"));
+ */
+export const virtualPathEffect = Effect.fn("Agents.bucket.virtualPath")((value, directory = false) => Effect.try({ try: () => virtualPathCore(value, directory), catch: deepAgentBucketFailure }), (effect) => observeAgent("bucket.virtual-path", effect));
+/** Normalizes a virtual path for existing synchronous callers.
+ * @param value - Candidate virtual path.
+ * @param directory - Whether to retain a trailing slash.
+ * @returns Normalized absolute virtual path.
+ * @throws Error for empty, unsafe, or traversing paths.
+ * @example virtualPath("docs/readme.md");
+ */
+export function virtualPath(value, directory = false) {
+    return Effect.runSync(virtualPathEffect(value, directory).pipe(Effect.catchTag("DeepAgentBucketFailure", (failure) => Effect.fail(failure.cause))));
+}
+function virtualPathCore(value, directory = false) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new Error("Path cannot be empty");
+    if (value.includes("\0") || value.startsWith("~") || /^[A-Za-z]:/.test(value)) {
+        throw new Error(`Invalid virtual path: ${value}`);
+    }
+    const parts = value.replaceAll("\\", "/").split("/");
+    if (parts.includes(".."))
+        throw new Error(`Path traversal not allowed: ${value}`);
+    const clean = parts.filter((part) => part !== "" && part !== ".");
+    if (!directory && clean.length === 0)
+        throw new Error("File path cannot be root");
+    return `/${clean.join("/")}${directory && clean.length > 0 ? "/" : ""}`;
+}
+/** Converts a virtual path to its bucket key.
+ * @param context - Private bucket context.
+ * @param path - Virtual file path.
+ * @returns An Effect with a bucket key or DeepAgentBucketFailure.
+ * @example Effect.runSync(bucketKeyEffect(context, "/readme.md"));
+ */
+export const bucketKeyEffect = Effect.fn("Agents.bucket.key")((context, path) => Effect.try({
+    try: () => `${context.prefix}/${virtualPathCore(path).slice(1)}`,
+    catch: deepAgentBucketFailure,
+}), (effect) => observeAgent("bucket.key", effect));
+/** Converts a virtual path to a bucket key for synchronous callers.
+ * @param context - Private bucket context.
+ * @param path - Virtual file path.
+ * @returns Prefixed bucket key.
+ * @throws The original invalid path error.
+ * @example bucketKey(context, "/readme.md");
+ */
+export function bucketKey(context, path) {
+    return Effect.runSync(bucketKeyEffect(context, path).pipe(Effect.catchTag("DeepAgentBucketFailure", (failure) => Effect.fail(failure.cause))));
+}
+/** Converts a scoped bucket key to a virtual path.
+ * @param context - Private bucket context.
+ * @param key - Bucket key.
+ * @returns An Effect with a virtual path or DeepAgentBucketFailure.
+ * @example Effect.runSync(filePathEffect(context, "agents/readme.md"));
+ */
+export const filePathEffect = Effect.fn("Agents.bucket.filePath")((context, key) => Effect.try({
+    try: () => {
+        const prefix = `${context.prefix}/`;
+        if (!key.startsWith(prefix))
+            throw new Error("Bucket key is outside the backend prefix");
+        return `/${key.slice(prefix.length)}`;
+    },
+    catch: deepAgentBucketFailure,
+}), (effect) => observeAgent("bucket.file-path", effect));
+/** Converts a scoped bucket key for existing synchronous callers.
+ * @param context - Private bucket context.
+ * @param key - Bucket key.
+ * @returns Virtual file path.
+ * @throws Error for a key outside the context prefix.
+ * @example filePath(context, "agents/readme.md");
+ */
+export function filePath(context, key) {
+    return Effect.runSync(filePathEffect(context, key).pipe(Effect.catchTag("DeepAgentBucketFailure", (failure) => Effect.fail(failure.cause))));
+}
+function normalizeKeyPrefix(value) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new TypeError("Backend prefix is required");
+    const normalized = virtualPathCore(value).slice(1);
+    if (normalized.startsWith(".relkit") || normalized.startsWith("__relkit")) {
+        throw new TypeError("Backend prefix is reserved");
+    }
+    return normalized;
+}
+function assertBucketClient(value) {
+    const client = value;
+    for (const operation of ["put", "get", "head", "delete", "exists", "list"]) {
+        if (typeof client?.[operation] !== "function") {
+            throw new TypeError("DeepAgents bucket backend requires a RELKIT BucketClient");
+        }
+    }
+}
+//# sourceMappingURL=deepagent-bucket-path.js.map

package/dist/deepagent-bucket-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepagent-bucket-path.js","sourceRoot":"","sources":["../src/deepagent-bucket-path.ts"],"names":[],"mappings":"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"}

package/dist/deepagent-bucket-read.d.ts

@@ -0,0 +1,65 @@
+/** Reads normalized native files from the selected bucket, applying the backend's content and missing-file conventions. */
+import type { ReadRawResult, ReadResult } from "deepagents";
+import { Effect } from "effect";
+import { DeepAgentBucket } from "./deepagent-bucket-service.js";
+import type { DeepAgentBucketContext } from "./deepagent-bucket-files.types.js";
+/** Reads the full file payload from the current bucket service.
+ * @param path - Virtual file path.
+ * @returns An Effect with raw data or a tagged bucket failure.
+ * @example Effect.runPromise(Effect.provide(readBucketRawEffect("/a.md"), deepAgentBucketLayer(context)));
+ */
+export declare const readBucketRawEffect: (path: string) => Effect.Effect<{
+    error: string;
+    data?: never;
+} | {
+    data: {
+        content: string | Uint8Array<ArrayBufferLike>;
+        mimeType: string;
+        created_at: string;
+        modified_at: string;
+    };
+    error?: never;
+}, import("./deepagent-bucket-error.js").DeepAgentBucketFailure, DeepAgentBucket>;
+/** Reads the full file payload for existing DeepAgents Promise callers.
+ * @param context - Bound bucket client and prefix.
+ * @param path - Virtual file path.
+ * @returns Raw data or a legacy error result.
+ * @throws A cancellation or timeout failure from the bucket client.
+ * @example await readBucketRaw(context, "/a.md");
+ */
+export declare function readBucketRaw(context: DeepAgentBucketContext, path: string): Promise<ReadRawResult>;
+/** Reads a paged text file or an unmodified binary payload.
+ * @param path - Virtual file path.
+ * @param offset - Zero-based text line offset.
+ * @param limit - Maximum number of text lines.
+ * @returns An Effect with page data or a tagged bucket failure.
+ * @example Effect.runPromise(Effect.provide(readBucketEffect("/a.md", 0, 50), deepAgentBucketLayer(context)));
+ */
+export declare const readBucketEffect: (path: string, offset?: any, limit?: any) => Effect.Effect<{
+    error: string;
+    content?: never;
+    mimeType?: never;
+} | {
+    content: string | Uint8Array<ArrayBufferLike>;
+    mimeType: string;
+    error?: never;
+} | {
+    nextOffset?: number;
+    content: string;
+    mimeType: string;
+    totalLines: number;
+    startLine: number;
+    endLine: number;
+    error?: never;
+}, import("./deepagent-bucket-error.js").DeepAgentBucketFailure, DeepAgentBucket>;
+/** Reads a file for existing DeepAgents Promise callers.
+ * @param context - Bound bucket client and prefix.
+ * @param path - Virtual file path.
+ * @param offset - Zero-based text line offset.
+ * @param limit - Maximum number of text lines.
+ * @returns A text page, binary content, or legacy error result.
+ * @throws A cancellation or timeout failure from the bucket client.
+ * @example await readBucket(context, "/a.md", 0, 50);
+ */
+export declare function readBucket(context: DeepAgentBucketContext, path: string, offset?: number, limit?: number): Promise<ReadResult>;
+//# sourceMappingURL=deepagent-bucket-read.d.ts.map