effect-agent 0.1.0-beta.16 → 0.1.0-beta.160

package/src/sandbox/PageCrawl.ts

@@ -0,0 +1,148 @@
+import { Context, Schema, type Scope, type Stream } from "effect";
+
+import { PageCaptureTargetUrl } from "./PageCapture.ts";
+import { SandboxImplementation } from "./Sandbox.ts";
+
+const MAX_PAGE_BYTES = 8 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const MAX_PAGES = 100;
+const MAX_DEPTH = 10;
+const MAX_DEADLINE_MILLIS = 10 * 60_000;
+const MAX_DIAGNOSTIC_LENGTH = 8_000;
+const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0));
+const BoundedMarkdown = Schema.String.check(Schema.isMaxLength(MAX_PAGE_BYTES));
+const BoundedMessage = Schema.String.check(Schema.isMaxLength(MAX_DIAGNOSTIC_LENGTH));
+
+const HttpStatus = Schema.Int.check(
+  Schema.isGreaterThanOrEqualTo(100),
+  Schema.isLessThanOrEqualTo(599),
+);
+
+/** One credential-free HTTPS URL. The first adapter confines every record to its exact host. */
+export const PageCrawlStartUrl = PageCaptureTargetUrl;
+export type PageCrawlStartUrl = typeof PageCrawlStartUrl.Type;
+
+/** The declared uses Cloudflare evaluates against a site's Content Signals. */
+export const PageCrawlPurpose = Schema.Literals(["search", "ai-input", "ai-train"]);
+export type PageCrawlPurpose = typeof PageCrawlPurpose.Type;
+
+/** Immutable caller limits for one scoped crawl. */
+export class PageCrawlLimits extends Schema.Class<PageCrawlLimits>("PageCrawlLimits")({
+  maxPages: PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_PAGES)),
+  maxDepth: PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_DEPTH)),
+  maxPageBytes: PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_PAGE_BYTES)),
+  maxTotalBytes: PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_TOTAL_BYTES)),
+  deadlineMillis: PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_DEADLINE_MILLIS)),
+}) {}
+
+/** A rendered Markdown crawl rooted at one exact HTTPS host. */
+export class PageCrawlRequest extends Schema.Class<PageCrawlRequest>("PageCrawlRequest")({
+  startUrl: PageCrawlStartUrl,
+  purposes: Schema.Array(PageCrawlPurpose).check(
+    Schema.isMinLength(1),
+    Schema.isMaxLength(3),
+    Schema.isUnique(),
+  ),
+  limits: PageCrawlLimits,
+}) {}
+
+/** Cloudflare's documented status for one discovered URL. */
+export const PageCrawlRecordStatus = Schema.Literals([
+  "queued",
+  "completed",
+  "disallowed",
+  "skipped",
+  "errored",
+  "cancelled",
+]);
+
+export type PageCrawlRecordStatus = typeof PageCrawlRecordStatus.Type;
+
+/** Bounded origin metadata when Cloudflare reached the URL. */
+export class PageCrawlRecordMetadata extends Schema.Class<PageCrawlRecordMetadata>(
+  "PageCrawlRecordMetadata",
+)({
+  status: HttpStatus,
+  url: PageCrawlStartUrl,
+  title: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(4_096))),
+}) {}
+
+/** One untrusted page record. Non-completed statuses may have no Markdown. */
+export class PageCrawlRecord extends Schema.Class<PageCrawlRecord>("PageCrawlRecord")({
+  url: PageCrawlStartUrl,
+  status: PageCrawlRecordStatus,
+  markdown: Schema.optionalKey(BoundedMarkdown),
+  metadata: Schema.optionalKey(PageCrawlRecordMetadata),
+}) {}
+
+/** Cloudflare refused a request because of a request-rate or browser-quota limit. */
+export class PageCrawlRateLimitedError extends Schema.TaggedError<PageCrawlRateLimitedError>()(
+  "PageCrawlRateLimitedError",
+  {
+    implementation: SandboxImplementation,
+    reason: Schema.Literals(["rate", "quota"]),
+    retryAfterMillis: Schema.optionalKey(Schema.Natural),
+    message: BoundedMessage,
+    cause: Schema.optionalKey(Schema.Defect()),
+  },
+) {}
+
+/** The REST transport or provider response violated the crawl protocol. */
+export class PageCrawlProtocolError extends Schema.TaggedError<PageCrawlProtocolError>()(
+  "PageCrawlProtocolError",
+  {
+    implementation: SandboxImplementation,
+    message: BoundedMessage,
+    cause: Schema.optionalKey(Schema.Defect()),
+  },
+) {}
+
+/** The first record or operation that crossed one immutable caller limit. */
+export class PageCrawlLimitError extends Schema.TaggedError<PageCrawlLimitError>()(
+  "PageCrawlLimitError",
+  {
+    implementation: SandboxImplementation,
+    limit: Schema.Literals(["pages", "page-bytes", "total-bytes", "deadline"]),
+    maximum: PositiveInt,
+    observed: Schema.Natural,
+    message: BoundedMessage,
+  },
+) {}
+
+/** A documented non-success terminal job status. */
+export class PageCrawlTerminalError extends Schema.TaggedError<PageCrawlTerminalError>()(
+  "PageCrawlTerminalError",
+  {
+    implementation: SandboxImplementation,
+    status: Schema.Literals([
+      "errored",
+      "cancelled_by_user",
+      "cancelled_due_to_timeout",
+      "cancelled_due_to_limits",
+    ]),
+    message: BoundedMessage,
+  },
+) {}
+
+export const PageCrawlError = Schema.Union([
+  PageCrawlRateLimitedError,
+  PageCrawlProtocolError,
+  PageCrawlLimitError,
+  PageCrawlTerminalError,
+]);
+
+export type PageCrawlError = typeof PageCrawlError.Type;
+
+/** Scoped exact-host crawl stream. Provider job identity and polling stay adapter-private. */
+export class PageCrawl extends Context.Service<
+  PageCrawl,
+  {
+    readonly crawl: (
+      request: PageCrawlRequest,
+    ) => Stream.Stream<PageCrawlRecord, PageCrawlError, Scope.Scope>;
+  }
+>()("@effect-agent/sandbox/PageCrawl") {}
+
+export type PageCrawlCrawl = (
+  request: PageCrawlRequest,
+) => Stream.Stream<PageCrawlRecord, PageCrawlError, Scope.Scope>;

