@fungi.computer/oyster 0.1.0 → 0.3.0

package/dist/agent-avatars.js

@@ -0,0 +1,66 @@
+import { seededAvatar } from "@fungi.computer/sprite/avatar";
+import { avatarSchema } from "@fungi.computer/sprite-zdog/avatar";
+import { avatarCatalog } from "@fungi.computer/sprite-zdog/catalog";
+import { renderStyleSchema } from "@fungi.computer/sprite";
+import { z } from "zod";
+const storedAvatarRowSchema = z.strictObject({ avatar: z.string() });
+/** The catalog-valid avatar an owner may choose for an Agent. */
+export const agentAvatarSchema = avatarSchema;
+const appearanceValue = z.union([z.string(), z.number(), z.boolean()]);
+/** One character's avatar with its appearance closed to that character's controls. */
+function closedCharacterAvatar(character) {
+    return z.strictObject({
+        v: z.literal(1),
+        character: z.literal(character),
+        appearance: z.strictObject(Object.fromEntries(Object.keys(avatarCatalog[character].controls).map((control) => [
+            control,
+            appearanceValue.optional(),
+        ]))),
+        expression: z.string().min(1),
+        renderStyle: renderStyleSchema,
+    });
+}
+/**
+ * The avatar as a closed record, for contracts that refuse open maps (Hub
+ * projections): each character's appearance names only its own controls,
+ * then the catalog refines it exactly as `agentAvatarSchema` does.
+ */
+export const agentAvatarProjectionSchema = z
+    .discriminatedUnion("character", [
+    closedCharacterAvatar("mushroom"),
+    closedCharacterAvatar("cat"),
+    closedCharacterAvatar("burger"),
+])
+    .superRefine((avatar, context) => {
+    for (const issue of agentAvatarSchema.safeParse(avatar).error?.issues ?? [])
+        context.addIssue({
+            code: "custom",
+            path: issue.path,
+            message: issue.message,
+        });
+});
+/** A projected avatar as the Avatar descriptor Sprite draws. */
+export function avatarFromProjection(projected) {
+    return agentAvatarSchema.parse(projected);
+}
+/** Open the chosen-avatar table in the Agent directory's own SQLite. */
+export function createAgentAvatarStore(sql) {
+    sql.exec("CREATE TABLE IF NOT EXISTS agent_avatars (agent_id TEXT PRIMARY KEY, avatar TEXT NOT NULL) STRICT");
+    return {
+        read(agentId) {
+            const row = sql
+                .exec("SELECT avatar FROM agent_avatars WHERE agent_id = ?", agentId)
+                .toArray()[0];
+            if (row === undefined)
+                return seededAvatar(agentId);
+            const stored = storedAvatarRowSchema.parse(row);
+            return agentAvatarSchema.parse(JSON.parse(stored.avatar));
+        },
+        write(agentId, avatar) {
+            sql.exec("INSERT INTO agent_avatars(agent_id, avatar) VALUES(?, ?) ON CONFLICT(agent_id) DO UPDATE SET avatar = excluded.avatar", agentId, JSON.stringify(agentAvatarSchema.parse(avatar)));
+        },
+        remove(agentId) {
+            sql.exec("DELETE FROM agent_avatars WHERE agent_id = ?", agentId);
+        },
+    };
+}

package/dist/agents.d.ts

@@ -3,18 +3,22 @@
  * the App page calls. Apps reach agents through Agar's `agent.list`,
  * `agent.manage`, `agent.read` and `agent.send` contracts, so an App written
  * for the Hub (Grove) runs unchanged. Each agent's own transport is
- * Shiitake's HTTP routes (`/sessions…`, `/acp`), served by the adapter.
+ * Shiitake's HTTP routes (`/sessions…`, `/acp`) and Knapsack's Session browser
+ * transport (`/browser/…`), served by the adapter behind the same App grants.
  */
 import { Hono } from "hono";
 import type { AppToolPolicy } from "./apps/tools.js";
 import * as Schema from "effect/Schema";
 import { type OysterCapability, type OysterEnv, type OysterPrincipal } from "./host.js";
 import type { HostActor } from "@fungi.computer/puffball/app";
+import type { Avatar } from "@fungi.computer/sprite/avatar";
 import type { MemberInboxItem, MemberInboxSession } from "@fungi.computer/puffball/inbox";
 /** One agent as Apps see it, in Agar's `appAgentSchema` shape. */
 export type OysterAgent = Readonly<{
     agentId: string;
     name: string;
+    /** The Agent's own avatar: the owner's choice, else its seeded default. */
+    avatar: Avatar;
     sessionOperations: readonly ("agent.read" | "agent.send" | "agent.manage")[];
 }>;
 /** An Agent owner's Session facts before the member identity and visit are added. */
