@mepuka/skygent 0.3.0 → 0.3.1

package/src/cli/sync.ts

@@ -1,5 +1,5 @@
 import { Command, Options } from "@effect/cli";
-import { Duration, Effect, Layer, Option } from "effect";
+import { Effect, Layer, Option } from "effect";
 import { Jetstream } from "effect-jetstream";
 import { filterExprSignature } from "../domain/filter.js";
 import { DataSource, SyncResult } from "../domain/sync.js";
@@ -28,25 +28,30 @@ import {
   postFilterJsonOption,
   authorFilterOption,
   includePinsOption,
-  decodeActor,
   quietOption,
   refreshOption,
   strictOption,
-  maxErrorsOption,
-  parseMaxErrors,
-  parseLimit
+  maxErrorsOption
 } from "./shared-options.js";
 import {
   depthOption as threadDepthOption,
   parentHeightOption as threadParentHeightOption,
   parseThreadDepth
 } from "./thread-options.js";
+import { DurationInput, PositiveInt } from "./option-schemas.js";
 
-const limitOption = Options.integer("limit").pipe(
+const syncLimitOption = Options.integer("limit").pipe(
+  Options.withSchema(PositiveInt),
+  Options.withDescription("Maximum number of posts to sync"),
+  Options.optional
+);
+const jetstreamLimitOption = Options.integer("limit").pipe(
+  Options.withSchema(PositiveInt),
   Options.withDescription("Maximum number of Jetstream events to process"),
   Options.optional
 );
 const durationOption = Options.text("duration").pipe(
+  Options.withSchema(DurationInput),
   Options.withDescription("Stop after a duration (e.g. \"2 minutes\")"),
   Options.optional
 );
@@ -57,34 +62,10 @@ const parentHeightOption = threadParentHeightOption(
   "Thread parent height to include (0-1000, default 80)"
 );
 
-const parseDuration = (value: Option.Option<string>) =>
-  Option.match(value, {
-    onNone: () => Effect.succeed(Option.none()),
-    onSome: (raw) =>
-      Effect.try({
-        try: () => Duration.decode(raw as Duration.DurationInput),
-        catch: (cause) =>
-          CliInputError.make({
-            message: `Invalid duration: ${raw}. Use formats like \"2 minutes\".`,
-            cause
-          })
-      }).pipe(
-        Effect.flatMap((duration) =>
-          Duration.toMillis(duration) < 0
-            ? Effect.fail(
-                CliInputError.make({
-                  message: "Duration must be non-negative.",
-                  cause: duration
-                })
-              )
-            : Effect.succeed(Option.some(duration))
-        )
-      )
-  });
 
 const timelineCommand = Command.make(
   "timeline",
-  { store: storeNameOption, filter: filterOption, filterJson: filterJsonOption, quiet: quietOption, refresh: refreshOption },
+  { store: storeNameOption, filter: filterOption, filterJson: filterJsonOption, quiet: quietOption, refresh: refreshOption, limit: syncLimitOption },
   makeSyncCommandBody("timeline", () => DataSource.timeline())
 ).pipe(
   Command.withDescription(
@@ -101,7 +82,7 @@ const timelineCommand = Command.make(
 
 const feedCommand = Command.make(
   "feed",
-  { uri: feedUriArg, store: storeNameOption, filter: filterOption, filterJson: filterJsonOption, quiet: quietOption, refresh: refreshOption },
+  { uri: feedUriArg, store: storeNameOption, filter: filterOption, filterJson: filterJsonOption, quiet: quietOption, refresh: refreshOption, limit: syncLimitOption },
   ({ uri, ...rest }) => makeSyncCommandBody("feed", () => DataSource.feed(uri), { uri })(rest)
 ).pipe(
   Command.withDescription(
@@ -117,7 +98,7 @@ const feedCommand = Command.make(
 
 const listCommand = Command.make(
   "list",
-  { uri: listUriArg, store: storeNameOption, filter: filterOption, filterJson: filterJsonOption, quiet: quietOption, refresh: refreshOption },
+  { uri: listUriArg, store: storeNameOption, filter: filterOption, filterJson: filterJsonOption, quiet: quietOption, refresh: refreshOption, limit: syncLimitOption },
   ({ uri, ...rest }) => makeSyncCommandBody("list", () => DataSource.list(uri), { uri })(rest)
 ).pipe(
   Command.withDescription(
@@ -133,7 +114,7 @@ const listCommand = Command.make(
 
 const notificationsCommand = Command.make(
   "notifications",
-  { store: storeNameOption, filter: filterOption, filterJson: filterJsonOption, quiet: quietOption, refresh: refreshOption },
+  { store: storeNameOption, filter: filterOption, filterJson: filterJsonOption, quiet: quietOption, refresh: refreshOption, limit: syncLimitOption },
   makeSyncCommandBody("notifications", () => DataSource.notifications())
 ).pipe(
   Command.withDescription(
@@ -155,18 +136,18 @@ const authorCommand = Command.make(
     postFilter: postFilterOption,
     postFilterJson: postFilterJsonOption,
     quiet: quietOption,
-    refresh: refreshOption
+    refresh: refreshOption,
+    limit: syncLimitOption
   },
-  ({ actor, filter, includePins, postFilter, postFilterJson, store, quiet, refresh }) =>
+  ({ actor, filter, includePins, postFilter, postFilterJson, store, quiet, refresh, limit }) =>
     Effect.gen(function* () {
-      const resolvedActor = yield* decodeActor(actor);
       const apiFilter = Option.getOrUndefined(filter);
-      const source = DataSource.author(resolvedActor, {
+      const source = DataSource.author(actor, {
         ...(apiFilter !== undefined ? { filter: apiFilter } : {}),
         ...(includePins ? { includePins: true } : {})
       });
       const run = makeSyncCommandBody("author", () => source, {
-        actor: resolvedActor,
+        actor,
         ...(apiFilter !== undefined ? { filter: apiFilter } : {}),
         ...(includePins ? { includePins: true } : {})
       });
@@ -175,7 +156,8 @@ const authorCommand = Command.make(
         filter: postFilter,
         filterJson: postFilterJson,
         quiet,
-        refresh
+        refresh,
+        limit
       });
     })
 ).pipe(
@@ -201,12 +183,13 @@ const threadCommand = Command.make(
     filter: filterOption,
     filterJson: filterJsonOption,
     quiet: quietOption,
-    refresh: refreshOption
+    refresh: refreshOption,
+    limit: syncLimitOption
   },
-  ({ uri, depth, parentHeight, filter, filterJson, store, quiet, refresh }) =>
+  ({ uri, depth, parentHeight, filter, filterJson, store, quiet, refresh, limit }) =>
     Effect.gen(function* () {
       const { depth: depthValue, parentHeight: parentHeightValue } =
-        yield* parseThreadDepth(depth, parentHeight);
+        parseThreadDepth(depth, parentHeight);
       const source = DataSource.thread(uri, {
         ...(depthValue !== undefined ? { depth: depthValue } : {}),
         ...(parentHeightValue !== undefined ? { parentHeight: parentHeightValue } : {})
@@ -216,7 +199,7 @@ const threadCommand = Command.make(
         ...(depthValue !== undefined ? { depth: depthValue } : {}),
         ...(parentHeightValue !== undefined ? { parentHeight: parentHeightValue } : {})
       });
-      return yield* run({ store, filter, filterJson, quiet, refresh });
+      return yield* run({ store, filter, filterJson, quiet, refresh, limit });
     })
 ).pipe(
   Command.withDescription(
@@ -244,7 +227,7 @@ const jetstreamCommand = Command.make(
     cursor: jetstreamOptions.cursor,
     compress: jetstreamOptions.compress,
     maxMessageSize: jetstreamOptions.maxMessageSize,
-    limit: limitOption,
+    limit: jetstreamLimitOption,
     duration: durationOption,
     strict: strictOption,
     maxErrors: maxErrorsOption
@@ -285,10 +268,8 @@ const jetstreamCommand = Command.make(
         storeRef,
         filterHash
       );
-      const parsedLimit = yield* parseLimit(limit);
-      const parsedDuration = yield* parseDuration(duration);
-      const parsedMaxErrors = yield* parseMaxErrors(maxErrors);
-      if (Option.isNone(parsedLimit) && Option.isNone(parsedDuration)) {
+      const parsedDuration = duration;
+      if (Option.isNone(limit) && Option.isNone(parsedDuration)) {
         return yield* CliInputError.make({
           message:
             "Jetstream sync requires --limit or --duration. Use watch jetstream for continuous streaming.",
@@ -304,9 +285,9 @@ const jetstreamCommand = Command.make(
       });
       const result = yield* Effect.gen(function* () {
         const engine = yield* JetstreamSyncEngine;
-        const limitValue = Option.getOrUndefined(parsedLimit);
+        const limitValue = Option.getOrUndefined(limit);
         const durationValue = Option.getOrUndefined(parsedDuration);
-        const maxErrorsValue = Option.getOrUndefined(parsedMaxErrors);
+        const maxErrorsValue = Option.getOrUndefined(maxErrors);
         return yield* engine.sync({
           source: selection.source,
           store: storeRef,

package/src/cli/thread-options.ts

@@ -1,15 +1,17 @@
 import { Options } from "@effect/cli";
-import { Effect, Option } from "effect";
-import { parseBoundedIntOption } from "./shared-options.js";
+import { Option } from "effect";
+import { boundedInt } from "./option-schemas.js";
 
 export const depthOption = (description: string) =>
   Options.integer("depth").pipe(
+    Options.withSchema(boundedInt(0, 1000)),
     Options.withDescription(description),
     Options.optional
   );
 
 export const parentHeightOption = (description: string) =>
   Options.integer("parent-height").pipe(
+    Options.withSchema(boundedInt(0, 1000)),
     Options.withDescription(description),
     Options.optional
   );
@@ -17,17 +19,7 @@ export const parentHeightOption = (description: string) =>
 export const parseThreadDepth = (
   depth: Option.Option<number>,
   parentHeight: Option.Option<number>
-) =>
-  Effect.gen(function* () {
-    const parsedDepth = yield* parseBoundedIntOption(depth, "depth", 0, 1000);
-    const parsedParentHeight = yield* parseBoundedIntOption(
-      parentHeight,
-      "parent-height",
-      0,
-      1000
-    );
-    return {
-      depth: Option.getOrUndefined(parsedDepth),
-      parentHeight: Option.getOrUndefined(parsedParentHeight)
-    };
-  });
+) => ({
+  depth: Option.getOrUndefined(depth),
+  parentHeight: Option.getOrUndefined(parentHeight)
+});

package/src/cli/view-thread.ts

@@ -1,5 +1,5 @@
 import { Args, Command, Options } from "@effect/cli";
-import { Chunk, Console, Effect, Option, Schema, Stream } from "effect";
+import { Chunk, Console, Effect, Option, Stream } from "effect";
 import { PostUri, StoreName } from "../domain/primitives.js";
 import type { Post } from "../domain/post.js";
 import { all } from "../domain/filter.js";
@@ -11,19 +11,20 @@ import { StoreIndex } from "../services/store-index.js";
 import { SyncEngine } from "../services/sync-engine.js";
 import { renderThread } from "./doc/thread.js";
 import { renderPlain, renderAnsi } from "./doc/render.js";
-import { writeJson, writeText } from "./output.js";
+import { CliOutput, writeJson, writeText } from "./output.js";
 import { storeOptions } from "./store.js";
 import { withExamples } from "./help.js";
 import { CliInputError } from "./errors.js";
-import { formatSchemaError } from "./shared.js";
 import {
   depthOption as threadDepthOption,
   parentHeightOption as threadParentHeightOption,
   parseThreadDepth
 } from "./thread-options.js";
 import { textJsonFormats } from "./output-format.js";
+import { PositiveInt } from "./option-schemas.js";
 
 const uriArg = Args.text({ name: "uri" }).pipe(
+  Args.withSchema(PostUri),
   Args.withDescription("AT-URI of any post in the thread")
 );
 
@@ -42,6 +43,7 @@ const ansiOption = Options.boolean("ansi").pipe(
 );
 
 const widthOption = Options.integer("width").pipe(
+  Options.withSchema(PositiveInt),
   Options.withDescription("Line width for terminal output"),
   Options.optional
 );
@@ -70,10 +72,11 @@ export const threadCommand = Command.make(
   },
   ({ uri, store, compact, ansi, width, format, depth, parentHeight }) =>
     Effect.gen(function* () {
+      const output = yield* CliOutput;
       const outputFormat = Option.getOrElse(format, () => "text" as const);
       const w = Option.getOrUndefined(width);
       const { depth: depthValue, parentHeight: parentHeightValue } =
-        yield* parseThreadDepth(depth, parentHeight);
+        parseThreadDepth(depth, parentHeight);
       const d = depthValue ?? 6;
       const ph = parentHeightValue ?? 80;
 
@@ -82,15 +85,15 @@ export const threadCommand = Command.make(
       if (Option.isSome(store)) {
         const index = yield* StoreIndex;
         const storeRef = yield* storeOptions.loadStoreRef(store.value);
-        const targetUri = yield* Schema.decodeUnknown(PostUri)(uri).pipe(
-          Effect.mapError((error) =>
-            CliInputError.make({
-              message: `Invalid post URI: ${formatSchemaError(error)}`,
-              cause: error
-            })
-          )
-        );
-        const hasTarget = yield* index.hasUri(storeRef, targetUri);
+        const totalPosts = yield* index.count(storeRef);
+        if (totalPosts > 20000) {
+          yield* output
+            .writeStderr(
+              `ℹ️  Store ${storeRef.name} has ${totalPosts} posts. Thread rendering will load all posts into memory.`
+            )
+            .pipe(Effect.catchAll(() => Effect.void));
+        }
+        const hasTarget = yield* index.hasUri(storeRef, uri);
         if (!hasTarget) {
           const engine = yield* SyncEngine;
           const source = DataSource.thread(uri, { depth: d, parentHeight: ph });
@@ -100,7 +103,7 @@ export const threadCommand = Command.make(
         const stream = index.query(storeRef, query);
         const collected = yield* Stream.runCollect(stream);
         const allPosts = Chunk.toReadonlyArray(collected);
-        const threadPosts = selectThreadPosts(allPosts, String(targetUri));
+        const threadPosts = selectThreadPosts(allPosts, String(uri));
         if (threadPosts.length === 0) {
           return yield* CliInputError.make({
             message: `Thread not found for ${uri}.`,
@@ -108,7 +111,7 @@ export const threadCommand = Command.make(
           });
         }
         // B1: Hint when only root post exists in store
-        if (threadPosts.length === 1 && threadPosts[0]?.uri === targetUri) {
+        if (threadPosts.length === 1 && threadPosts[0]?.uri === uri) {
           yield* Console.log("\nℹ️  Only root post found in store. Use --no-store to fetch full thread from API.\n");
         }
         posts = threadPosts;

package/src/cli/watch.ts

@@ -14,7 +14,6 @@ import { withExamples } from "./help.js";
 import { buildJetstreamSelection, jetstreamOptions } from "./jetstream.js";
 import { makeWatchCommandBody } from "./sync-factory.js";
 import { parseOptionalDuration } from "./interval.js";
-import { CliInputError } from "./errors.js";
 import {
   feedUriArg,
   listUriArg,
@@ -27,30 +26,32 @@ import {
   postFilterJsonOption,
   authorFilterOption,
   includePinsOption,
-  decodeActor,
   quietOption,
   refreshOption,
   strictOption,
-  maxErrorsOption,
-  parseMaxErrors
+  maxErrorsOption
 } from "./shared-options.js";
 import {
   depthOption as threadDepthOption,
   parentHeightOption as threadParentHeightOption,
   parseThreadDepth
 } from "./thread-options.js";
+import { DurationInput, PositiveInt } from "./option-schemas.js";
 
 const intervalOption = Options.text("interval").pipe(
+  Options.withSchema(DurationInput),
   Options.withDescription(
     "Polling interval (e.g. \"30 seconds\", \"500 millis\") (default: 30 seconds)"
   ),
   Options.optional
 );
 const maxCyclesOption = Options.integer("max-cycles").pipe(
+  Options.withSchema(PositiveInt),
   Options.withDescription("Stop after N watch cycles"),
   Options.optional
 );
 const untilOption = Options.text("until").pipe(
+  Options.withSchema(DurationInput),
   Options.withDescription("Stop after a duration (e.g. \"10 minutes\")"),
   Options.optional
 );
@@ -179,14 +180,13 @@ const authorCommand = Command.make(
   },
   ({ actor, filter, includePins, postFilter, postFilterJson, interval, maxCycles, until, store, quiet, refresh }) =>
     Effect.gen(function* () {
-      const resolvedActor = yield* decodeActor(actor);
       const apiFilter = Option.getOrUndefined(filter);
-      const source = DataSource.author(resolvedActor, {
+      const source = DataSource.author(actor, {
         ...(apiFilter !== undefined ? { filter: apiFilter } : {}),
         ...(includePins ? { includePins: true } : {})
       });
       const run = makeWatchCommandBody("author", () => source, {
-        actor: resolvedActor,
+        actor,
         ...(apiFilter !== undefined ? { filter: apiFilter } : {}),
         ...(includePins ? { includePins: true } : {})
       });
@@ -232,7 +232,7 @@ const threadCommand = Command.make(
   ({ uri, depth, parentHeight, filter, filterJson, interval, maxCycles, until, store, quiet, refresh }) =>
     Effect.gen(function* () {
       const { depth: depthValue, parentHeight: parentHeightValue } =
-        yield* parseThreadDepth(depth, parentHeight);
+        parseThreadDepth(depth, parentHeight);
       const source = DataSource.thread(uri, {
         ...(depthValue !== undefined ? { depth: depthValue } : {}),
         ...(parentHeightValue !== undefined ? { parentHeight: parentHeightValue } : {})
@@ -309,27 +309,14 @@ const jetstreamCommand = Command.make(
         storeRef,
         filterHash
       );
-      const parsedMaxErrors = yield* parseMaxErrors(maxErrors);
-      const parsedUntil = yield* parseOptionalDuration(until);
-      const parsedMaxCycles = yield* Option.match(maxCycles, {
-        onNone: () => Effect.succeed(Option.none<number>()),
-        onSome: (value) =>
-          value <= 0
-            ? Effect.fail(
-                CliInputError.make({
-                  message: "--max-cycles must be a positive integer.",
-                  cause: { maxCycles: value }
-                })
-              )
-            : Effect.succeed(Option.some(value))
-      });
+      const parsedUntil = parseOptionalDuration(until);
       const engineLayer = JetstreamSyncEngine.layer.pipe(
         Layer.provideMerge(Jetstream.live(selection.config))
       );
       yield* logInfo("Starting watch", { source: "jetstream", store: storeRef.name });
       yield* Effect.gen(function* () {
         const engine = yield* JetstreamSyncEngine;
-        const maxErrorsValue = Option.getOrUndefined(parsedMaxErrors);
+        const maxErrorsValue = Option.getOrUndefined(maxErrors);
         const stream = engine.watch({
           source: selection.source,
           store: storeRef,
@@ -346,8 +333,8 @@ const jetstreamCommand = Command.make(
             makeSyncReporter(quiet, monitor, output)
           )
         );
-        const limited = Option.isSome(parsedMaxCycles)
-          ? outputStream.pipe(Stream.take(parsedMaxCycles.value))
+        const limited = Option.isSome(maxCycles)
+          ? outputStream.pipe(Stream.take(maxCycles.value))
           : outputStream;
         const timed = Option.isSome(parsedUntil)
           ? limited.pipe(Stream.interruptWhen(Effect.sleep(parsedUntil.value)))

package/src/domain/primitives.ts

@@ -16,18 +16,35 @@ export const Hashtag = Schema.String.pipe(
 );
 export type Hashtag = typeof Hashtag.Type;
 
-export const AtUri = Schema.String.pipe(Schema.brand("AtUri"));
+const atUriPattern = /^at:\/\/\S+$/;
+
+export const AtUri = Schema.String.pipe(
+  Schema.pattern(atUriPattern),
+  Schema.brand("AtUri")
+);
 export type AtUri = typeof AtUri.Type;
 
-export const PostUri = Schema.String.pipe(Schema.brand("PostUri"));
+export const PostUri = Schema.String.pipe(
+  Schema.pattern(atUriPattern),
+  Schema.brand("PostUri")
+);
 export type PostUri = typeof PostUri.Type;
 
 export const PostCid = Schema.String.pipe(Schema.brand("PostCid"));
 export type PostCid = typeof PostCid.Type;
 
-export const Did = Schema.String.pipe(Schema.brand("Did"));
+export const Did = Schema.String.pipe(
+  Schema.pattern(/^did:\S+$/),
+  Schema.brand("Did")
+);
 export type Did = typeof Did.Type;
 
+export const ActorId = Schema.String.pipe(
+  Schema.pattern(/^(did:\S+|[a-z0-9][a-z0-9.-]{1,251})$/),
+  Schema.brand("ActorId")
+);
+export type ActorId = typeof ActorId.Type;
+
 export const Timestamp = Schema.Union(
   Schema.DateFromString,
   Schema.DateFromSelf

package/src/services/bsky-client.ts

@@ -1256,6 +1256,7 @@ export class BskyClient extends Context.Tag("@skygent/BskyClient")<
       const config = yield* AppConfigService;
       const credentials = yield* CredentialStore;
       const agent = new AtpAgent({ service: config.service });
+      const publicAgent = new AtpAgent({ service: "https://public.api.bsky.app" });
 
       const minInterval = yield* Config.duration("SKYGENT_BSKY_RATE_LIMIT").pipe(
         Config.withDefault(Duration.millis(250))
@@ -1507,6 +1508,7 @@ export class BskyClient extends Context.Tag("@skygent/BskyClient")<
       const getFollowers = (actor: string, opts?: GraphOptions) =>
         Effect.gen(function* () {
           yield* ensureAuth(false);
+          const api = agent.hasSession ? agent : publicAgent;
           const params = withCursor(
             { actor, limit: opts?.limit ?? 50 },
             opts?.cursor
@@ -1514,7 +1516,7 @@ export class BskyClient extends Context.Tag("@skygent/BskyClient")<
           const response = yield* withRetry(
             withRateLimit(
               Effect.tryPromise<AppBskyGraphGetFollowers.Response>(() =>
-                agent.app.bsky.graph.getFollowers(params)
+                api.app.bsky.graph.getFollowers(params)
               )
             )
           ).pipe(Effect.mapError(toBskyError("Failed to fetch followers", "getFollowers")));
@@ -1531,6 +1533,7 @@ export class BskyClient extends Context.Tag("@skygent/BskyClient")<
       const getFollows = (actor: string, opts?: GraphOptions) =>
         Effect.gen(function* () {
           yield* ensureAuth(false);
+          const api = agent.hasSession ? agent : publicAgent;
           const params = withCursor(
             { actor, limit: opts?.limit ?? 50 },
             opts?.cursor
@@ -1538,7 +1541,7 @@ export class BskyClient extends Context.Tag("@skygent/BskyClient")<
           const response = yield* withRetry(
             withRateLimit(
               Effect.tryPromise<AppBskyGraphGetFollows.Response>(() =>
-                agent.app.bsky.graph.getFollows(params)
+                api.app.bsky.graph.getFollows(params)
               )
             )
           ).pipe(Effect.mapError(toBskyError("Failed to fetch follows", "getFollows")));
@@ -1582,10 +1585,11 @@ export class BskyClient extends Context.Tag("@skygent/BskyClient")<
             return { actor, relationships: [] };
           }
           yield* ensureAuth(false);
+          const api = agent.hasSession ? agent : publicAgent;
           const response = yield* withRetry(
             withRateLimit(
               Effect.tryPromise<AppBskyGraphGetRelationships.Response>(() =>
-                agent.app.bsky.graph.getRelationships({ actor, others: [...others] })
+                api.app.bsky.graph.getRelationships({ actor, others: [...others] })
               )
             )
           ).pipe(Effect.mapError(toBskyError("Failed to fetch relationships", "getRelationships")));
@@ -1602,6 +1606,7 @@ export class BskyClient extends Context.Tag("@skygent/BskyClient")<
       const getList = (uri: string, opts?: GraphOptions) =>
         Effect.gen(function* () {
           yield* ensureAuth(false);
+          const api = agent.hasSession ? agent : publicAgent;
           const params = withCursor(
             { list: uri, limit: opts?.limit ?? 50 },
             opts?.cursor
@@ -1609,7 +1614,7 @@ export class BskyClient extends Context.Tag("@skygent/BskyClient")<
           const response = yield* withRetry(
             withRateLimit(
               Effect.tryPromise<AppBskyGraphGetList.Response>(() =>
-                agent.app.bsky.graph.getList(params)
+                api.app.bsky.graph.getList(params)
               )
             )
           ).pipe(Effect.mapError(toBskyError("Failed to fetch list", "getList")));
@@ -1626,6 +1631,7 @@ export class BskyClient extends Context.Tag("@skygent/BskyClient")<
       const getLists = (actor: string, opts?: GraphListsOptions) =>
         Effect.gen(function* () {
           yield* ensureAuth(false);
+          const api = agent.hasSession ? agent : publicAgent;
           const params = withCursor(
             {
               actor,
@@ -1639,7 +1645,7 @@ export class BskyClient extends Context.Tag("@skygent/BskyClient")<
           const response = yield* withRetry(
             withRateLimit(
               Effect.tryPromise<AppBskyGraphGetLists.Response>(() =>
-                agent.app.bsky.graph.getLists(params)
+                api.app.bsky.graph.getLists(params)
               )
             )
           ).pipe(Effect.mapError(toBskyError("Failed to fetch lists", "getLists")));

package/src/services/shared.ts

@@ -19,10 +19,57 @@ export const pickDefined = <T extends Record<string, unknown>>(input: T): Partia
     Object.entries(input).filter(([, value]) => value !== undefined)
   ) as Partial<T>;
 
+type FormatParseErrorOptions = {
+  readonly label?: string;
+  readonly maxIssues?: number;
+};
+
+const formatPath = (path: ReadonlyArray<unknown>) =>
+  path.length > 0 ? path.map((entry) => String(entry)).join(".") : "value";
+
+export const formatParseError = (
+  error: ParseResult.ParseError,
+  options?: FormatParseErrorOptions
+) => {
+  const issues = ParseResult.ArrayFormatter.formatErrorSync(error);
+  if (issues.length === 0) {
+    return ParseResult.TreeFormatter.formatErrorSync(error);
+  }
+
+  const jsonParseIssue = issues.find(
+    (issue) =>
+      issue._tag === "Transformation" &&
+      typeof issue.message === "string" &&
+      issue.message.startsWith("JSON Parse error")
+  );
+  if (jsonParseIssue) {
+    const header = options?.label
+      ? `Invalid JSON input for ${options.label}.`
+      : "Invalid JSON input.";
+    return [
+      header,
+      jsonParseIssue.message,
+      "Tip: wrap JSON in single quotes to avoid shell escaping issues."
+    ].join("\n");
+  }
+
+  const maxIssues = options?.maxIssues ?? 6;
+  const lines = issues.slice(0, maxIssues).map((issue) => {
+    const path = formatPath(issue.path);
+    return `${path}: ${issue.message}`;
+  });
+  if (issues.length > maxIssues) {
+    lines.push(`Additional issues: ${issues.length - maxIssues}`);
+  }
+
+  const header = options?.label ? `Invalid ${options.label}.` : undefined;
+  return header ? [header, ...lines].join("\n") : lines.join("\n");
+};
+
 /** Format a Schema parse error (or arbitrary unknown) as a readable string. */
 export const formatSchemaError = (error: unknown) => {
   if (ParseResult.isParseError(error)) {
-    return ParseResult.TreeFormatter.formatErrorSync(error);
+    return formatParseError(error);
   }
   return String(error);
 };

package/src/services/store-cleaner.ts

@@ -11,7 +11,10 @@ export class StoreCleaner extends Context.Tag("@skygent/StoreCleaner")<
   {
     readonly deleteStore: (
       name: StoreName
-    ) => Effect.Effect<{ readonly deleted: boolean }, StoreError>;
+    ) => Effect.Effect<
+      { readonly deleted: boolean; readonly reason?: "missing" },
+      StoreError
+    >;
   }
 >() {
   static readonly layer = Layer.effect(
@@ -26,7 +29,7 @@ export class StoreCleaner extends Context.Tag("@skygent/StoreCleaner")<
         Effect.gen(function* () {
           const storeOption = yield* manager.getStore(name);
           if (Option.isNone(storeOption)) {
-            return { deleted: false } as const;
+            return { deleted: false, reason: "missing" } as const;
           }
           const store = storeOption.value;
           yield* eventLog.clear(store);

package/src/services/store-renamer.ts

@@ -13,6 +13,7 @@ type StoreRenameResult = {
   readonly from: StoreName;
   readonly to: StoreName;
   readonly moved: boolean;
+  readonly movedOnDisk: boolean;
   readonly lineagesUpdated: number;
   readonly checkpointsUpdated: number;
 };
@@ -262,7 +263,8 @@ export class StoreRenamer extends Context.Tag("@skygent/StoreRenamer")<
               return {
                 from,
                 to,
-                moved: fromExists,
+                moved: true,
+                movedOnDisk: fromExists,
                 lineagesUpdated,
                 checkpointsUpdated
               } satisfies StoreRenameResult;