apps 0.0.1-beta.32 → 0.0.1-beta.34

package/types/apps/src/contracts/cache.d.ts

@@ -37,6 +37,20 @@ export interface AppCache {
         readonly id: string;
     }) => AppCache;
 }
+/**
+ * A credential a remote read sends, and the account it belongs to. A public source takes neither.
+ * A credential comes only with its account, so the read is cached in that account's scope.
+ */
+export type AccountCredential<Credential extends object> = ({
+    readonly account?: undefined;
+} & {
+    readonly [Field in keyof Credential]?: undefined;
+}) | ({
+    /** The selected account, as `accounts.<slot>` provides it. */
+    readonly account: {
+        readonly id: string;
+    };
+} & Credential);
 /** Trusted storage and background ownership; never accepted from request JSON. */
 export interface HostCache {
     readonly transport: CacheTransport;

package/types/apps/src/contracts/skills.d.ts

@@ -115,14 +115,26 @@ export interface SkillCacheOptions {
     readonly staleFor?: import("effect").Duration.Input;
 }
 /**
- * A public GitHub repository and an optional immutable commit, tag or branch. With a cache, a
- * branch or tag is resolved again when the catalog refreshes, and each commit's file list is kept.
+ * Whose access reads the repository. A public repository needs neither field. A private one takes
+ * a GitHub account and its token, sent on every request of this read. The token comes only with
+ * its account, so the catalog is cached in that account's scope and failures name the account.
  */
-export interface GitHubSkillsOptions extends SkillTransport, SkillCacheOptions {
+export type GitHubSkillsAccount = import("./cache.js").AccountCredential<{
+    /**
+     * The account's token or its handle, such as `account.fields.token`. Its provider declares
+     * hosts `github.com` and `raw.githubusercontent.com`, so app code never holds the value.
+     */
+    readonly token: string;
+}>;
+/**
+ * A GitHub repository and an optional immutable commit, tag or branch. With a cache, a branch or
+ * tag is resolved again when the catalog refreshes, and each commit's file list is kept.
+ */
+export type GitHubSkillsOptions = SkillTransport & SkillCacheOptions & GitHubSkillsAccount & {
     readonly repo: string;
     readonly path?: string;
     readonly ref?: string;
-}
+};
 /** A published directory index, including its listed skill documents and text references. */
 export interface WellKnownSkillsOptions extends SkillTransport, SkillCacheOptions {
     readonly url: string;

package/types/apps/src/implementation/catalog-cache.d.ts

@@ -1,5 +1,5 @@
 import { Duration, Effect, Schema } from "effect";
-import type { AppCache, CacheLoadContext } from "../contracts/cache.js";
+import type { AccountCredential, AppCache, CacheLoadContext } from "../contracts/cache.js";
 import { JsonObject, type JsonValue } from "../contracts/schema.js";
 export interface CatalogCacheOptions {
     /** The app's cache. An account's catalog is kept in that account's scope. */
@@ -11,27 +11,24 @@ export interface CatalogCacheOptions {
     /** Await a fresh revision at an explicit logical connection or refresh boundary. */
     readonly revalidate?: boolean;
 }
-/**
- * Whose catalog a remote router reads. A public server takes neither field. Credential headers
- * come only with the account they belong to, so an authenticated catalog always has its account.
- */
-export type CatalogAccount = {
-    readonly account?: undefined;
-    readonly headers?: undefined;
-} | {
-    /** The selected account, as `accounts.<slot>` provides it. */
-    readonly account: {
-        readonly id: string;
-    };
+/** Whose catalog a remote router reads, and the headers, such as credentials, it sends. */
+export type CatalogAccount = AccountCredential<{
     /** Headers for this account's requests, such as its credentials. */
     readonly headers?: Readonly<Record<string, string>>;
-};
+}>;
+/** Why a read cannot use its account's scope. */
+export type CatalogScopeProblem = "missing-account" | "unselected-account";
 /**
  * The cache an account's catalog lives in: the account's own scope, which token renewals keep.
- * Credentials never enter a key. Headers without an account, or an account the app was not
- * given, fail with `invalid`.
+ * `credential` is what the read sends, such as headers or a token; it never enters a key. A
+ * credential without an account, or an account the app was not given, fails with `invalid`.
  */
-export declare const catalogScope: <E>(options: CatalogCacheOptions & CatalogAccount, invalid: () => E) => Effect.Effect<AppCache | undefined, E>;
+export declare const catalogScope: <E>(options: {
+    readonly cache?: AppCache | undefined;
+    readonly account?: {
+        readonly id: string;
+    } | undefined;
+}, credential: unknown, invalid: (problem: CatalogScopeProblem) => E) => Effect.Effect<AppCache | undefined, E>;
 /** One load: the tools, and optionally a record describing the whole catalog. */
 export interface CatalogLoad<A> {
     readonly tools: readonly A[];

package/types/apps/src/implementation/schema.d.ts

@@ -38,6 +38,11 @@ export interface ObjectSchema<F extends Fields> extends Schema<ObjectValue<F>> {
 export declare const decoderOf: <T>(schema: Schema<T, boolean>) => EffectSchema.Decoder<T>;
 /** Recognize schemas made by this author facade when adapting a definition. */
 export declare const isSchema: (value: unknown) => value is Schema<unknown, boolean>;
+/**
+ * Source that skipped type checking can pass any value where a schema belongs, such as `string`
+ * for `string()`. Name the argument and the mistake before a native constructor reads it.
+ */
+export declare const schemaArgument: <S extends Schema<unknown, boolean>>(value: S, role: string) => S;
 /** Decode within an Effect program. Invalid input is omitted from the failure. */
 export declare const parse: <T>(decoder: EffectSchema.Decoder<T>, input: unknown) => Effect.Effect<T, ValidationError>;
 /** Present a native decoder through the synchronous author API. */

package/types/apps/src/implementation/skills.d.ts

@@ -1,31 +1,24 @@
 /** Remote skill readers return complete portable bundles, never installed host files. */
 import { Effect } from "effect";
-import { SkillLoadFailed, type GitHubSkillsOptions, type WellKnownSkillsOptions, type SkillTransport } from "../contracts/skills.js";
+import { NetworkRefused } from "../contracts/network.js";
+import { ProviderError } from "../contracts/provider-error.js";
+import { AppSkills, SkillLoadFailed, type GitHubSkillsOptions, type WellKnownSkillsOptions, type SkillTransport } from "../contracts/skills.js";
 /** Give every failure without a message one that names the service. */
 export declare const withService: (service: string | undefined) => <A, R>(effect: Effect.Effect<A, SkillLoadFailed, R>) => Effect.Effect<A, SkillLoadFailed, R>;
+interface ReadRequest {
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Describe a refusal by Executor's app network; defaults to the refusal's own message. */
+    readonly refused?: (refused: NetworkRefused) => SkillLoadFailed;
+}
 /** One loader invocation owns its byte budget and all of its network requests. */
 export declare const reader: (transport: SkillTransport) => Effect.Effect<{
-    fetchBytes: (url: string, post?: {
-        readonly body: Uint8Array;
-        readonly headers: Record<string, string>;
+    fetchBytes: (url: string, request?: ReadRequest & {
+        readonly body?: Uint8Array;
     }) => Effect.Effect<Uint8Array<ArrayBuffer>, SkillLoadFailed, never>;
-    read: (url: string) => Effect.Effect<string, SkillLoadFailed, never>;
+    read: (url: string, request?: ReadRequest) => Effect.Effect<string, SkillLoadFailed, never>;
     json: (url: string) => Effect.Effect<unknown, SkillLoadFailed, never>;
 }, never, never>;
-export declare const githubSkillsEffect: (options: GitHubSkillsOptions) => Effect.Effect<readonly {
-    readonly description: string;
-    readonly name: string;
-    readonly files: readonly {
-        readonly path: string;
-        readonly content: string;
-    }[];
-    readonly license?: string;
-    readonly compatibility?: string;
-    readonly metadata?: {
-        readonly [x: string]: string;
-    };
-    readonly "allowed-tools"?: string;
-}[], SkillLoadFailed, never>;
+export declare const githubSkillsEffect: (options: GitHubSkillsOptions) => Effect.Effect<typeof AppSkills.Type, SkillLoadFailed | ProviderError>;
 /** Fetch all indexed files and reject a publication whose index changes during the read. */
 export declare const wellKnownSkillsEffect: (options: WellKnownSkillsOptions) => Effect.Effect<readonly {
     readonly description: string;
@@ -41,3 +34,4 @@ export declare const wellKnownSkillsEffect: (options: WellKnownSkillsOptions) =>
     };
     readonly "allowed-tools"?: string;
 }[], SkillLoadFailed, never>;
+export {};

package/types/apps/src/skills.d.ts

@@ -1,8 +1,9 @@
 import { type FolderSkillsOptions, type GitHubSkillsOptions, type SkillReaderOptions, type WellKnownSkillsOptions, type SkillFile } from "./contracts/skills.js";
-export { SkillLoadFailed, SkillDefinitionInvalid, SkillServiceName, type SkillReaderOptions, type FolderSkillsOptions, type AppSkillSource as Skill, type SkillFile, type GitHubSkillsOptions, type SkillCacheOptions, type WellKnownSkillsOptions, } from "./contracts/skills.js";
+export { SkillLoadFailed, SkillDefinitionInvalid, SkillServiceName, type SkillReaderOptions, type FolderSkillsOptions, type AppSkillSource as Skill, type SkillFile, type GitHubSkillsAccount, type GitHubSkillsOptions, type SkillCacheOptions, type WellKnownSkillsOptions, } from "./contracts/skills.js";
 /**
- * Fetch a public GitHub skill collection from one resolved commit. Pass `cache: ctx.cache` to reuse
- * the catalog; without it, mutable refs resolve again on each call.
+ * Fetch a GitHub skill collection from one resolved commit. A private repository takes `account`
+ * and its `token`. Pass `cache: ctx.cache` to reuse the catalog; without it, mutable refs resolve
+ * again on each call.
  */
 export declare const githubSkills: (options: GitHubSkillsOptions) => Promise<readonly {
     readonly description: string;