@fungi.computer/oyster 0.0.1 → 0.2.0

package/dist/agents.d.ts

@@ -10,11 +10,14 @@ 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 +73,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. */

package/dist/agents.js

@@ -7,8 +7,10 @@
  */
 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 +32,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 +80,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 +143,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 +171,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))

package/dist/app-builds.d.ts

@@ -1,20 +1,53 @@
+/**
+ * Oyster's App build owner: an App's registered source, its build jobs on the
+ * host's own Computer, and the Releases those builds produce.
+ *
+ * A build runs the shared job lifecycle (`build/build-jobs.ts`) and the fixed
+ * captured builder command on one Computer. The Computer holds no key: its
+ * clone is admitted at egress for exactly the job's one repository (read
+ * only), and its candidate upload for exactly the job. A source is either a
+ * repository in an installation's Git (a fork, through the Git door) or the
+ * App's own published template, built only at a recorded seed revision of
+ * its pinned recipe (no installed App is needed). The build streams each
+ * built object into the host's artifact store itself, through the egress, and
+ * then submits a small manifest naming them. This owner only records facts:
+ * it checks each named object's stored size and digest, writes the asset
+ * manifest and App root in Oyster's one immutable artifact representation
+ * (the same objects a packed upload writes), verifies the Release like any
+ * installed one, and records it; installing it is a separate owner act.
+ */
 import * as Schema from "effect/Schema";
 import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
 import { type Release } from "@fungi.computer/puffball";
-import { type TeamAppCandidateSubmission } from "./build/submission-contract.js";
-import { type PublisherR2Bucket } from "./build/r2-artifact-writer.js";
-import { type ArtifactStore } from "./release.js";
-/** A Computer's whole-build budget: a cold standard-2 build measured 185-270 s. */
+import { type TeamAppCandidateManifest } from "./build/submission-contract.js";
+import { type ArtifactHeads, type ArtifactStore } from "./release.js";
+import type { PublisherTemplateSeedReceipts } from "./source/seed-receipt.js";
+/** A Computer's whole-build budget: a cold build on a 6 GiB Computer measured 185-270 s. */
 export declare const oysterAppBuildTimeoutMs = 900000;
 /** Host names the Computer's egress serves for a build; never public hosts. */
 export declare const oysterBuildGitHost = "git.team.internal";
 export declare const oysterBuildReportHost = "build.team.internal";
-/** An App's registered build source: one repository and its pinned recipe. */
-export declare const oysterBuildSourceSchema: Schema.Struct<{
-    readonly appId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
+/** Where an App's source is cloned from. */
+export declare const oysterBuildLocationSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"installation">;
     /** The installation whose Git holds the repository (Bonsai for a fork). */
     readonly installationId: Schema.String;
     readonly repository: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"template">;
+}>]>;
+export type OysterBuildLocation = Schema.Schema.Type<typeof oysterBuildLocationSchema>;
+/** An App's registered build source: where it is cloned and its pinned recipe. */
+export declare const oysterBuildSourceSchema: Schema.Struct<{
+    readonly appId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
+    readonly location: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"installation">;
+        /** The installation whose Git holds the repository (Bonsai for a fork). */
+        readonly installationId: Schema.String;
+        readonly repository: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"template">;
+    }>]>;
     readonly recipe: Schema.Struct<{
         readonly kind: Schema.optional<Schema.Literals<readonly ["bundled-html", "source-html"]>>;
         readonly bundle: Schema.Literal<true>;
@@ -54,9 +87,10 @@ export type OysterBuildView = Readonly<{
     detail: string | null;
     release: Release | null;
 }>;
-/** One Computer as the build owner reaches it. */
 export type OysterBuildComputer = Readonly<{
-    /** Run the fixed build command; the Computer re-admits the job first. */
+    /** 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. */
     runBuild(input: {
         jobId: string;
         command: string;
@@ -78,19 +112,27 @@ export type OysterAppBuildOptions = Readonly<{
         objectId: string;
         port: OysterBuildComputer;
     }>;
-    bucket: PublisherR2Bucket;
-    artifacts: ArtifactStore;
+    /** The host's artifact store; a build's objects are already in it. */
+    artifacts: ArtifactStore & ArtifactHeads;
+    /** The seed receipts a template build must match. */
+    templates: Pick<PublisherTemplateSeedReceipts, "read">;
     now?: () => number;
 }>;
-/** The SQLite tables one Oyster build owner keeps. */
-export declare function migrateOysterAppBuilds(owner: WatchdogSqliteOwner["sql"]): void;
-/** The build owner over one tenant's SQLite, Computer and Release bucket. */
+/**
+ * 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.
+ */
+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;
     readSource: (appId: 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
+     * recipe.
      * Answers the job and its one run, which the caller keeps alive (the
      * upload grant exists only inside that run's fixed command).
      */
@@ -128,6 +170,11 @@ export declare function createOysterAppBuilds(options: OysterAppBuildOptions): R
     }>): Readonly<{
         requestedBy: string;
     }> | null;
+    /**
+     * May this Computer's clone read this template repository now? Only while
+     * a live template job on this Computer names it.
+     */
+    admitTemplateClone(computerObjectId: string, repository: string): boolean;
     /** A reported artifact or status for a live job. */
     record(event: Readonly<{
         kind: "build-artifact";
@@ -143,9 +190,21 @@ export declare function createOysterAppBuilds(options: OysterAppBuildOptions): R
         detail: string | null;
     }>): void;
     /**
-     * The Computer's candidate for a live job: checked against the job, written
-     * by the shared R2 writer, verified as an installable Release and recorded.
+     * May this live job's build upload one object now, and how large? The
+     * grant is the one inside the job's fixed command; the bound is its
+     * recipe's (`pinnedRecipeObjectBound`).
+     */
+    admitObjectUpload(jobId: string, computerObjectId: string, grant: string): Promise<Readonly<{
+        maxObjectBytes: number;
+    }> | null>;
+    /**
+     * The Computer's candidate manifest for a live job: checked against the
+     * job and its pinned recipe, each named object found stored with its
+     * size and verified digest (one at a time; only the backend descriptor
+     * is read), its asset manifest and App root written, verified as an
+     * installable Release and recorded. An over-policy candidate stores
+     * nothing.
      */
-    submitCandidate(jobId: string, candidate: TeamAppCandidateSubmission, grant: string, credentialId: string): Promise<Response>;
+    submitCandidate(jobId: string, manifest: TeamAppCandidateManifest, grant: string, credentialId: string): Promise<Response>;
 }>;
 export type OysterAppBuilds = ReturnType<typeof createOysterAppBuilds>;