package/src/sandbox/PageScreenshot.ts

@@ -0,0 +1,81 @@
+import { Context, Schema, type Effect } from "effect";
+
+import {
+  PageCaptureEngine,
+  PageCaptureNavigationError,
+  PageCaptureProtocolError,
+  PageCaptureRateLimitedError,
+  PageCaptureTarget,
+  PageCaptureUnsupportedError,
+  PageNavigationOptions,
+  PageResourcePolicy,
+  PageViewport,
+} from "./PageCapture.ts";
+import { SandboxImplementation } from "./Sandbox.ts";
+
+const MAX_SCREENSHOT_BYTES = 8 * 1024 * 1024;
+const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0));
+
+/** The byte limit and full-page choice are fixed before Browser Run starts. */
+export class PageScreenshotLimits extends Schema.Class<PageScreenshotLimits>(
+  "PageScreenshotLimits",
+)({
+  maxOutputBytes: PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_SCREENSHOT_BYTES)),
+}) {}
+
+/** Schema-first request for exactly one PNG screenshot. */
+export class PageScreenshotRequest extends Schema.Class<PageScreenshotRequest>(
+  "PageScreenshotRequest",
+)({
+  target: PageCaptureTarget,
+  engine: PageCaptureEngine,
+  limits: PageScreenshotLimits,
+  fullPage: Schema.Boolean,
+  navigation: Schema.optionalKey(PageNavigationOptions),
+  viewport: Schema.optionalKey(PageViewport),
+  resourcePolicy: Schema.optionalKey(PageResourcePolicy),
+}) {}
+
+/** The only successful output: bytes are caller-owned and never durable framework data. */
+export class PageScreenshotResult extends Schema.Class<PageScreenshotResult>(
+  "PageScreenshotResult",
+)({
+  implementation: SandboxImplementation,
+  mediaType: Schema.Literal("image/png"),
+  bytes: Schema.Uint8Array.check(Schema.isMaxLength(MAX_SCREENSHOT_BYTES)),
+}) {}
+
+/** The response crossed the request's PNG byte limit. */
+export class PageScreenshotOutputLimitError extends Schema.TaggedError<PageScreenshotOutputLimitError>()(
+  "PageScreenshotOutputLimitError",
+  {
+    implementation: SandboxImplementation,
+    limit: PositiveInt,
+    observed: Schema.Natural,
+  },
+) {}
+
+/** Expected screenshot failures. The shared capture errors keep identical semantics. */
+export const PageScreenshotError = Schema.Union([
+  PageCaptureRateLimitedError,
+  PageCaptureNavigationError,
+  PageCaptureUnsupportedError,
+  PageCaptureProtocolError,
+  PageScreenshotOutputLimitError,
+]);
+
+export type PageScreenshotError = typeof PageScreenshotError.Type;
+
+/** Stateless, one-output PNG capture port. It owns neither persistence nor later byte handoff. */
+export class PageScreenshot extends Context.Service<
+  PageScreenshot,
+  {
+    readonly capture: (
+      request: PageScreenshotRequest,
+    ) => Effect.Effect<PageScreenshotResult, PageScreenshotError>;
+  }
+>()("@effect-agent/sandbox/PageScreenshot") {}
+
+export type PageScreenshotCapture = (
+  request: PageScreenshotRequest,
+) => Effect.Effect<PageScreenshotResult, PageScreenshotError>;