@@ -70,12 +74,19 @@ export type AgentToolPolicyStatus = Readonly<{
 export type OysterAgents = Readonly<{
     /** Every agent, oldest first. */
     list(): Promise<readonly OysterAgent[]>;
-    /** Create an agent; retrying with the same `requestId` returns the same one. */
-    create(name: string, requestId: string, principal: OysterPrincipal, actor: AgentPolicyActor): Promise<OysterAgent>;
+    /**
+     * Create an agent; retrying with the same `requestId` returns the same one.
+     * With no `avatar` it wears its seeded default until the owner picks one.
+     */
+    create(name: string, requestId: string, principal: OysterPrincipal, actor: AgentPolicyActor, avatar?: Avatar): Promise<OysterAgent>;
     /** Owner-only rename; refuses a name already held by another Agent. */
     rename(agentId: string, name: string, principal: OysterPrincipal): Promise<OysterAgent | Readonly<{
         error: "not_found" | "name_taken" | "not_granted";
     }>>;
+    /** Owner-only avatar change for an existing Agent. */
+    setAvatar(agentId: string, avatar: Avatar, principal: OysterPrincipal): Promise<OysterAgent | Readonly<{
+        error: "not_found" | "not_granted";
+    }>>;
     /** This Agent's App-tool policy status, or `null` for no such Agent. */
     policyStatus(agentId: string): Promise<AgentToolPolicyStatus | null>;
     /** Read this Agent's stored App-tool approval; absence requires re-approval. A key's App access is its own grants (Ear Tag), not this policy. */
@@ -94,7 +105,7 @@ export type OysterAgents = Readonly<{
     addMcpServer(agentId: string, input: AgentMcpServerInput): Promise<AgentMcpServer | AgentMcpServerRefusal>;
     /** Disconnect one MCP server; `false` when the Agent or server is unknown. */
     removeMcpServer(agentId: string, serverId: string): Promise<boolean>;
-    /** Serve one Shiitake transport request (`/sessions…`, `/acp`) for an agent. */
+    /** Serve this Agent's Shiitake and Knapsack Session browser transports. */
     fetch(agentId: string, request: Request): Promise<Response | null>;
     /** This member's Session and Workflow review rows, admitted by the host. */
     inbox(): Promise<OysterInbox>;

package/dist/agents.js

@@ -3,12 +3,15 @@
  * the App page calls. Apps reach agents through Agar's `agent.list`,
  * `agent.manage`, `agent.read` and `agent.send` contracts, so an App written
  * for the Hub (Grove) runs unchanged. Each agent's own transport is
- * Shiitake's HTTP routes (`/sessions…`, `/acp`), served by the adapter.
+ * Shiitake's HTTP routes (`/sessions…`, `/acp`) and Knapsack's Session browser
+ * transport (`/browser/…`), served by the adapter behind the same App grants.
  */
 import { Hono } from "hono";
 import * as Schema from "effect/Schema";
+import { z } from "zod";
 import { oysterPrincipalIsOwner, } from "./host.js";
-import { agentList, agentManage, agentRename, agentSessionRead, agentSessionWrite, agentToolPolicy, } from "@fungi.computer/agar/agents";
+import { agentAvatarSchema } from "./agent-avatars.js";
+import { agentAvatar, agentList, agentManage, agentRename, agentSessionRead, agentSessionWrite, agentToolPolicy, } from "@fungi.computer/agar/agents";
 /** At most this many MCP servers per Agent. */
 export const maxAgentMcpServers = 16;
 /** Owner input for one MCP server: a guest identifier, an `https:` endpoint and an optional bearer. */
@@ -30,10 +33,12 @@ export const agentMcpServerInputSchema = Schema.Struct({
 const createSchema = Schema.Struct({
     name: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256)),
     requestId: Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_.:-]{1,256}$/u)),
+    avatar: Schema.optionalKey(Schema.Unknown),
 });
 const renameSchema = Schema.Struct({
     name: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256)),
 });
