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

package/src/ExaWebSearch.ts

@@ -0,0 +1,145 @@
+/**
+ * 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 { Clock, Effect, Layer, Redacted, Schema } from "effect"
+import * as HttpClientRequest from "effect/http/HttpClientRequest"
+import { header, readBounded } from "./internal/Http.ts"
+import * as StdError from "./StdError.ts"
+import * as WebSearch from "./WebSearch.ts"
+
+const maxResults = 20
+const requestTimeoutMs = 30_000
+const ExaResult = Schema.Struct({
+  title: Schema.optional(Schema.String),
+  url: Schema.String,
+  text: Schema.optional(Schema.String),
+  publishedDate: Schema.optional(Schema.String)
+})
+const ExaResponse = Schema.Struct({
+  results: Schema.Array(ExaResult)
+})
+const freshnessDays = {
+  day: 1,
+  week: 7,
+  month: 31,
+  year: 365
+} as const
+
+const failure = (code: StdError.Code, message: string): StdError.StdError => new StdError.StdError({ code, message })
+
+/**
+ * Provides {@link WebSearch.WebSearch} backed by the Exa API, reading its
+ * key from the named credential.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer = (
+  credentialId: string
+): Layer.Layer<WebSearch.WebSearch, never, Credential.Credential | HttpClient.HttpClient> =>
+  Layer.effect(
+    WebSearch.WebSearch,
+    Effect.gen(function*() {
+      const credentials = yield* Credential.Credential
+      const http = yield* HttpClient.HttpClient
+      return WebSearch.make({
+        search: (input): Effect.Effect<typeof WebSearch.Output.Type, StdError.StdError> =>
+          Effect.gen(function*() {
+            const reference = yield* credentials.get(credentialId).pipe(Effect.mapError(() =>
+              new StdError.StdError({
+                code: "provider_unavailable",
+                message: "Configured Exa credential is unavailable"
+              })
+            ))
+            const secret = yield* credentials.resolve(reference).pipe(Effect.mapError(() =>
+              new StdError.StdError({
+                code: "provider_unavailable",
+                message: "Configured Exa credential cannot be resolved"
+              })
+            ))
+            const now = yield* 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 === undefined
+                  ? {}
+                  : { startPublishedDate: new Date(now - freshnessDays[input.freshness] * 86_400_000).toISOString() })
+              }),
+              { "authorization": `Bearer ${Redacted.value(secret)}`, "content-type": "application/json" }
+            )
+            const response = yield* http.execute(request).pipe(
+              Effect.timeout(requestTimeoutMs),
+              Effect.mapError((error) =>
+                error._tag === "TimeoutError"
+                  ? failure("timeout", "Exa search request timed out")
+                  : failure("request_failed", "Exa search request failed")
+              )
+            )
+            const retryAfter = header(response.headers, "retry-after")
+            // Successful responses may carry pacing advice too; status decides refusal.
+            const refused = response.status < 200 || response.status >= 300
+            if (response.status === 429 || (refused && retryAfter !== undefined)) {
+              const delay = retryAfter === undefined
+                ? NaN
+                : /^\d+$/.test(retryAfter.trim())
+                ? Number(retryAfter)
+                : Math.max(0, Math.ceil((Date.parse(retryAfter) - (yield* Clock.currentTimeMillis)) / 1_000))
+              return yield* 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* Effect.fail(failure("provider_unavailable", "Exa search authentication was rejected"))
+            }
+            if (response.status >= 500) {
+              return yield* Effect.fail(failure("provider_unavailable", `Exa search returned ${response.status}`))
+            }
+            if (response.status < 200 || response.status >= 300) {
+              return yield* Effect.fail(failure("request_failed", `Exa search returned ${response.status}`))
+            }
+            // Bound the body before decoding: an endpoint must not choose how
+            // much of it the host buffers.
+            const bytes = yield* readBounded(response.stream, "https://api.exa.ai/search").pipe(
+              Effect.timeout(requestTimeoutMs),
+              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* Schema.decodeUnknownEffect(Schema.fromJsonString(ExaResponse))(
+              new TextDecoder().decode(bytes)
+            ).pipe(
+              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, 2_000),
+                ...(result.publishedDate === undefined ? {} : { publishedAt: result.publishedDate })
+              }))
+            }
+          })
+      })
+    })
+  )

package/src/Explore.ts

@@ -0,0 +1,139 @@
+/**
+ * Read-only workspace reconnaissance as a dynamic flow.
+ *
+ * @since 1.0.0
+ */
+
+import * as Schema from "effect/Schema"
+import * as Glob from "./Glob.ts"
+import * as Grep from "./Grep.ts"
+import { envelope } from "./internal/Declaration.ts"
+import * as Ls from "./Ls.ts"
+import * as Read from "./Read.ts"
+
+/**
+ * Registry name for the explore flow.
+ *
+ * @category metadata
+ * @since 1.0.0
+ */
+export const name = "explore" as const
+
+/**
+ * Model-facing description of the explore flow.
+ *
+ * @category metadata
+ * @since 1.0.0
+ */
+export 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 const Input = Schema.Struct({
+  prompt: Schema.String.annotate({
+    description: "The workspace question to investigate."
+  })
+})
+
+/**
+ * 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 const Output = Schema.Struct({
+  findings: Schema.String.annotate({
+    description: "Evidence-backed findings with file:line citations."
+  })
+})
+
+/**
+ * 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 const effects = envelope({
+  tier: "sealed",
+  mode: "hermetic",
+  reads: ["/**"],
+  writes: []
+})
+
+/**
+ * Narrows the explore effect declaration for one decoded input.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (_input: typeof Input.Type) => effects
+
+const flows = Object.freeze(
+  [
+    Read.flow,
+    Ls.flow,
+    Glob.flow,
+    Grep.flow
+  ] as const
+)
+
+/**
+ * Transitive capabilities of the read-only flows available to explore.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities: ReadonlyArray<string> = Object.freeze(
+  [...new Set(flows.flatMap((flow) => flow.capabilities))].sort()
+)
+
+/**
+ * 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 const make = (options: {
+  readonly model?: string | undefined
+}) => ({
+  name,
+  description,
+  input: Input,
+  output: Output,
+  model: options.model,
+  flows,
+  prompt: description,
+  capabilities,
+  effects
+} as const)
+
+/**
+ * Default explore declaration with seat-selected model injection.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = make({})

package/src/Fetch.ts

@@ -0,0 +1,117 @@
+/**
+ * HTTP GET flow declaration and portable handler.
+ *
+ * @since 1.0.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as HttpClientRequest from "effect/http/HttpClientRequest"
+import * as Schema from "effect/Schema"
+import { capability, envelope } from "./internal/Declaration.ts"
+import { execute, Response, Timeout } from "./internal/Http.ts"
+
+/**
+ * Registry name for the fetch flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "fetch"
+
+/**
+ * Model-facing description of the fetch flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export const description =
+  "Get an absolute URL and return its status and text body; long bodies are truncated with a notice. Use http-post to send data."
+
+/**
+ * Input schema for the fetch flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Input = Schema.Struct({
+  url: Schema.String.annotate({ description: "Absolute http or https URL to retrieve" }),
+  headers: Schema.optional(Schema.Record(Schema.String, Schema.String)).annotate({
+    description: "Additional request headers"
+  }),
+  timeout: Schema.optional(Timeout).annotate({
+    description: "Total request and response body timeout in seconds; defaults to 30, capped at 120"
+  })
+})
+
+/**
+ * Decoded input accepted by the `fetch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type
+
+/**
+ * Output schema for the fetch flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Output = Response
+
+/**
+ * Decoded output returned by the `fetch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type
+
+/**
+ * Static effect envelope for the fetch flow.
+ *
+ * A retrieval leaves no durable state behind, so it is sealed even though it
+ * leaves the machine.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "sealed", mode: "expected", reads: [], writes: [] })
+
+/**
+ * Narrows the fetch effect envelope for one decoded input.
+ *
+ * Network reach is expressed as a capability rather than a path envelope, so
+ * a retrieval has nothing left to narrow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (_input: typeof Input.Type) => effects
+
+/**
+ * Capabilities required by the fetch flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("net:get", "*")]
+
+/**
+ * Declaration-only fetch flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects } as const
+
+/**
+ * Retrieves a URL through the permission-aware kernel HTTP client.
+ *
+ * Error statuses are ordinary results; only transport, permission, and body
+ * decoding failures use the typed error channel.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("Fetch.run")((input: Input) => execute(input, HttpClientRequest.get))

package/src/Glob.ts

@@ -0,0 +1,200 @@
+/**
+ * The `glob` projection of Smithers Ripgrep Subset v1.
+ *
+ * It has the same two peer implementations as `grep` and supports the
+ * `rg --files -g` pattern subset: `*`, `**`, `?`, and brace alternatives;
+ * results are path sorted; hidden files are opt-in; root and nested .gitignore
+ * files apply by default (even outside git repositories). `noIgnore: true` opts
+ * out. Parent/global ignore files, .git/info/exclude, .ignore and .rgignore
+ * are not read. Caller globs filter the remaining files without overriding
+ * ignores. An explicitly named ignored or skipped directory is still searched.
+ *
+ * **Patterns are relative to `root`, never to the filesystem.** A candidate is
+ * matched by the path it has *relative to the search root*, so `tests/**\/*.py`
+ * — what every caller writing a project-relative pattern means — matches
+ * `<root>/tests/admin_views/admin.py`. Three rules follow, and both peers
+ * implement all three identically:
+ *
+ * - A pattern with no `/` matches the **basename** at any depth: `*.py` finds
+ *   every Python file in the subtree.
+ * - A pattern containing `/` is matched against the root-relative path and is
+ *   anchored at the root: `tests/*.py` matches `<root>/tests/a.py` and not
+ *   `<root>/src/tests/a.py`.
+ * - A leading `/` is the same anchor spelled explicitly, not a filesystem
+ *   absolute path: `/a.py` matches only `<root>/a.py`, where bare `a.py` would
+ *   match any `a.py` in the subtree. A leading `./` means the same anchor.
+ *
+ * `**` crosses directory boundaries, `*` and `?` stay inside one segment, and
+ * `?` consumes one UTF-8 byte. Trailing spaces are not part of a pattern:
+ * `rg` reads `-g` by gitignore's rules and drops them, so `"a.ts "` finds
+ * `a.ts`, and a pattern left blank by that is rejected rather than read as no
+ * filter at all.
+ *
+ * A `root` that names one file is that file. It is reported whatever the
+ * pattern says, because `rg` searches a path given on its command line without
+ * consulting `-g`, and a walk that reaches one file has nothing to filter.
+ *
+ * A walk skips what it cannot read — a dangling symlink, a link cycle, a
+ * directory the process may not list — and reports everything it did reach.
+ * One unreadable entry never fails the call.
+ *
+ * The consequence worth stating is the one that cost a SWE-bench run 41 of its
+ * 43 frames: an *absolute* pattern such as `/home/repo/tests/**` is read as the
+ * root-relative path `home/repo/tests/**`, which nothing under a root of
+ * `/home/repo` can match. That answer is now never silent — a pattern no file
+ * under the root could match reports why through `notice`, so "unsatisfiable"
+ * and "searched and found none" stay distinguishable.
+ *
+ * @since 1.0.0
+ */
+
+import { Effect, Schema } from "effect"
+import { capability, envelope, rootSubtree } from "./internal/Declaration.ts"
+import { MAX_ENTRIES } from "./internal/Text.ts"
+import * as Search from "./Search.ts"
+import * as Contract from "./SearchContract.ts"
+import type * as StdError from "./StdError.ts"
+
+/**
+ * The registry name for glob.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "glob"
+/**
+ * The model-facing glob description.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export const description = "Find files through the Smithers Ripgrep Subset v1 contract."
+/**
+ * Input accepted by {@link flow} and {@link run}.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Input = Schema.Struct({
+  pattern: Schema.NonEmptyString.annotate({
+    description:
+      "Ripgrep -g pattern, matched against paths relative to root, never absolute paths: *, ?, {a,b} stay inside one segment, ** crosses directories, a pattern without / matches any basename, and a leading / anchors at root."
+  }),
+  root: Schema.optional(Schema.String).annotate({
+    description: "Search root the pattern is relative to; defaults to . (the host workspace)."
+  }),
+  hidden: Schema.optional(Schema.Boolean).annotate({ description: "Ripgrep --hidden." }),
+  noIgnore: Schema.optional(Schema.Boolean).annotate({
+    description:
+      "Honor root-scoped .gitignore files by default. Set true to include ignored paths; hidden and fixed directory skips still apply."
+  }),
+  limit: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))).annotate({
+    description: `Maximum paths, capped at ${MAX_ENTRIES}.`
+  })
+})
+/**
+ * Decoded input accepted by the `glob` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type
+/**
+ * Output produced by {@link run}.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Output = Schema.Struct({
+  paths: Schema.Array(Schema.String),
+  total: Schema.Int,
+  truncated: Schema.Boolean,
+  notice: Schema.optional(Schema.String)
+})
+/**
+ * Decoded output returned by the `glob` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type
+/**
+ * Conservative sealed declaration for all workspace files.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "sealed", mode: "hermetic", reads: ["/**"], writes: [] })
+/**
+ * Narrows the read declaration to the requested root subtree.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (input: { readonly root?: string | undefined }) =>
+  envelope({ tier: "sealed", mode: "hermetic", reads: [rootSubtree(input.root ?? ".")], writes: [] })
+/**
+ * Capability strings requested by glob.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("fs:read", "/**")]
+/**
+ * Declaration-only glob flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects } as const
+
+/**
+ * What a call to this flow does, for a reader of a run.
+ *
+ * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the
+ * governing vocabulary and `StandardFlows` binds this value onto the flow's
+ * descriptor, where the binding site checks it. `declarationDigest` excludes
+ * it, so declaring it cannot invalidate a call identity or a cached prompt.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export const activity = "reads" as const
+
+/**
+ * How one recorded call to this flow reads: the verb for each settlement, the
+ * input field that is its subject, and the measured output fields a one-line
+ * summary may count.
+ *
+ * Display metadata only, governed by `@smthrs/registry`
+ * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export const presentation = {
+  verb: { pending: "listing", success: "listed", failure: "failed to list" },
+  subject: "pattern",
+  result: "paths"
+} as const
+
+/**
+ * Runs one `rg --files -g` contract call through the selected peer implementation.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("Glob.run")(function*(
+  input: typeof Input.Type
+): Effect.fn.Return<typeof Output.Type, StdError.StdError, Search.Search> {
+  const patternError = Contract.validateGlob(input.pattern)
+  if (patternError !== undefined) return yield* Effect.fail(patternError)
+  const search = yield* Search.Search
+  return yield* search.glob({
+    pattern: input.pattern,
+    root: input.root ?? ".",
+    hidden: input.hidden ?? false,
+    noIgnore: input.noIgnore ?? false,
+    limit: Math.min(input.limit ?? MAX_ENTRIES, MAX_ENTRIES)
+  })
+})