package/src/sandbox/Sandbox.ts

@@ -0,0 +1,241 @@
+import { Context, Duration, Schema, type Stream } from "effect";
+
+const BoundedName = Schema.NonEmptyString.check(Schema.isMaxLength(256));
+const BoundedPath = Schema.NonEmptyString.check(Schema.isMaxLength(4 * 1024));
+const BoundedArgument = Schema.String.check(Schema.isMaxLength(32 * 1024));
+const MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+const MAX_ARTIFACT_RULES = 64;
+const BoundedOutputText = Schema.String.check(Schema.isMaxLength(MAX_OUTPUT_BYTES));
+
+export const SANDBOX_DIAGNOSTIC_MAX_LENGTH = 8 * 1024;
+const BoundedDiagnostic = Schema.String.check(Schema.isMaxLength(SANDBOX_DIAGNOSTIC_MAX_LENGTH));
+const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0));
+const PositiveNumber = Schema.Finite.check(Schema.isGreaterThan(0));
+const MaxOutputBytes = PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_OUTPUT_BYTES));
+const BoundedArguments = Schema.Array(BoundedArgument).check(Schema.isMaxLength(256));
+const BoundedEnvironmentNames = Schema.Array(BoundedName).check(Schema.isMaxLength(128));
+
+const FinitePositiveDuration = Schema.Duration.pipe(
+  Schema.refine(
+    (duration): duration is Duration.Duration =>
+      Duration.isFinite(duration) && Duration.isPositive(duration),
+    { expected: "a finite positive duration" },
+  ),
+);
+
+const FiniteNonNegativeDuration = Schema.Duration.pipe(
+  Schema.refine(
+    (duration): duration is Duration.Duration =>
+      Duration.isFinite(duration) && !Duration.isNegative(duration),
+    { expected: "a finite non-negative duration" },
+  ),
+);
+
+/** A requested runtime image or executable environment. */
+export class SandboxRuntime extends Schema.Class<SandboxRuntime>("SandboxRuntime")({
+  kind: Schema.Literals(["container", "microvm", "wasm", "unisolated-process"]),
+  identity: BoundedName,
+}) {}
+
+/** The implementation and its isolation posture that executed a request. */
+export class SandboxImplementation extends Schema.Class<SandboxImplementation>(
+  "SandboxImplementation",
+)({
+  isolation: Schema.Literals(["isolated", "unisolated"]),
+  identity: BoundedName,
+}) {}
+
+/** A host path made available to the requested runtime. */
+export class SandboxMount extends Schema.Class<SandboxMount>("SandboxMount")({
+  source: BoundedPath,
+  target: BoundedPath,
+  access: Schema.Literals(["read-only", "read-write"]),
+}) {}
+
+/** Explicitly denies all workload network access. */
+export class NetworkDisabled extends Schema.TaggedClass<NetworkDisabled>()("NetworkDisabled", {}) {}
+
+/** Explicitly permits connections only to the named destination and port allowlists. */
+export class NetworkAllowlist extends Schema.TaggedClass<NetworkAllowlist>()("NetworkAllowlist", {
+  domains: Schema.Array(BoundedName).check(Schema.isMaxLength(256)),
+  ports: Schema.Array(PositiveInt.check(Schema.isLessThanOrEqualTo(65_535))).check(
+    Schema.isMaxLength(256),
+  ),
+}) {}
+
+/** Network access policy supplied to a sandbox implementation. */
+export const SandboxNetworkPolicy = Schema.Union([NetworkDisabled, NetworkAllowlist]);
+export type SandboxNetworkPolicy = typeof SandboxNetworkPolicy.Type;
+
+/** Names of ambient variables that may be copied into the workload environment. */
+export class SandboxEnvironment extends Schema.Class<SandboxEnvironment>("SandboxEnvironment")({
+  allow: BoundedEnvironmentNames,
+}) {}
+
+/** Limits that a sandbox implementation must either enforce or reject. */
+export class SandboxLimits extends Schema.Class<SandboxLimits>("SandboxLimits")({
+  cpuCores: Schema.optionalKey(PositiveNumber.check(Schema.isLessThanOrEqualTo(1_024))),
+  memoryBytes: Schema.optionalKey(
+    PositiveInt.check(Schema.isLessThanOrEqualTo(1024 * 1024 * 1024 * 1024)),
+  ),
+  maxOutputBytes: MaxOutputBytes,
+  maxWallTime: FinitePositiveDuration,
+}) {}
+
+/** A secret reference; raw secret values are never part of a sandbox request. */
+export class SandboxSecretHandle extends Schema.Class<SandboxSecretHandle>("SandboxSecretHandle")({
+  id: BoundedName,
+  purpose: Schema.NonEmptyString.check(Schema.isMaxLength(2 * 1024)),
+}) {}
+
+/** Rules for copying selected workload output out of an isolated runtime. */
+export class SandboxArtifactRule extends Schema.Class<SandboxArtifactRule>("SandboxArtifactRule")({
+  path: BoundedPath,
+  maxBytes: MaxOutputBytes,
+}) {}
+
+/** Metadata for an artifact that a sandbox implementation released after applying its rules. */
+export class SandboxArtifact extends Schema.Class<SandboxArtifact>("SandboxArtifact")({
+  path: BoundedPath,
+  bytes: Schema.Natural.check(Schema.isLessThanOrEqualTo(MAX_OUTPUT_BYTES)),
+  digest: BoundedName,
+  mediaType: Schema.optionalKey(BoundedName),
+}) {}
+
+/** Schema-first command execution request. Command and arguments are intentionally separate. */
+export class SandboxRequest extends Schema.Class<SandboxRequest>("SandboxRequest")({
+  runtime: SandboxRuntime,
+  command: BoundedPath,
+  args: BoundedArguments,
+  cwd: BoundedPath,
+  environment: SandboxEnvironment,
+  mounts: Schema.Array(SandboxMount).check(Schema.isMaxLength(64)),
+  network: SandboxNetworkPolicy,
+  limits: SandboxLimits,
+  secretHandles: Schema.Array(SandboxSecretHandle).check(Schema.isMaxLength(64)),
+  artifactRules: Schema.Array(SandboxArtifactRule).check(Schema.isMaxLength(MAX_ARTIFACT_RULES)),
+}) {}
+
+/** Accounting that a sandbox implementation was able to observe for one execution. */
+export class SandboxResourceUse extends Schema.Class<SandboxResourceUse>("SandboxResourceUse")({
+  wallTime: FiniteNonNegativeDuration,
+  stdoutBytes: Schema.Natural.check(Schema.isLessThanOrEqualTo(MAX_OUTPUT_BYTES)),
+  stderrBytes: Schema.Natural.check(Schema.isLessThanOrEqualTo(MAX_OUTPUT_BYTES)),
+  cpuMillis: Schema.optionalKey(Schema.Natural),
+  memoryBytes: Schema.optionalKey(Schema.Natural),
+}) {}
+
+const SandboxEventBase = {
+  eventVersion: Schema.Literal(1),
+  implementation: SandboxImplementation,
+};
+
+/** Signals that the implementation has accepted the request and started its workload. */
+export class SandboxStarted extends Schema.TaggedClass<SandboxStarted>()("SandboxStarted", {
+  ...SandboxEventBase,
+  runtime: SandboxRuntime,
+}) {}
+
+/** A bounded text fragment from stdout or stderr. Sandbox output is sensitive by default. */
+export class SandboxOutput extends Schema.TaggedClass<SandboxOutput>()("SandboxOutput", {
+  ...SandboxEventBase,
+  stream: Schema.Literals(["stdout", "stderr"]),
+  text: BoundedOutputText,
+  bytes: Schema.Natural.check(Schema.isLessThanOrEqualTo(MAX_OUTPUT_BYTES)),
+}) {}
+
+/** The terminal process status and observed bounded resource usage. */
+export class SandboxExited extends Schema.TaggedClass<SandboxExited>()("SandboxExited", {
+  ...SandboxEventBase,
+  exitCode: Schema.Int,
+  resourceUse: SandboxResourceUse,
+  artifacts: Schema.Array(SandboxArtifact).check(Schema.isMaxLength(MAX_ARTIFACT_RULES)),
+}) {}
+
+/** Versioned execution event stream. */
+export const SandboxEvent = Schema.Union([SandboxStarted, SandboxOutput, SandboxExited]);
+export type SandboxEvent = typeof SandboxEvent.Type;
+
+/** The runtime could not start the requested process. */
+export class SandboxSpawnError extends Schema.TaggedError<SandboxSpawnError>()(
+  "SandboxSpawnError",
+  {
+    implementation: SandboxImplementation,
+    command: BoundedPath,
+    message: BoundedDiagnostic,
+    cause: Schema.optionalKey(Schema.Defect()),
+  },
+) {}
+
+/** The process ended unsuccessfully after starting. */
+export class SandboxExitError extends Schema.TaggedError<SandboxExitError>()("SandboxExitError", {
+  implementation: SandboxImplementation,
+  exitCode: Schema.Int,
+  message: BoundedDiagnostic,
+  cause: Schema.optionalKey(Schema.Defect()),
+}) {}
+
+/** The wall-clock execution limit elapsed and the owned process was interrupted. */
+export class SandboxTimeoutError extends Schema.TaggedError<SandboxTimeoutError>()(
+  "SandboxTimeoutError",
+  {
+    implementation: SandboxImplementation,
+    maxWallTime: FinitePositiveDuration,
+  },
+) {}
+
+/** A stdout or stderr stream exceeded its configured bounded-output limit. */
+export class SandboxOutputLimitError extends Schema.TaggedError<SandboxOutputLimitError>()(
+  "SandboxOutputLimitError",
+  {
+    implementation: SandboxImplementation,
+    stream: Schema.Literals(["stdout", "stderr"]),
+    limit: PositiveInt,
+    observed: PositiveInt,
+  },
+) {}
+
+/** The selected implementation cannot honestly enforce one requested security or resource feature. */
+export class SandboxUnsupportedRequestError extends Schema.TaggedError<SandboxUnsupportedRequestError>()(
+  "SandboxUnsupportedRequestError",
+  {
+    implementation: SandboxImplementation,
+    feature: Schema.Literals([
+      "runtime",
+      "mounts",
+      "network",
+      "cpu-limit",
+      "memory-limit",
+      "secret-handles",
+      "artifacts",
+    ]),
+    message: BoundedDiagnostic,
+  },
+) {}
+
+/** Expected sandbox execution failures. Interruption remains an Effect interruption, never a fabricated exit. */
+export const SandboxError = Schema.Union([
+  SandboxSpawnError,
+  SandboxExitError,
+  SandboxTimeoutError,
+  SandboxOutputLimitError,
+  SandboxUnsupportedRequestError,
+]);
+
+export type SandboxError = typeof SandboxError.Type;
+
+/**
+ * Scoped command/code execution capability. Implementations must identify their isolation posture
+ * in every emitted event; an `unisolated` implementation is never a security sandbox.
+ */
+export class Sandbox extends Context.Service<
+  Sandbox,
+  {
+    readonly execute: (request: SandboxRequest) => Stream.Stream<SandboxEvent, SandboxError>;
+  }
+>()("@effect-agent/sandbox/Sandbox") {}
+
+/** Type helper for implementations that preserve the public Sandbox service contract. */
+export type SandboxExecute = (
+  request: SandboxRequest,
+) => Stream.Stream<SandboxEvent, SandboxError, never>;