@smthrs/std 0.0.0-stage → 1.0.0-rc.4

package/dist/cjs/ExaWebSearch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The Exa provider for the `websearch` flow.
+ *
+ * {@link layer} binds `WebSearch.WebSearch` to the Exa search API. It reads the
+ * API key from a named credential on every search, calls Exa through the
+ * permission-checked `HttpClient`, and maps each hit onto `WebSearch.Result`.
+ *
+ * @since 1.0.0
+ */
+import * as Credential from "@smthrs/control/Credential";
+import * as HttpClient from "@smthrs/kernel/HttpClient";
+import { Layer } from "effect";
+import * as WebSearch from "./WebSearch.ts";
+/**
+ * Provides {@link WebSearch.WebSearch} backed by the Exa API, reading its
+ * key from the named credential.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layer: (credentialId: string) => Layer.Layer<WebSearch.WebSearch, never, Credential.Credential | HttpClient.HttpClient>;
+//# sourceMappingURL=ExaWebSearch.d.ts.map

package/dist/cjs/ExaWebSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExaWebSearch.d.ts","sourceRoot":"","sources":["../../src/ExaWebSearch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,UAAU,MAAM,4BAA4B,CAAA;AACxD,OAAO,KAAK,UAAU,MAAM,2BAA2B,CAAA;AACvD,OAAO,EAAiB,KAAK,EAAoB,MAAM,QAAQ,CAAA;AAI/D,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAsB3C;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAChB,cAAc,MAAM,KACnB,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,GAAG,UAAU,CAAC,UAAU,CAiGrF,CAAA"}

package/dist/cjs/ExaWebSearch.js

@@ -0,0 +1,138 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ExaWebSearch_exports = {};
+__export(ExaWebSearch_exports, {
+  layer: () => layer
+});
+module.exports = __toCommonJS(ExaWebSearch_exports);
+var Credential = __toESM(require("@smthrs/control/Credential"), 1);
+var HttpClient = __toESM(require("@smthrs/kernel/HttpClient"), 1);
+var import_effect = require("effect");
+var HttpClientRequest = __toESM(require("effect/unstable/http/HttpClientRequest"), 1);
+var import_Http = require("./internal/Http.js");
+var StdError = __toESM(require("./StdError.js"), 1);
+var WebSearch = __toESM(require("./WebSearch.js"), 1);
+const maxResults = 20;
+const requestTimeoutMs = 3e4;
+const ExaResult = import_effect.Schema.Struct({
+  title: import_effect.Schema.optional(import_effect.Schema.String),
+  url: import_effect.Schema.String,
+  text: import_effect.Schema.optional(import_effect.Schema.String),
+  publishedDate: import_effect.Schema.optional(import_effect.Schema.String)
+});
+const ExaResponse = import_effect.Schema.Struct({
+  results: import_effect.Schema.Array(ExaResult)
+});
+const freshnessDays = {
+  day: 1,
+  week: 7,
+  month: 31,
+  year: 365
+};
+const failure = (code, message) => new StdError.StdError({ code, message });
+const layer = (credentialId) => import_effect.Layer.effect(
+  WebSearch.WebSearch,
+  import_effect.Effect.gen(function* () {
+    const credentials = yield* Credential.Credential;
+    const http = yield* HttpClient.HttpClient;
+    return WebSearch.make({
+      search: (input) => import_effect.Effect.gen(function* () {
+        const reference = yield* credentials.get(credentialId).pipe(import_effect.Effect.mapError(
+          () => new StdError.StdError({
+            code: "provider_unavailable",
+            message: "Configured Exa credential is unavailable"
+          })
+        ));
+        const secret = yield* credentials.resolve(reference).pipe(import_effect.Effect.mapError(
+          () => new StdError.StdError({
+            code: "provider_unavailable",
+            message: "Configured Exa credential cannot be resolved"
+          })
+        ));
+        const now = yield* import_effect.Clock.currentTimeMillis;
+        const request = HttpClientRequest.setHeaders(
+          HttpClientRequest.bodyJsonUnsafe(HttpClientRequest.post("https://api.exa.ai/search"), {
+            query: input.query,
+            numResults: Math.min(input.numResults ?? 8, maxResults),
+            ...input.freshness === void 0 ? {} : { startPublishedDate: new Date(now - freshnessDays[input.freshness] * 864e5).toISOString() }
+          }),
+          { "authorization": `Bearer ${import_effect.Redacted.value(secret)}`, "content-type": "application/json" }
+        );
+        const response = yield* http.execute(request).pipe(
+          import_effect.Effect.timeout(requestTimeoutMs),
+          import_effect.Effect.mapError(
+            (error) => error._tag === "TimeoutError" ? failure("timeout", "Exa search request timed out") : failure("request_failed", "Exa search request failed")
+          )
+        );
+        const retryAfter = (0, import_Http.header)(response.headers, "retry-after");
+        const refused = response.status < 200 || response.status >= 300;
+        if (response.status === 429 || refused && retryAfter !== void 0) {
+          const delay = retryAfter === void 0 ? NaN : /^\d+$/.test(retryAfter.trim()) ? Number(retryAfter) : Math.max(0, Math.ceil((Date.parse(retryAfter) - (yield* import_effect.Clock.currentTimeMillis)) / 1e3));
+          return yield* import_effect.Effect.fail(
+            failure(
+              "rate_limited",
+              Number.isFinite(delay) ? `Exa search was throttled; retry after ${delay} seconds` : "Exa search was throttled"
+            )
+          );
+        }
+        if (response.status === 401 || response.status === 403) {
+          return yield* import_effect.Effect.fail(failure("provider_unavailable", "Exa search authentication was rejected"));
+        }
+        if (response.status >= 500) {
+          return yield* import_effect.Effect.fail(failure("provider_unavailable", `Exa search returned ${response.status}`));
+        }
+        if (response.status < 200 || response.status >= 300) {
+          return yield* import_effect.Effect.fail(failure("request_failed", `Exa search returned ${response.status}`));
+        }
+        const bytes = yield* (0, import_Http.readBounded)(response.stream, "https://api.exa.ai/search").pipe(
+          import_effect.Effect.timeout(requestTimeoutMs),
+          import_effect.Effect.mapError(
+            (error) => error._tag === "TimeoutError" ? failure("timeout", "Exa search response timed out") : error instanceof StdError.StdError && error.code === "response_too_large" ? failure("response_too_large", "Exa search response exceeds the 5 MiB limit") : failure("request_failed", "Exa search response was invalid")
+          )
+        );
+        const body = yield* import_effect.Schema.decodeUnknownEffect(import_effect.Schema.fromJsonString(ExaResponse))(
+          new TextDecoder().decode(bytes)
+        ).pipe(
+          import_effect.Effect.mapError(
+            () => new StdError.StdError({ code: "request_failed", message: "Exa search response was invalid" })
+          )
+        );
+        return {
+          results: body.results.slice(0, Math.min(input.numResults ?? 8, maxResults)).map((result) => ({
+            title: result.title ?? result.url,
+            url: result.url,
+            snippet: (result.text ?? "").slice(0, 2e3),
+            ...result.publishedDate === void 0 ? {} : { publishedAt: result.publishedDate }
+          }))
+        };
+      })
+    });
+  })
+);
+//# sourceMappingURL=ExaWebSearch.js.map

package/dist/cjs/ExaWebSearch.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ExaWebSearch.ts"],
+  "sourcesContent": ["/**\n * The Exa provider for the `websearch` flow.\n *\n * {@link layer} binds `WebSearch.WebSearch` to the Exa search API. It reads the\n * API key from a named credential on every search, calls Exa through the\n * permission-checked `HttpClient`, and maps each hit onto `WebSearch.Result`.\n *\n * @since 1.0.0\n */\n\nimport * as Credential from \"@smthrs/control/Credential\"\nimport * as HttpClient from \"@smthrs/kernel/HttpClient\"\nimport { Clock, Effect, Layer, Redacted, Schema } from \"effect\"\nimport * as HttpClientRequest from \"effect/unstable/http/HttpClientRequest\"\nimport { header, readBounded } from \"./internal/Http.ts\"\nimport * as StdError from \"./StdError.ts\"\nimport * as WebSearch from \"./WebSearch.ts\"\n\nconst maxResults = 20\nconst requestTimeoutMs = 30_000\nconst ExaResult = Schema.Struct({\n  title: Schema.optional(Schema.String),\n  url: Schema.String,\n  text: Schema.optional(Schema.String),\n  publishedDate: Schema.optional(Schema.String)\n})\nconst ExaResponse = Schema.Struct({\n  results: Schema.Array(ExaResult)\n})\nconst freshnessDays = {\n  day: 1,\n  week: 7,\n  month: 31,\n  year: 365\n} as const\n\nconst failure = (code: StdError.Code, message: string): StdError.StdError => new StdError.StdError({ code, message })\n\n/**\n * Provides {@link WebSearch.WebSearch} backed by the Exa API, reading its\n * key from the named credential.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layer = (\n  credentialId: string\n): Layer.Layer<WebSearch.WebSearch, never, Credential.Credential | HttpClient.HttpClient> =>\n  Layer.effect(\n    WebSearch.WebSearch,\n    Effect.gen(function*() {\n      const credentials = yield* Credential.Credential\n      const http = yield* HttpClient.HttpClient\n      return WebSearch.make({\n        search: (input): Effect.Effect<typeof WebSearch.Output.Type, StdError.StdError> =>\n          Effect.gen(function*() {\n            const reference = yield* credentials.get(credentialId).pipe(Effect.mapError(() =>\n              new StdError.StdError({\n                code: \"provider_unavailable\",\n                message: \"Configured Exa credential is unavailable\"\n              })\n            ))\n            const secret = yield* credentials.resolve(reference).pipe(Effect.mapError(() =>\n              new StdError.StdError({\n                code: \"provider_unavailable\",\n                message: \"Configured Exa credential cannot be resolved\"\n              })\n            ))\n            const now = yield* Clock.currentTimeMillis\n            const request = HttpClientRequest.setHeaders(\n              HttpClientRequest.bodyJsonUnsafe(HttpClientRequest.post(\"https://api.exa.ai/search\"), {\n                query: input.query,\n                numResults: Math.min(input.numResults ?? 8, maxResults),\n                ...(input.freshness === undefined\n                  ? {}\n                  : { startPublishedDate: new Date(now - freshnessDays[input.freshness] * 86_400_000).toISOString() })\n              }),\n              { \"authorization\": `Bearer ${Redacted.value(secret)}`, \"content-type\": \"application/json\" }\n            )\n            const response = yield* http.execute(request).pipe(\n              Effect.timeout(requestTimeoutMs),\n              Effect.mapError((error) =>\n                error._tag === \"TimeoutError\"\n                  ? failure(\"timeout\", \"Exa search request timed out\")\n                  : failure(\"request_failed\", \"Exa search request failed\")\n              )\n            )\n            const retryAfter = header(response.headers, \"retry-after\")\n            // Successful responses may carry pacing advice too; status decides refusal.\n            const refused = response.status < 200 || response.status >= 300\n            if (response.status === 429 || (refused && retryAfter !== undefined)) {\n              const delay = retryAfter === undefined\n                ? NaN\n                : /^\\d+$/.test(retryAfter.trim())\n                ? Number(retryAfter)\n                : Math.max(0, Math.ceil((Date.parse(retryAfter) - (yield* Clock.currentTimeMillis)) / 1_000))\n              return yield* Effect.fail(\n                failure(\n                  \"rate_limited\",\n                  Number.isFinite(delay)\n                    ? `Exa search was throttled; retry after ${delay} seconds`\n                    : \"Exa search was throttled\"\n                )\n              )\n            }\n            if (response.status === 401 || response.status === 403) {\n              return yield* Effect.fail(failure(\"provider_unavailable\", \"Exa search authentication was rejected\"))\n            }\n            if (response.status >= 500) {\n              return yield* Effect.fail(failure(\"provider_unavailable\", `Exa search returned ${response.status}`))\n            }\n            if (response.status < 200 || response.status >= 300) {\n              return yield* Effect.fail(failure(\"request_failed\", `Exa search returned ${response.status}`))\n            }\n            // Bound the body before decoding: an endpoint must not choose how\n            // much of it the host buffers.\n            const bytes = yield* readBounded(response.stream, \"https://api.exa.ai/search\").pipe(\n              Effect.timeout(requestTimeoutMs),\n              Effect.mapError((error) =>\n                error._tag === \"TimeoutError\"\n                  ? failure(\"timeout\", \"Exa search response timed out\")\n                  : error instanceof StdError.StdError && error.code === \"response_too_large\"\n                  ? failure(\"response_too_large\", \"Exa search response exceeds the 5 MiB limit\")\n                  : failure(\"request_failed\", \"Exa search response was invalid\")\n              )\n            )\n            const body = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(ExaResponse))(\n              new TextDecoder().decode(bytes)\n            ).pipe(\n              Effect.mapError(() =>\n                new StdError.StdError({ code: \"request_failed\", message: \"Exa search response was invalid\" })\n              )\n            )\n            return {\n              results: body.results.slice(0, Math.min(input.numResults ?? 8, maxResults)).map((result) => ({\n                title: result.title ?? result.url,\n                url: result.url,\n                snippet: (result.text ?? \"\").slice(0, 2_000),\n                ...(result.publishedDate === undefined ? {} : { publishedAt: result.publishedDate })\n              }))\n            }\n          })\n      })\n    })\n  )\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/Explore.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Read-only workspace reconnaissance as a dynamic flow.
+ *
+ * @since 1.0.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * Registry name for the explore flow.
+ *
+ * @category metadata
+ * @since 1.0.0
+ */
+export declare const name: "explore";
+/**
+ * Model-facing description of the explore flow.
+ *
+ * @category metadata
+ * @since 1.0.0
+ */
+export declare const description = "Investigate the workspace read-only, cite every finding as file:line, report evidence only, and never propose edits.";
+/**
+ * Input accepted by the explore flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Struct<{
+    readonly prompt: Schema.String;
+}>;
+/**
+ * Decoded input accepted by the `explore` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type;
+/**
+ * Output returned by the explore flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Output: Schema.Struct<{
+    readonly findings: Schema.String;
+}>;
+/**
+ * Decoded output returned by the `explore` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type;
+/**
+ * Static effect envelope for read-only workspace reconnaissance.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Narrows the explore effect declaration for one decoded input.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effectsFor: (_input: typeof Input.Type) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * Transitive capabilities of the read-only flows available to explore.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: ReadonlyArray<string>;
+/**
+ * Constructs an explore flow, optionally pinned to a model.
+ *
+ * Model selection remains optional so the invoking seat can inject its model.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: (options: {
+    readonly model?: string | undefined;
+}) => {
+    readonly name: "explore";
+    readonly description: "Investigate the workspace read-only, cite every finding as file:line, report evidence only, and never propose edits.";
+    readonly input: Schema.Struct<{
+        readonly prompt: Schema.String;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly findings: Schema.String;
+    }>;
+    readonly model: string | undefined;
+    readonly flows: readonly [{
+        readonly name: "read";
+        readonly description: "Read a text file by 1-based offset and limit. content is RAW file text with no line-number prefixes, so any line of it is an edit anchor as it stands; the numbers are startLine/endLine.";
+        readonly input: Schema.Struct<{
+            readonly path: Schema.String;
+            readonly offset: Schema.optional<Schema.Int>;
+            readonly limit: Schema.optional<Schema.Int>;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly content: Schema.String;
+            readonly startLine: Schema.Number;
+            readonly endLine: Schema.Number;
+            readonly totalLines: Schema.Number;
+            readonly truncated: Schema.Boolean;
+            readonly notice: Schema.optional<Schema.String>;
+        }>;
+        readonly capabilities: string[];
+        readonly effects: import("@smthrs/plan/Effects").Declaration;
+    }, {
+        readonly name: "ls";
+        readonly description: "List a directory with directories first, trailing /, and locale-independent UTF-16 code-unit ordering; use 1-based offset and limit to page large listings.";
+        readonly input: Schema.Struct<{
+            readonly path: Schema.String;
+            readonly offset: Schema.optional<Schema.Int>;
+            readonly limit: Schema.optional<Schema.Int>;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly entries: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly kind: Schema.Literals<readonly ["file", "directory"]>;
+            }>>;
+            readonly total: Schema.Number;
+            readonly truncated: Schema.Boolean;
+            readonly notice: Schema.optional<Schema.String>;
+        }>;
+        readonly capabilities: string[];
+        readonly effects: import("@smthrs/plan/Effects").Declaration;
+    }, {
+        readonly name: "glob";
+        readonly description: "Find files through the Smithers Ripgrep Subset v1 contract.";
+        readonly input: Schema.Struct<{
+            readonly pattern: Schema.NonEmptyString;
+            readonly root: Schema.optional<Schema.String>;
+            readonly hidden: Schema.optional<Schema.Boolean>;
+            readonly noIgnore: Schema.optional<Schema.Boolean>;
+            readonly limit: Schema.optional<Schema.Int>;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly paths: Schema.$Array<Schema.String>;
+            readonly total: Schema.Int;
+            readonly truncated: Schema.Boolean;
+            readonly notice: Schema.optional<Schema.String>;
+        }>;
+        readonly capabilities: string[];
+        readonly effects: import("@smthrs/plan/Effects").Declaration;
+    }, {
+        readonly name: "grep";
+        readonly description: "Search file contents through the Smithers Ripgrep Subset v1 contract. limit counts matches, each carrying its own context and enclosing definition; fixedStrings searches a literal, and one is retried.";
+        readonly input: Schema.Struct<{
+            readonly pattern: Schema.String;
+            readonly root: Schema.optional<Schema.String>;
+            readonly fixedStrings: Schema.optional<Schema.Boolean>;
+            readonly ignoreCase: Schema.optional<Schema.Boolean>;
+            readonly smartCase: Schema.optional<Schema.Boolean>;
+            readonly globs: Schema.optional<Schema.$Array<Schema.String>>;
+            readonly beforeContext: Schema.optional<Schema.Int>;
+            readonly afterContext: Schema.optional<Schema.Int>;
+            readonly context: Schema.optional<Schema.Int>;
+            readonly maxCount: Schema.optional<Schema.Int>;
+            readonly filesWithMatches: Schema.optional<Schema.Boolean>;
+            readonly hidden: Schema.optional<Schema.Boolean>;
+            readonly symbols: Schema.optional<Schema.Boolean>;
+            readonly noIgnore: Schema.optional<Schema.Boolean>;
+            readonly limit: Schema.optional<Schema.Int>;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly matches: Schema.$Array<Schema.Struct<{
+                readonly file: Schema.String;
+                readonly line: Schema.Int;
+                readonly text: Schema.String;
+                readonly before: Schema.$Array<Schema.Struct<{
+                    readonly line: Schema.Int;
+                    readonly text: Schema.String;
+                }>>;
+                readonly after: Schema.$Array<Schema.Struct<{
+                    readonly line: Schema.Int;
+                    readonly text: Schema.String;
+                }>>;
+                readonly symbol: Schema.optional<Schema.Struct<{
+                    readonly kind: Schema.String;
+                    readonly name: Schema.String;
+                    readonly startLine: Schema.Int;
+                    readonly endLine: Schema.Int;
+                }>>;
+            }>>;
+            readonly files: Schema.$Array<Schema.String>;
+            readonly filesSearched: Schema.Int;
+            readonly skippedBinary: Schema.Int;
+            readonly truncated: Schema.Boolean;
+            readonly retriedAsLiteral: Schema.optional<Schema.Boolean>;
+            readonly notice: Schema.optional<Schema.String>;
+        }>;
+        readonly capabilities: string[];
+        readonly effects: import("@smthrs/plan/Effects").Declaration;
+    }];
+    readonly prompt: "Investigate the workspace read-only, cite every finding as file:line, report evidence only, and never propose edits.";
+    readonly capabilities: readonly string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+/**
+ * Default explore declaration with seat-selected model injection.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "explore";
+    readonly description: "Investigate the workspace read-only, cite every finding as file:line, report evidence only, and never propose edits.";
+    readonly input: Schema.Struct<{
+        readonly prompt: Schema.String;
+    }>;
+    readonly output: Schema.Struct<{
+        readonly findings: Schema.String;
+    }>;
+    readonly model: string | undefined;
+    readonly flows: readonly [{
+        readonly name: "read";
+        readonly description: "Read a text file by 1-based offset and limit. content is RAW file text with no line-number prefixes, so any line of it is an edit anchor as it stands; the numbers are startLine/endLine.";
+        readonly input: Schema.Struct<{
+            readonly path: Schema.String;
+            readonly offset: Schema.optional<Schema.Int>;
+            readonly limit: Schema.optional<Schema.Int>;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly content: Schema.String;
+            readonly startLine: Schema.Number;
+            readonly endLine: Schema.Number;
+            readonly totalLines: Schema.Number;
+            readonly truncated: Schema.Boolean;
+            readonly notice: Schema.optional<Schema.String>;
+        }>;
+        readonly capabilities: string[];
+        readonly effects: import("@smthrs/plan/Effects").Declaration;
+    }, {
+        readonly name: "ls";
+        readonly description: "List a directory with directories first, trailing /, and locale-independent UTF-16 code-unit ordering; use 1-based offset and limit to page large listings.";
+        readonly input: Schema.Struct<{
+            readonly path: Schema.String;
+            readonly offset: Schema.optional<Schema.Int>;
+            readonly limit: Schema.optional<Schema.Int>;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly entries: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly kind: Schema.Literals<readonly ["file", "directory"]>;
+            }>>;
+            readonly total: Schema.Number;
+            readonly truncated: Schema.Boolean;
+            readonly notice: Schema.optional<Schema.String>;
+        }>;
+        readonly capabilities: string[];
+        readonly effects: import("@smthrs/plan/Effects").Declaration;
+    }, {
+        readonly name: "glob";
+        readonly description: "Find files through the Smithers Ripgrep Subset v1 contract.";
+        readonly input: Schema.Struct<{
+            readonly pattern: Schema.NonEmptyString;
+            readonly root: Schema.optional<Schema.String>;
+            readonly hidden: Schema.optional<Schema.Boolean>;
+            readonly noIgnore: Schema.optional<Schema.Boolean>;
+            readonly limit: Schema.optional<Schema.Int>;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly paths: Schema.$Array<Schema.String>;
+            readonly total: Schema.Int;
+            readonly truncated: Schema.Boolean;
+            readonly notice: Schema.optional<Schema.String>;
+        }>;
+        readonly capabilities: string[];
+        readonly effects: import("@smthrs/plan/Effects").Declaration;
+    }, {
+        readonly name: "grep";
+        readonly description: "Search file contents through the Smithers Ripgrep Subset v1 contract. limit counts matches, each carrying its own context and enclosing definition; fixedStrings searches a literal, and one is retried.";
+        readonly input: Schema.Struct<{
+            readonly pattern: Schema.String;
+            readonly root: Schema.optional<Schema.String>;
+            readonly fixedStrings: Schema.optional<Schema.Boolean>;
+            readonly ignoreCase: Schema.optional<Schema.Boolean>;
+            readonly smartCase: Schema.optional<Schema.Boolean>;
+            readonly globs: Schema.optional<Schema.$Array<Schema.String>>;
+            readonly beforeContext: Schema.optional<Schema.Int>;
+            readonly afterContext: Schema.optional<Schema.Int>;
+            readonly context: Schema.optional<Schema.Int>;
+            readonly maxCount: Schema.optional<Schema.Int>;
+            readonly filesWithMatches: Schema.optional<Schema.Boolean>;
+            readonly hidden: Schema.optional<Schema.Boolean>;
+            readonly symbols: Schema.optional<Schema.Boolean>;
+            readonly noIgnore: Schema.optional<Schema.Boolean>;
+            readonly limit: Schema.optional<Schema.Int>;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly matches: Schema.$Array<Schema.Struct<{
+                readonly file: Schema.String;
+                readonly line: Schema.Int;
+                readonly text: Schema.String;
+                readonly before: Schema.$Array<Schema.Struct<{
+                    readonly line: Schema.Int;
+                    readonly text: Schema.String;
+                }>>;
+                readonly after: Schema.$Array<Schema.Struct<{
+                    readonly line: Schema.Int;
+                    readonly text: Schema.String;
+                }>>;
+                readonly symbol: Schema.optional<Schema.Struct<{
+                    readonly kind: Schema.String;
+                    readonly name: Schema.String;
+                    readonly startLine: Schema.Int;
+                    readonly endLine: Schema.Int;
+                }>>;
+            }>>;
+            readonly files: Schema.$Array<Schema.String>;
+            readonly filesSearched: Schema.Int;
+            readonly skippedBinary: Schema.Int;
+            readonly truncated: Schema.Boolean;
+            readonly retriedAsLiteral: Schema.optional<Schema.Boolean>;
+            readonly notice: Schema.optional<Schema.String>;
+        }>;
+        readonly capabilities: string[];
+        readonly effects: import("@smthrs/plan/Effects").Declaration;
+    }];
+    readonly prompt: "Investigate the workspace read-only, cite every finding as file:line, report evidence only, and never propose edits.";
+    readonly capabilities: readonly string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+//# sourceMappingURL=Explore.d.ts.map

package/dist/cjs/Explore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Explore.d.ts","sourceRoot":"","sources":["../../src/Explore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAOvC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,EAAG,SAAkB,CAAA;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,yHACgG,CAAA;AAExH;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;EAIhB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;EAIjB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,4CAKlB,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,OAAO,KAAK,CAAC,IAAI,+CAAY,CAAA;AAWhE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,MAAM,CAE9C,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAUU,CAAA;AAEX;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAW,CAAA"}

package/dist/cjs/Explore.js

@@ -0,0 +1,90 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name2 in all)
+    __defProp(target, name2, { get: all[name2], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Explore_exports = {};
+__export(Explore_exports, {
+  Input: () => Input,
+  Output: () => Output,
+  capabilities: () => capabilities,
+  description: () => description,
+  effects: () => effects,
+  effectsFor: () => effectsFor,
+  flow: () => flow,
+  make: () => make,
+  name: () => name
+});
+module.exports = __toCommonJS(Explore_exports);
+var Schema = __toESM(require("effect/Schema"), 1);
+var Glob = __toESM(require("./Glob.js"), 1);
+var Grep = __toESM(require("./Grep.js"), 1);
+var import_Declaration = require("./internal/Declaration.js");
+var Ls = __toESM(require("./Ls.js"), 1);
+var Read = __toESM(require("./Read.js"), 1);
+const name = "explore";
+const description = "Investigate the workspace read-only, cite every finding as file:line, report evidence only, and never propose edits.";
+const Input = Schema.Struct({
+  prompt: Schema.String.annotate({
+    description: "The workspace question to investigate."
+  })
+});
+const Output = Schema.Struct({
+  findings: Schema.String.annotate({
+    description: "Evidence-backed findings with file:line citations."
+  })
+});
+const effects = (0, import_Declaration.envelope)({
+  tier: "sealed",
+  mode: "hermetic",
+  reads: ["/**"],
+  writes: []
+});
+const effectsFor = (_input) => effects;
+const flows = Object.freeze(
+  [
+    Read.flow,
+    Ls.flow,
+    Glob.flow,
+    Grep.flow
+  ]
+);
+const capabilities = Object.freeze(
+  [...new Set(flows.flatMap((flow2) => flow2.capabilities))].sort()
+);
+const make = (options) => ({
+  name,
+  description,
+  input: Input,
+  output: Output,
+  model: options.model,
+  flows,
+  prompt: description,
+  capabilities,
+  effects
+});
+const flow = make({});
+//# sourceMappingURL=Explore.js.map

package/dist/cjs/Explore.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Explore.ts"],
+  "sourcesContent": ["/**\n * Read-only workspace reconnaissance as a dynamic flow.\n *\n * @since 1.0.0\n */\n\nimport * as Schema from \"effect/Schema\"\nimport * as Glob from \"./Glob.ts\"\nimport * as Grep from \"./Grep.ts\"\nimport { envelope } from \"./internal/Declaration.ts\"\nimport * as Ls from \"./Ls.ts\"\nimport * as Read from \"./Read.ts\"\n\n/**\n * Registry name for the explore flow.\n *\n * @category metadata\n * @since 1.0.0\n */\nexport const name = \"explore\" as const\n\n/**\n * Model-facing description of the explore flow.\n *\n * @category metadata\n * @since 1.0.0\n */\nexport const description =\n  \"Investigate the workspace read-only, cite every finding as file:line, report evidence only, and never propose edits.\"\n\n/**\n * Input accepted by the explore flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Input = Schema.Struct({\n  prompt: Schema.String.annotate({\n    description: \"The workspace question to investigate.\"\n  })\n})\n\n/**\n * Decoded input accepted by the `explore` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Input = typeof Input.Type\n\n/**\n * Output returned by the explore flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Output = Schema.Struct({\n  findings: Schema.String.annotate({\n    description: \"Evidence-backed findings with file:line citations.\"\n  })\n})\n\n/**\n * Decoded output returned by the `explore` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Output = typeof Output.Type\n\n/**\n * Static effect envelope for read-only workspace reconnaissance.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effects = envelope({\n  tier: \"sealed\",\n  mode: \"hermetic\",\n  reads: [\"/**\"],\n  writes: []\n})\n\n/**\n * Narrows the explore effect declaration for one decoded input.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effectsFor = (_input: typeof Input.Type) => effects\n\nconst flows = Object.freeze(\n  [\n    Read.flow,\n    Ls.flow,\n    Glob.flow,\n    Grep.flow\n  ] as const\n)\n\n/**\n * Transitive capabilities of the read-only flows available to explore.\n *\n * @category capabilities\n * @since 1.0.0\n */\nexport const capabilities: ReadonlyArray<string> = Object.freeze(\n  [...new Set(flows.flatMap((flow) => flow.capabilities))].sort()\n)\n\n/**\n * Constructs an explore flow, optionally pinned to a model.\n *\n * Model selection remains optional so the invoking seat can inject its model.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const make = (options: {\n  readonly model?: string | undefined\n}) => ({\n  name,\n  description,\n  input: Input,\n  output: Output,\n  model: options.model,\n  flows,\n  prompt: description,\n  capabilities,\n  effects\n} as const)\n\n/**\n * Default explore declaration with seat-selected model injection.\n *\n * @category flows\n * @since 1.0.0\n */\nexport const flow = make({})\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,aAAwB;AACxB,WAAsB;AACtB,WAAsB;AACtB,yBAAyB;AACzB,SAAoB;AACpB,WAAsB;AAQf,MAAM,OAAO;AAQb,MAAM,cACX;AAQK,MAAM,QAAQ,OAAO,OAAO;AAAA,EACjC,QAAQ,OAAO,OAAO,SAAS;AAAA,IAC7B,aAAa;AAAA,EACf,CAAC;AACH,CAAC;AAgBM,MAAM,SAAS,OAAO,OAAO;AAAA,EAClC,UAAU,OAAO,OAAO,SAAS;AAAA,IAC/B,aAAa;AAAA,EACf,CAAC;AACH,CAAC;AAgBM,MAAM,cAAU,6BAAS;AAAA,EAC9B,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO,CAAC,KAAK;AAAA,EACb,QAAQ,CAAC;AACX,CAAC;AAQM,MAAM,aAAa,CAAC,WAA8B;AAEzD,MAAM,QAAQ,OAAO;AAAA,EACnB;AAAA,IACE,KAAK;AAAA,IACL,GAAG;AAAA,IACH,KAAK;AAAA,IACL,KAAK;AAAA,EACP;AACF;AAQO,MAAM,eAAsC,OAAO;AAAA,EACxD,CAAC,GAAG,IAAI,IAAI,MAAM,QAAQ,CAACA,UAASA,MAAK,YAAY,CAAC,CAAC,EAAE,KAAK;AAChE;AAUO,MAAM,OAAO,CAAC,aAEd;AAAA,EACL;AAAA,EACA;AAAA,EACA,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,OAAO,QAAQ;AAAA,EACf;AAAA,EACA,QAAQ;AAAA,EACR;AAAA,EACA;AACF;AAQO,MAAM,OAAO,KAAK,CAAC,CAAC;",
+  "names": ["flow"]
+}