+const avatarInputSchema = z.object({ avatar: agentAvatarSchema });
 const visitSchema = Schema.Struct({
     agentId: Schema.String,
     sessionId: Schema.String,
@@ -76,6 +81,19 @@ export function agentCapabilities(agents) {
                 rename: { kind: "json", method: "PUT", path: "agent-names/:agentId" },
             },
         },
+        {
+            ...shared,
+            id: "agent.avatar",
+            permission: "agent.avatar",
+            version: agentAvatar.version,
+            methods: {
+                setAvatar: {
+                    kind: "json",
+                    method: "PUT",
+                    path: "agent-avatars/:agentId",
+                },
+            },
+        },
         {
             ...shared,
             id: "agent.toolPolicy",
@@ -126,9 +144,14 @@ function createAgentRoutes(agents) {
         const body = Schema.decodeUnknownOption(createSchema)(await context.req.json());
         if (body._tag === "None")
             return refusal(400, "Name the agent");
+        const avatar = body.value.avatar === undefined
+            ? undefined
+            : agentAvatarSchema.safeParse(body.value.avatar);
+        if (avatar?.success === false)
+            return refusal(400, "Choose a valid avatar");
         // The owner's own authenticated request creates this Agent; its App tools
         // are approved the same way direct owner approval is, with no second path.
-        return Response.json(await agents.create(body.value.name, body.value.requestId, principal, "owner-direct"));
+        return Response.json(await agents.create(body.value.name, body.value.requestId, principal, "owner-direct", avatar?.data));
     });
     routes.put("/agent-names/:agentId", async (context) => {
         const { principal } = context.env;
@@ -149,6 +172,21 @@ function createAgentRoutes(agents) {
                     : 403, result.error);
         return Response.json(result);
     });
+    routes.put("/agent-avatars/:agentId", async (context) => {
+        const { principal } = context.env;
+        if (!oysterPrincipalIsOwner(principal))
+            return refusal(403, "Only the owner changes avatars");
+        const agentId = context.req.param("agentId");
+        if (!agentIdPattern.test(agentId))
+            return refusal(404, "No such agent");
+        const body = avatarInputSchema.safeParse(await context.req.json());
+        if (!body.success)
+            return refusal(400, "Choose a valid avatar");
+        const result = await agents.setAvatar(agentId, body.data.avatar, principal);
+        if ("error" in result)
+            return refusal(result.error === "not_found" ? 404 : 403, result.error);
+        return Response.json(result);
+    });
     routes.get("/agent-policies/:agentId", async (context) => {
         const agentId = context.req.param("agentId");
         if (!agentIdPattern.test(agentId))
@@ -168,7 +206,8 @@ function createAgentRoutes(agents) {
         const path = url.pathname.slice(`/agents/${agentId}`.length);
         if (!(path === "/acp" ||
             path === "/sessions" ||
-            path.startsWith("/sessions/")))
+            path.startsWith("/sessions/") ||
+            path.startsWith("/browser/")))
             return refusal(404, "Not found");
         const length = Number(incoming.headers.get("content-length") ?? "0");
         if (length > maxAgentRequestBytes)

package/dist/app-builds.d.ts

@@ -19,6 +19,7 @@
 import * as Schema from "effect/Schema";
 import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
 import { type Release } from "@fungi.computer/puffball";
+import { type AppPublisherCoreConfigInput } from "./build/effect.js";
 import { type TeamAppCandidateManifest } from "./build/submission-contract.js";
 import { type ArtifactHeads, type ArtifactStore } from "./release.js";
 import type { PublisherTemplateSeedReceipts } from "./source/seed-receipt.js";
@@ -77,6 +78,19 @@ export declare const oysterBuildSourceSchema: Schema.Struct<{
     readonly buildRecipeDigest: Schema.refine<import("@fungi.computer/puffball").Sha256Digest, Schema.String>;
 }>;
 export type OysterBuildSource = Schema.Schema.Type<typeof oysterBuildSourceSchema>;
+/** Installation is a build outcome, never a pending consent/approval record. */
+export declare const oysterBuildInstallationSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"pending">;
+    readonly installationId: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["installed", "needs_consent"]>;
+    readonly installationId: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"failed">;
+    readonly installationId: Schema.String;
+    readonly detail: Schema.String;
+}>]>;
+export type OysterBuildInstallation = Schema.Schema.Type<typeof oysterBuildInstallationSchema>;
 /** What an owner sees of one build. */
 export type OysterBuildView = Readonly<{
     jobId: string;
@@ -86,8 +100,42 @@ export type OysterBuildView = Readonly<{
     status: "running" | "succeeded" | "failed" | "revoked";
     detail: string | null;
     release: Release | null;
+    installation: OysterBuildInstallation | null;
+}>;
+/** Known preflight refusals, before a job or Computer run exists. */
+export declare const oysterBuildStartReasonSchema: Schema.Literals<readonly ["invalid_revision", "no_source", "not_template_seed", "no_backend"]>;
+export type OysterBuildStartReason = Schema.Schema.Type<typeof oysterBuildStartReasonSchema>;
+export declare const oysterBuildStartMessages: {
+    invalid_revision: string;
+    no_source: string;
+    no_backend: string;
+    not_template_seed: string;
+};
+declare const OysterBuildStartError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "OysterBuildStartError";
+} & Readonly<A>;
+/** Local typed failure. The registry turns it into data before a DO RPC. */
+export declare class OysterBuildStartError extends OysterBuildStartError_base<{
+    readonly reason: OysterBuildStartReason;
+    readonly message: string;
+}> {
+    constructor(reason: OysterBuildStartReason);
+}
+export type OysterBuildStartResult = Readonly<{
+    kind: "started";
+    build: OysterBuildView;
+}> | Readonly<{
+    kind: "refused";
+    reason: OysterBuildStartReason;
+}>;
+export type OysterBuildBackend = Readonly<{
+    kind: "hosted";
+}> | Readonly<{
+    kind: "no_backend";
 }>;
 export type OysterBuildComputer = Readonly<{
+    /** Read the configured hosted route without starting a machine. Local machines never build Apps. */
+    buildBackend(): Promise<OysterBuildBackend>;
     /** Run the fixed build command; the Computer re-admits the job first.
      * A missing `output` means no terminal result was established: the
      * command may still be running, so it is never read as an exit. */
@@ -118,17 +166,28 @@ export type OysterAppBuildOptions = Readonly<{
     templates: Pick<PublisherTemplateSeedReceipts, "read">;
     now?: () => number;
 }>;
-/**
- * The SQLite tables one Oyster build owner keeps. Creation and any carrying
- * forward of retained facts run as one transaction of the owner's storage, so
- * an interrupted conversion leaves the facts as they were for a retry.
- */
+/** Create the current build tables and index atomically; never convert old stores. */
 export declare function migrateOysterAppBuilds(owner: WatchdogSqliteOwner): void;
 /** The build owner over one tenant's SQLite, Computer and artifact store. */
 export declare function createOysterAppBuilds(options: OysterAppBuildOptions): Readonly<{
     /** Record (or replace) an App's build source; the caller is the owner. */
-    registerSource(source: OysterBuildSource): OysterBuildSource;
+    registerSource: (source: OysterBuildSource) => OysterBuildSource;
+    /** Resolve repository identity and replace its current recipe as one transition.
+     * A fork's existing identity wins over the copied manifest's App id. */
+    registerRepositorySource(input: {
+        appId: string;
+        location: Extract<OysterBuildLocation, {
+            kind: "installation";
+        }>;
+        recipe: AppPublisherCoreConfigInput["recipe"];
+    }): {
+        kind: "registered";
+        source: OysterBuildSource;
+    } | {
+        kind: "conflict";
+    };
     readSource: (appId: string) => OysterBuildSource | null;
+    readRepositorySource: (installationId: string, repository: string) => OysterBuildSource | null;
     /**
      * Mint one build job for an App's registered source at one exact commit.
      * A template source builds only a seed revision recorded for its pinned
@@ -136,15 +195,28 @@ export declare function createOysterAppBuilds(options: OysterAppBuildOptions): R
      * Answers the job and its one run, which the caller keeps alive (the
      * upload grant exists only inside that run's fixed command).
      */
-    start(input: {
+    start: (input: {
         appId: string;
         sourceRevision: string;
         requestedBy: string;
-    }): Promise<Readonly<{
+        /** The Workflow's installation target. Absence leaves manual builds manual. */
+        installAt?: string;
+        /** One host-owned Workflow node reuses its job, including after restart. */
+        requestId?: string;
+    }) => Promise<Readonly<{
         build: OysterBuildView;
         run: () => Promise<OysterBuildView>;
     }>>;
     read(jobId: string): OysterBuildView | null;
+    /** Discover the current source's latest job from the caller's Git owner,
+     * never a job id remembered in a browser or another installation's repo. */
+    latestRepositoryBuild(installationId: string, repository: string): OysterBuildView | null;
+    /** One bounded host installation at a time. Only a verified successful
+     * build may reach the installer; the same existing row owns its outcome.
+     * A Workflow retry may resume a pending decision, never a terminal one. */
+    install(jobId: string, decide: (release: Release, installationId: string) => Promise<Exclude<OysterBuildInstallation, {
+        kind: "pending";
+    }>>): Promise<boolean>;
     /** A built Release by id, for an owner to install or select. */
     release(releaseId: string): Release | null;
     /** May this Computer execute this job now? Re-checked by the Computer. */
@@ -208,3 +280,4 @@ export declare function createOysterAppBuilds(options: OysterAppBuildOptions): R
     submitCandidate(jobId: string, manifest: TeamAppCandidateManifest, grant: string, credentialId: string): Promise<Response>;
 }>;
 export type OysterAppBuilds = ReturnType<typeof createOysterAppBuilds>;
+export {};