@fungi.computer/agar 0.6.1 → 0.7.0

package/README.md

@@ -9,7 +9,7 @@ methods, connects its frontend to a host through typed capabilities, and gives
 App builders selected context, host-rendered permission requests and explicit
 cleanup. The host and resource owners authorize the work; the same App runs on
 Fungi's hosted Teams or on any host that composes
-[Oyster](https://oyster.shiit.app).
+[Oyster](https://github.com/fungi-computer/oyster).
 
 ## Install or set up
 

package/dist/agents.d.ts

@@ -56,14 +56,31 @@ export declare const appAgentListResultSchema: z.ZodLazy<z.ZodObject<{
         name: z.ZodString;
     }, z.core.$strict>>;
 }, z.core.$strict>>;
-/** Computer provisioning is a Team creation choice, separate from Home policy. */
-export declare const appAgentComputerSchema: Schema.Literals<readonly ["new", "none"]>;
+/**
+ * Computer provisioning is a Team creation choice, separate from Home policy:
+ * a new Computer, none, or one of the Team's existing Computers.
+ */
+export declare const appAgentComputerSchema: Schema.Union<readonly [Schema.Literals<readonly ["new", "none"]>, Schema.Struct<{
+    readonly computerId: Schema.String;
+}>]>;
+/** The creation-time Computer choice for a new Agent. */
+export type AppAgentComputer = Schema.Schema.Type<typeof appAgentComputerSchema>;
+/** One existing Team Computer a new Agent may start on. */
+export declare const appAgentComputerChoiceSchema: Schema.Struct<{
+    readonly computerId: Schema.String;
+    readonly name: Schema.String;
+    readonly createdAt: Schema.Number;
+}>;
+/** An existing Team Computer offered when creating an Agent. */
+export type AppAgentComputerChoice = Schema.Schema.Type<typeof appAgentComputerChoiceSchema>;
 /** Validates Agent creation input: a name, a caller-chosen request id, an
  * optional Computer provisioning choice and an optional chosen avatar. */
 export declare const appAgentCreateInputSchema: Schema.Struct<{
     readonly name: Schema.String;
     readonly requestId: Schema.String;
-    readonly computer: Schema.optionalKey<Schema.Literals<readonly ["new", "none"]>>;
+    readonly computer: Schema.optionalKey<Schema.Union<readonly [Schema.Literals<readonly ["new", "none"]>, Schema.Struct<{
+        readonly computerId: Schema.String;
+    }>]>>;
     readonly avatar: Schema.optionalKey<Schema.declare<{
         v: 1;
         character: "mushroom" | "cat" | "burger";
@@ -102,6 +119,8 @@ export type AppAgentListHandle = {
 export type AppAgentCreateHandle = {
     /** Create a new Agent with the given name and request id. */
     create(input: AppAgentCreateInput): Promise<AppAgent>;
+    /** The Team Computers a new Agent may use; null when the host offers no choice. */
+    computers(): Promise<readonly AppAgentComputerChoice[] | null>;
 };
 /**
  * Live capability handle for listing and creating Agents in a Team or
@@ -118,7 +137,7 @@ export type AppAgentDirectoryHandle = AppAgentListHandle & AppAgentCreateHandle
 /** Capability to list the Agents visible to this App in read-only form. */
 export declare const agentList: CapabilityContract<AppAgentListHandle>;
 /** Capability to create new Agents and open transports to them. */
-export declare const agentManage: CapabilityContract<Pick<AppAgentDirectoryHandle, "create" | "open">>;
+export declare const agentManage: CapabilityContract<Pick<AppAgentDirectoryHandle, "create" | "computers" | "open">>;
 /** Validates Agent rename input: the target Agent and its new display name. */
 export declare const appAgentRenameInputSchema: Schema.Struct<{
     readonly agentId: Schema.String;
@@ -217,6 +236,11 @@ export declare const agentSessionWrite: CapabilityContract<Pick<AppAgentDirector
 export declare function listAppAgents(capabilities: CapabilityDirectory): Promise<readonly AppAgent[]>;
 /** Create an Agent through the Team directory selected by the host. */
 export declare function createAppAgent(capabilities: CapabilityDirectory, input: AppAgentCreateInput): Promise<AppAgent>;
+/**
+ * The Team Computers a new Agent may use, newest first, or null when the host
+ * makes no creation-time Computer choice.
+ */
+export declare function listAppAgentComputers(capabilities: CapabilityDirectory): Promise<readonly AppAgentComputerChoice[] | null>;
 /**
  * A Fetch-based transport to one Agent's session endpoint, scoped to
  * this App and safe to hand to an HTTP client adapter.

package/dist/agents.js

@@ -28,8 +28,26 @@ export const appAgentSchema = Schema.Struct({
 export const appAgentListResultSchema = z.lazy(() => z.strictObject({
     agents: z.array(z.strictObject({ agentId: z.string(), name: z.string() })),
 }));
-/** Computer provisioning is a Team creation choice, separate from Home policy. */
-export const appAgentComputerSchema = Schema.Literals(["new", "none"]);
+/**
+ * Computer provisioning is a Team creation choice, separate from Home policy:
+ * a new Computer, none, or one of the Team's existing Computers.
+ */
+export const appAgentComputerSchema = Schema.Union([
+    Schema.Literals(["new", "none"]),
+    Schema.Struct({ computerId: boundedIdentity }),
+]);
+/** One existing Team Computer a new Agent may start on. */
+export const appAgentComputerChoiceSchema = Schema.Struct({
+    computerId: boundedIdentity,
+    name: boundedIdentity,
+    createdAt: Schema.Number.pipe(Schema.check(Schema.isInt())),
+});
+/**
+ * The host's existing Computers for a new Agent, or null when the host makes
+ * no creation-time Computer choice at all.
+ */
+const appAgentComputerChoicesSchema = Schema.NullOr(Schema.Array(appAgentComputerChoiceSchema));
+const decodeComputerChoices = Schema.decodeUnknownSync(appAgentComputerChoicesSchema, { onExcessProperty: "error" });
 /** Validates Agent creation input: a name, a caller-chosen request id, an
  * optional Computer provisioning choice and an optional chosen avatar. */
 export const appAgentCreateInputSchema = Schema.Struct({
@@ -51,6 +69,7 @@ export const agentList = defineCapability("agent.list", 1, z.lazy(() => rpcHandl
 /** Capability to create new Agents and open transports to them. */
 export const agentManage = defineCapability("agent.manage", 1, z.lazy(() => rpcHandleSchema({
     open: rpcMethod(rpcFetchHandleSchema),
+    computers: rpcMethod(rpcDataSchema(z.unknown().transform((value) => decodeComputerChoices(value)))),
     create: rpcMethod(rpcDataSchema(z
         .unknown()
         .transform((value) => Schema.decodeUnknownSync(appAgentSchema)(value)))),
@@ -127,6 +146,16 @@ export async function createAppAgent(capabilities, input) {
     const agent = await capabilities.require(agentManage).create(request);
     return Schema.decodeUnknownSync(appAgentSchema)(agent);
 }
+/**
+ * The Team Computers a new Agent may use, newest first, or null when the host
+ * makes no creation-time Computer choice.
+ */
+export async function listAppAgentComputers(capabilities) {
+    const choices = decodeComputerChoices(await capabilities.require(agentManage).computers());
+    return choices === null
+        ? null
+        : [...choices].sort((a, b) => b.createdAt - a.createdAt);
+}
 /** Keep read and write handles separate while owning their shared connection lifetime. */
 async function openOperationHandles(openRead, openWrite) {
     const read = await openRead();

package/dist/computer.d.ts

@@ -20,7 +20,7 @@ export declare const computerList: CapabilityContract<{
     }): Promise<ComputerListing>;
 }>;
 export declare const computerRuntimeStateSchema: Schema.Union<readonly [Schema.Struct<{
-    readonly state: Schema.Literals<readonly ["running", "sleeping", "starting"]>;
+    readonly state: Schema.Literals<readonly ["running", "sleeping", "starting", "start_failed"]>;
 }>, Schema.Struct<{
     readonly state: Schema.Literal<"queued">;
     readonly position: Schema.Number;
@@ -36,7 +36,7 @@ export declare const computerInstrumentSnapshotSchema: Schema.Struct<{
     readonly computerId: Schema.NonEmptyString;
     readonly name: Schema.NonEmptyString;
     readonly runtime: Schema.Union<readonly [Schema.Struct<{
-        readonly state: Schema.Literals<readonly ["running", "sleeping", "starting"]>;
+        readonly state: Schema.Literals<readonly ["running", "sleeping", "starting", "start_failed"]>;
     }>, Schema.Struct<{
         readonly state: Schema.Literal<"queued">;
         readonly position: Schema.Number;

package/dist/computer.js

@@ -22,7 +22,8 @@ export const computerList = defineCapability("computer.list", 1, z.lazy(() => rp
 })));
 export const computerRuntimeStateSchema = Schema.Union([
     Schema.Struct({
-        state: Schema.Literals(["running", "sleeping", "starting"]),
+        // start_failed: a queued start ended without running; start again.
+        state: Schema.Literals(["running", "sleeping", "starting", "start_failed"]),
     }),
     Schema.Struct({
         state: Schema.Literal("queued"),

package/dist/inbox.d.ts

@@ -78,8 +78,8 @@ export declare function watchMemberInbox(options: Readonly<{
 export declare function readTeamInboxNoticePage(transport: Pick<AppAgentTransport, "baseUrl" | "fetch">, after?: string | null): Promise<{
     readonly items: readonly ({
         readonly appId: import("@fungi.computer/puffball").AppId;
-        readonly displayName: string;
         readonly createdAt: number;
+        readonly displayName: string;
         readonly dispositionId: string;
         readonly releaseIds: readonly import("@fungi.computer/puffball").ReleaseId[];
         readonly reason?: string | undefined;

package/dist/index.d.ts

@@ -6,8 +6,8 @@ export type { Pending } from "./pending.js";
 export type { CapabilityContract, CapabilityDirectory, CapabilityRegistry, } from "./capabilities.js";
 export { agentAvatar, agentList, agentManage, agentRename, agentSessionRead, agentSessionWrite, agentToolPolicy, createAppAgent, renameAppAgent, setAppAgentAvatar, appAgentAvatarInputSchema, appAgentAvatarSchema, appAgentCreateInputSchema, appAgentRenameInputSchema, appAgentSchema, appAgentToolPolicyResultSchema, appAgentToolPolicyStatusSchema, listAppAgents, openAppAgent, } from "./agents.js";
 export type { AppAgent, AppAgentAvatarHandle, AppAgentAvatarInput, AppAgentCreateHandle, AppAgentCreateInput, AppAgentDirectoryHandle, AppAgentListHandle, AppAgentRenameHandle, AppAgentRenameInput, AppAgentToolPolicyHandle, AppAgentToolPolicyResult, AppAgentToolPolicyStatus, AppAgentTransport, AppAgentTransportHandle, } from "./agents.js";
-export { mediaGeneration, mediaGenerationFailureSchema, mediaGenerationReferenceSchema, mediaGenerationSelectionSchema, mediaModelSchema, openMediaGeneration, } from "./media.js";
-export type { MediaGenerationHandle, MediaGenerationAttempt, MediaGenerationAttemptHandle, MediaGenerationFailure, MediaGenerationInput, MediaGenerationOutcome, MediaGenerationReference, MediaGenerationResult, MediaGenerationSelection, MediaModel, MediaOutputFormat, MediaGenerationSession, } from "./media.js";
+export { mediaGeneration, mediaGenerationFailureSchema, mediaGenerationReferenceSchema, mediaGenerationSelectionSchema, mediaModelSchema, mediaShare, mediaShareInputSchema, mediaShareStatusSchema, openMediaGeneration, } from "./media.js";
+export type { MediaShareHandle, MediaShareInput, MediaShareStatus, MediaGenerationHandle, MediaGenerationAttempt, MediaGenerationAttemptHandle, MediaGenerationFailure, MediaGenerationInput, MediaGenerationOutcome, MediaGenerationReference, MediaGenerationResult, MediaGenerationSelection, MediaModel, MediaOutputFormat, MediaGenerationSession, } from "./media.js";
 export type { AppCommand, AppCommandHandler, AppCommandInvocation, AppCommands, } from "./commands.js";
 export { registerCatalog } from "./commands.js";
 export { connectApp } from "./connect.js";

package/dist/index.js

@@ -2,7 +2,7 @@ export { FungiAuthorSchema, FungiDelegationReplySchema, FungiMessageMetaSchema,
 export { createCapabilityRegistry, defineCapability } from "./capabilities.js";
 export { pending, pendingSchema } from "./pending.js";
 export { agentAvatar, agentList, agentManage, agentRename, agentSessionRead, agentSessionWrite, agentToolPolicy, createAppAgent, renameAppAgent, setAppAgentAvatar, appAgentAvatarInputSchema, appAgentAvatarSchema, appAgentCreateInputSchema, appAgentRenameInputSchema, appAgentSchema, appAgentToolPolicyResultSchema, appAgentToolPolicyStatusSchema, listAppAgents, openAppAgent, } from "./agents.js";
-export { mediaGeneration, mediaGenerationFailureSchema, mediaGenerationReferenceSchema, mediaGenerationSelectionSchema, mediaModelSchema, openMediaGeneration, } from "./media.js";
+export { mediaGeneration, mediaGenerationFailureSchema, mediaGenerationReferenceSchema, mediaGenerationSelectionSchema, mediaModelSchema, mediaShare, mediaShareInputSchema, mediaShareStatusSchema, openMediaGeneration, } from "./media.js";
 export { registerCatalog } from "./commands.js";
 export { connectApp } from "./connect.js";
 /** Data exchanged by iframe and host before the RPC MessagePort takes over. */

package/dist/media.d.ts

@@ -1,3 +1,4 @@
+import * as z from "zod";
 import * as Schema from "effect/Schema";
 import type { MediaProviderDiagnostic } from "./errors.js";
 export { mediaLibraryRequestSchema, mediaLibraryPathSchema, mediaLibraryResponseSchema, } from "./media-library.js";
@@ -371,6 +372,38 @@ export declare const mediaGenerationFailureSchema: Schema.Struct<{
  * declare it to request access; openMediaGeneration uses it to obtain
  * the host's handle. */
 export declare const mediaGeneration: CapabilityContract<MediaGenerationHandle>;
+/** Whether one generated Print has a public link, and what that link shows. */
+export declare const mediaShareStatusSchema: z.ZodUnion<readonly [z.ZodObject<{
+    shared: z.ZodLiteral<false>;
+}, z.core.$strict>, z.ZodObject<{
+    shared: z.ZodLiteral<true>;
+    url: z.ZodURL;
+    showPrompt: z.ZodBoolean;
+}, z.core.$strict>]>;
+/** A Print's share state as the host reports it. */
+export type MediaShareStatus = z.output<typeof mediaShareStatusSchema>;
+/** Turn a public link on for one generated Print. */
+export declare const mediaShareInputSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    showPrompt: z.ZodBoolean;
+}, z.core.$strict>;
+/** What to share and whether to show its prompt. */
+export type MediaShareInput = z.output<typeof mediaShareInputSchema>;
+/** Host handle behind the `media.share` capability. */
+export type MediaShareHandle = Readonly<{
+    /** Read whether this Print has a live public link. */
+    status(requestId: string): Promise<MediaShareStatus>;
+    /** Turn a public link on; repeating it returns the live link unchanged. */
+    share(input: MediaShareInput): Promise<MediaShareStatus>;
+    /** Stop sharing; the link stops working at once. */
+    stop(requestId: string): Promise<MediaShareStatus>;
+}>;
+/**
+ * Capability contract for public links to generated Media. Off by default
+ * per output; the host keeps the link, the bytes it serves and who may change
+ * it.
+ */
+export declare const mediaShare: CapabilityContract<MediaShareHandle>;
 /** Decode and normalize a typed input envelope; storage parses the envelope first. */
 export declare function parseMediaGenerationInput(input: Schema.Schema.Type<typeof mediaGenerationInputWireSchema>): MediaGenerationInput;
 /** Discover the exact retained model catalog surfaced by the owner. */

package/dist/media.js

@@ -357,6 +357,33 @@ export const mediaGeneration = defineCapability("media.generation", 5, z.lazy(()
     restoreAttempt: rpcMethod(mediaAttemptHandleSchema),
     cancelAttempt: rpcVoid,
 })));
+/** Whether one generated Print has a public link, and what that link shows. */
+export const mediaShareStatusSchema = z.union([
+    z.strictObject({ shared: z.literal(false) }),
+    z.strictObject({
+        shared: z.literal(true),
+        /** The public, read-only page; anyone with it can see this one Print. */
+        url: z.url(),
+        /** The page shows the prompt only when its owner chose to. */
+        showPrompt: z.boolean(),
+    }),
+]);
+/** Turn a public link on for one generated Print. */
+export const mediaShareInputSchema = z.strictObject({
+    /** The generation's request identity (a Print's `printId`). */
+    requestId: z.string().min(1).max(256),
+    showPrompt: z.boolean(),
+});
+/**
+ * Capability contract for public links to generated Media. Off by default
+ * per output; the host keeps the link, the bytes it serves and who may change
+ * it.
+ */
+export const mediaShare = defineCapability("media.share", 1, z.lazy(() => rpcHandleSchema({
+    status: rpcMethod(rpcDataSchema(mediaShareStatusSchema)),
+    share: rpcMethod(rpcDataSchema(mediaShareStatusSchema)),
+    stop: rpcMethod(rpcDataSchema(mediaShareStatusSchema)),
+})));
 /** Parse a value received from the host and turn schema failures into the
  * transport-safe Agar error used by the other capability helpers. */
 function decode(schema, value) {

package/dist/query.d.ts

@@ -37,8 +37,8 @@ export declare function useMemberInbox(app: QueryApp | null): {
         readonly agentId: string;
         readonly sessionId: string;
         readonly title: string;
-        readonly state: "running" | "done" | "needs_you" | "errored";
         readonly createdAt: number;
+        readonly state: "running" | "done" | "needs_you" | "errored";
         readonly lastActivityAt: number;
         readonly triggerId?: string | undefined;
         readonly settledAt?: number | undefined;

package/dist/test-kit/git.js

@@ -13,50 +13,41 @@ export function realGit() {
     const info = (name) => existsSync(join(root, `${name}.git`))
         ? { name, defaultBranch: "main", lastPushAt: null, source: null }
         : null;
+    const gitOutput = (name, ...args) => execFileSync("git", [`--git-dir=${join(root, `${name}.git`)}`, ...args], {
+        encoding: "utf8",
+        // A thousand-commit log page is over execFileSync's 1 MiB default.
+        maxBuffer: 256 * 1024 * 1024,
+    });
     // A full object id names an immutable commit, so one read serves every
     // later ask; refs and abbreviations move and are never cached.
     const commits = new Map();
     const immutable = (hash) => /^[0-9a-f]{40,64}$/u.test(hash);
-    const readCommit = (name, hash) => {
+    const cacheKey = (name, hash) => {
         // The repository's directory identity keeps a deleted-and-recreated name
         // from serving the old repository's commits, however it was removed.
         const dir = statSync(join(root, `${name}.git`), {
             bigint: true,
             throwIfNoEntry: false,
         });
-        const key = `${name}\0${String(dir?.ino)}\0${String(dir?.birthtimeNs)}\0${hash}`;
-        const cached = immutable(hash) ? commits.get(key) : undefined;
+        return `${name}\0${String(dir?.ino)}\0${String(dir?.birthtimeNs)}\0${hash}`;
+    };
+    const remember = (name, commit) => {
+        commits.set(cacheKey(name, commit.hash), structuredClone(commit));
+    };
+    const readCommit = (name, hash) => {
+        const cached = immutable(hash)
+            ? commits.get(cacheKey(name, hash))
+            : undefined;
         if (cached !== undefined)
             return structuredClone(cached);
         const found = spawnSync("git", [`--git-dir=${join(root, `${name}.git`)}`, "cat-file", "-t", hash], { encoding: "utf8" });
         if (found.status !== 0 || found.stdout.trim() !== "commit")
             return null;
-        const [oid, treeHash, parents, authorName, authorEmail, committerName, committerEmail, authoredAt, committedAt, message,] = z
-            .tuple([
-            z.string(),
-            z.string(),
-            z.string(),
-            z.string(),
-            z.string(),
-            z.string(),
-            z.string(),
-            z.string(),
-            z.string(),
-            z.string(),
-        ])
-            .parse(run(name, "show", "-s", "--format=%H%x00%T%x00%P%x00%an%x00%ae%x00%cn%x00%ce%x00%at%x00%ct%x00%B", hash).split("\0"));
-        const commit = {
-            hash: oid,
-            treeHash,
-            parents: parents ? parents.split(" ") : [],
-            author: { name: authorName, email: authorEmail },
-            committer: { name: committerName, email: committerEmail },
-            authoredAt: Number(authoredAt),
-            committedAt: Number(committedAt),
-            message,
-        };
+        const commit = parseCommits(gitOutput(name, "show", "-s", "-z", `--format=${COMMIT_FORMAT}`, hash)).at(0);
+        if (!commit)
+            throw new Error("Commit unreadable");
         if (immutable(hash))
-            commits.set(key, structuredClone(commit));
+            remember(name, commit);
         return commit;
     };
     const git = {
@@ -93,15 +84,11 @@ export function realGit() {
         log: (name, { ref, limit = 50, offset = 0 }) => {
             if (!readCommit(name, ref))
                 return Promise.resolve([]);
-            return Promise.resolve(run(name, "rev-list", "--first-parent", `--max-count=${String(limit)}`, `--skip=${String(offset)}`, ref)
-                .split("\n")
-                .filter(Boolean)
-                .map((hash) => {
-                const commit = readCommit(name, hash);
-                if (!commit)
-                    throw new Error("Commit disappeared");
-                return commit;
-            }));
+            // One walk with the same rev-list flags reads every page commit.
+            const page = parseCommits(gitOutput(name, "log", "-z", `--format=${COMMIT_FORMAT}`, "--first-parent", `--max-count=${String(limit)}`, `--skip=${String(offset)}`, ref));
+            for (const commit of page)
+                remember(name, commit);
+            return Promise.resolve(page);
         },
         readTree: (name, hash) => Promise.resolve(run(name, "ls-tree", "-z", hash)
             .split("\0")
@@ -189,3 +176,42 @@ export function realGit() {
         },
     };
 }
+// Ten NUL-separated fields per commit; `-z` ends each commit with NUL too.
+const COMMIT_FORMAT = "%H%x00%T%x00%P%x00%an%x00%ae%x00%cn%x00%ce%x00%at%x00%ct%x00%B";
+const COMMIT_FIELDS = 10;
+const commitFields = z.tuple([
+    z.string(),
+    z.string(),
+    z.string(),
+    z.string(),
+    z.string(),
+    z.string(),
+    z.string(),
+    z.string(),
+    z.string(),
+    z.string(),
+]);
+function parseCommits(output) {
+    const fields = output.split("\0");
+    // The final commit's NUL terminator leaves one empty trailing field.
+    if (fields.at(-1) === "")
+        fields.pop();
+    if (fields.length % COMMIT_FIELDS !== 0)
+        throw new Error("Unexpected git commit format");
+    const parsed = [];
+    for (let start = 0; start < fields.length; start += COMMIT_FIELDS) {
+        const [oid, treeHash, parents, authorName, authorEmail, committerName, committerEmail, authoredAt, committedAt, message,] = commitFields.parse(fields.slice(start, start + COMMIT_FIELDS));
+        parsed.push({
+            hash: oid,
+            treeHash,
+            parents: parents ? parents.split(" ") : [],
+            author: { name: authorName, email: authorEmail },
+            committer: { name: committerName, email: committerEmail },
+            authoredAt: Number(authoredAt),
+            committedAt: Number(committedAt),
+            // %B keeps the raw message's trailing newline; readers see it trimmed.
+            message: message.trimEnd(),
+        });
+    }
+    return parsed;
+}

package/docs/api/backend-definition.md

@@ -228,9 +228,9 @@ Define a typed method once; neither discovery nor builds execute its handler.
 
 #### Parameters
 
-| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `method`  | `Omit`\<`Readonly`\<\{ `description`: `string`; `effect`: `"external"` \| `"read"` \| `"write"`; `requires`: readonly ( \| `"agent.list"` \| `"agent.manage"` \| `"agent.read"` \| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"approvals"` \| `"apps.open"` \| `"apps.call"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`)[]; `hidden?`: `true`; `pending?`: `true`; `present?`: `Readonly`\<\{ `verb`: `string`; \}\>; \}\>, `"present"`\> & \{ input: I; output: O; present?: Readonly\<\{ verb: string; row: (call: Readonly\<\{ input: output\<I\>; output: output\<O\>; \}\>) =\> \{ readonly id: string; readonly title: string; ... 4 more ...; readonly media?: \{ ...; \} \| undefined; \}; rows: Readonly\<...\>; \}\> \| undefined; \} & (\{ ...; \} \| \{ ...; \}) |
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `method`  | `Omit`\<`Readonly`\<\{ `description`: `string`; `effect`: `"external"` \| `"read"` \| `"write"`; `requires`: readonly ( \| `"agent.list"` \| `"agent.manage"` \| `"agent.read"` \| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"approvals"` \| `"apps.open"` \| `"apps.call"` \| `"llm.generation"` \| `"media.generation"` \| `"media.share"` \| `"games:servers"` \| `"git.repository"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`)[]; `hidden?`: `true`; `pending?`: `true`; `present?`: `Readonly`\<\{ `verb`: `string`; \}\>; \}\>, `"present"`\> & \{ input: I; output: O; present?: Readonly\<\{ verb: string; row: (call: Readonly\<\{ input: output\<I\>; output: output\<O\>; \}\>) =\> \{ readonly id: string; readonly title: string; ... 4 more ...; readonly media?: \{ ...; \} \| undefined; \}; rows: Readonly\<...\>; \}\> \| undefined; \} & (\{ ...; \} \| \{ ...; \}) |
 
 #### Returns
 

package/docs/api/index.md

@@ -235,6 +235,18 @@ Create a new Agent with the given name and request id.
 `"crt"`; `watercolor`: `"watercolor"`; \}\>; \}; `sessionOperations`: readonly
 (`"agent.manage"` \| `"agent.read"` \| `"agent.send"`)[]; \}\>
 
+##### computers()
+
+```ts
+computers(): Promise<readonly object[] | null>;
+```
+
+The Team Computers a new Agent may use; null when the host offers no choice.
+
+###### Returns
+
+`Promise`\<readonly `object`[] \| `null`\>
+
 ---
 
 ### AppAgentDirectoryHandle
@@ -1243,6 +1255,67 @@ and Computer-relative reference paths.
 
 ---
 
+### MediaShareStatus
+
+```ts
+type MediaShareStatus = z.output<typeof mediaShareStatusSchema>;
+```
+
+A Print's share state as the host reports it.
+
+---
+
+### MediaShareInput
+
+```ts
+type MediaShareInput = z.output<typeof mediaShareInputSchema>;
+```
+
+What to share and whether to show its prompt.
+
+---
+
+### MediaShareHandle
+
+```ts
+type MediaShareHandle = Readonly<{
+  status: Promise<
+    | {
+        shared: false;
+      }
+    | {
+        shared: true;
+        url: string;
+        showPrompt: boolean;
+      }
+  >;
+  share: Promise<
+    | {
+        shared: false;
+      }
+    | {
+        shared: true;
+        url: string;
+        showPrompt: boolean;
+      }
+  >;
+  stop: Promise<
+    | {
+        shared: false;
+      }
+    | {
+        shared: true;
+        url: string;
+        showPrompt: boolean;
+      }
+  >;
+}>;
+```
+
+Host handle behind the `media.share` capability.
+
+---
+
 ### Pending
 
 ```ts
@@ -2246,7 +2319,16 @@ Agent has an avatar: the one its owner chose, else Sprite's
 const appAgentCreateInputSchema: Struct<{
   name: String;
   requestId: String;
-  computer: optionalKey<Literals<readonly ["new", "none"]>>;
+  computer: optionalKey<
+    Union<
+      readonly [
+        Literals<readonly ["new", "none"]>,
+        Struct<{
+          computerId: String;
+        }>,
+      ]
+    >
+  >;
   avatar: optionalKey<
     declare<
       {
@@ -2309,7 +2391,7 @@ Capability to list the Agents visible to this App in read-only form.
 
 ```ts
 const agentManage: CapabilityContract<
-  Pick<AppAgentDirectoryHandle, "create" | "open">
+  Pick<AppAgentDirectoryHandle, "create" | "computers" | "open">
 >;
 ```
 
@@ -2808,6 +2890,60 @@ request access; openMediaGeneration uses it to obtain the host's handle.
 
 ---
 
+### mediaShareStatusSchema
+
+```ts
+const mediaShareStatusSchema: ZodUnion<
+  readonly [
+    ZodObject<
+      {
+        shared: ZodLiteral<false>;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        shared: ZodLiteral<true>;
+        url: ZodURL;
+        showPrompt: ZodBoolean;
+      },
+      $strict
+    >,
+  ]
+>;
+```
+
+Whether one generated Print has a public link, and what that link shows.
+
+---
+
+### mediaShareInputSchema
+
+```ts
+const mediaShareInputSchema: ZodObject<
+  {
+    requestId: ZodString;
+    showPrompt: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Turn a public link on for one generated Print.
+
+---
+
+### mediaShare
+
+```ts
+const mediaShare: CapabilityContract<MediaShareHandle>;
+```
+
+Capability contract for public links to generated Media. Off by default per
+output; the host keeps the link, the bytes it serves and who may change it.
+
+---
+
 ### pendingSchema
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/agar",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "author": "Levi <levi@technomancy.dev>",
   "description": "App contract for fungi.computer: typed backend methods, host capabilities and the App frontend connection",
   "type": "module",
@@ -168,7 +168,7 @@
     }
   },
   "dependencies": {
-    "@fungi.computer/puffball": "0.4.0",
+    "@fungi.computer/puffball": "0.5.0",
     "@fungi.computer/whistle": "0.3.0",
     "@opentui/keymap": "0.5.10",
     "@fungi.computer/capnweb": "0.12.0",