@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/channels.d.ts

@@ -0,0 +1,142 @@
+import * as z from "zod";
+/** The one versioned reply owner of a channel conversation. */
+export declare const handoffSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"agent">;
+    version: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"requested">;
+    version: z.ZodNumber;
+    reason: z.ZodString;
+    at: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"person">;
+    version: z.ZodNumber;
+    memberId: z.ZodString;
+    memberName: z.ZodString;
+    since: z.ZodNumber;
+}, z.core.$strict>], "state">;
+export type Handoff = z.output<typeof handoffSchema>;
+/** An addressed website binding; no visitor credentials or site keys. */
+export declare const appWebsiteSchema: z.ZodObject<{
+    bindingId: z.ZodString;
+    agentId: z.ZodString;
+    origins: z.ZodArray<z.ZodString>;
+    lifecycle: z.ZodEnum<{
+        suspended: "suspended";
+        active: "active";
+    }>;
+}, z.core.$strict>;
+/** Owner-projected takeover state for one website conversation. */
+export declare const appWebsiteConversationSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    label: z.ZodString;
+    lastEventAt: z.ZodNumber;
+    needsYou: z.ZodNullable<z.ZodObject<{
+        at: z.ZodNumber;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+    held: z.ZodBoolean;
+    heldByYou: z.ZodBoolean;
+    heldByName: z.ZodNullable<z.ZodString>;
+    holdVersion: z.ZodNumber;
+}, z.core.$strict>;
+/** The binding is selected by its owner, never by an Agent identity. */
+export declare const appWebsiteSelectionSchema: z.ZodObject<{
+    bindingId: z.ZodString;
+}, z.core.$strict>;
+/** An exact conversation under that binding. */
+export declare const appWebsiteConversationSelectionSchema: z.ZodObject<{
+    bindingId: z.ZodString;
+    sessionId: z.ZodString;
+}, z.core.$strict>;
+/** An idempotent member reply through the takeover owner, not Session.prompt. */
+export declare const appWebsiteReplySchema: z.ZodObject<{
+    bindingId: z.ZodString;
+    sessionId: z.ZodString;
+    requestId: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>;
+/** Take over or hand back only the handoff version the member observed. */
+export declare const handoffChangeSchema: z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    confirm: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const appWebsiteHoldSchema: z.ZodObject<{
+    bindingId: z.ZodString;
+    sessionId: z.ZodString;
+    expectedVersion: z.ZodNumber;
+    confirm: z.ZodBoolean;
+}, z.core.$strict>;
+/** Dismiss only an Agent's unanswered request for a person. */
+export declare const appWebsiteDismissSchema: z.ZodObject<{
+    bindingId: z.ZodString;
+    sessionId: z.ZodString;
+    expectedVersion: z.ZodNumber;
+}, z.core.$strict>;
+/** The bounded website directory returned by the channel owner. */
+export declare const appWebsitePageSchema: z.ZodObject<{
+    websites: z.ZodArray<z.ZodObject<{
+        bindingId: z.ZodString;
+        agentId: z.ZodString;
+        origins: z.ZodArray<z.ZodString>;
+        lifecycle: z.ZodEnum<{
+            suspended: "suspended";
+            active: "active";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** At most 100 recent conversations projected by the App host. */
+export declare const appWebsiteConversationPageSchema: z.ZodObject<{
+    conversations: z.ZodArray<z.ZodObject<{
+        sessionId: z.ZodString;
+        label: z.ZodString;
+        lastEventAt: z.ZodNumber;
+        needsYou: z.ZodNullable<z.ZodObject<{
+            at: z.ZodNumber;
+            reason: z.ZodString;
+        }, z.core.$strict>>;
+        held: z.ZodBoolean;
+        heldByYou: z.ZodBoolean;
+        heldByName: z.ZodNullable<z.ZodString>;
+        holdVersion: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AppWebsiteConversation = z.output<typeof appWebsiteConversationSchema>;
+/** Read-only channel data admitted to a member's App installation. */
+export type AppChannelsReadHandle = {
+    list(): Promise<z.output<typeof appWebsitePageSchema>>;
+    conversations(input: z.output<typeof appWebsiteSelectionSchema>): Promise<z.output<typeof appWebsiteConversationPageSchema>>;
+};
+/** Takeover actions keep the authenticated member and live grant on the host. */
+export type AppChannelsManageHandle = {
+    hold(input: z.output<typeof appWebsiteHoldSchema>): Promise<AppWebsiteConversation>;
+    release(input: z.output<typeof appWebsiteHoldSchema>): Promise<AppWebsiteConversation>;
+    dismiss(input: z.output<typeof appWebsiteDismissSchema>): Promise<AppWebsiteConversation>;
+    reply(input: z.output<typeof appWebsiteReplySchema>): Promise<Readonly<{
+        status: "sent";
+    }>>;
+};
+/** Response to a successful member takeover action. */
+export declare const appWebsiteActionResponseSchema: z.ZodObject<{
+    conversation: z.ZodObject<{
+        sessionId: z.ZodString;
+        label: z.ZodString;
+        lastEventAt: z.ZodNumber;
+        needsYou: z.ZodNullable<z.ZodObject<{
+            at: z.ZodNumber;
+            reason: z.ZodString;
+        }, z.core.$strict>>;
+        held: z.ZodBoolean;
+        heldByYou: z.ZodBoolean;
+        heldByName: z.ZodNullable<z.ZodString>;
+        holdVersion: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** A successful reply is recorded without starting an Agent turn. */
+export declare const appWebsiteReplyResponseSchema: z.ZodObject<{
+    status: z.ZodLiteral<"sent">;
+}, z.core.$strict>;
+/** Reading website conversations is never an automatic default-App grant. */
+export declare const channelsRead: import("./capabilities.js").CapabilityContract<AppChannelsReadHandle>;
+/** Member-only takeover; separate consent from read-only channel access. */
+export declare const channelsPersonalManage: import("./capabilities.js").CapabilityContract<AppChannelsManageHandle>;

package/dist/channels.js

@@ -0,0 +1,97 @@
+import * as z from "zod";
+import { defineCapability } from "./capabilities.js";
+import { rpcDataSchema, rpcHandleSchema, rpcMethod, } from "./internal/rpc-contract.js";
+const identity = z.string().min(1).max(256);
+const handoffVersion = z.number().int().nonnegative();
+/** The one versioned reply owner of a channel conversation. */
+export const handoffSchema = z.discriminatedUnion("state", [
+    z.strictObject({ state: z.literal("agent"), version: handoffVersion }),
+    z.strictObject({
+        state: z.literal("requested"),
+        version: handoffVersion,
+        reason: z.string().max(4000),
+        at: z.number().int().nonnegative(),
+    }),
+    z.strictObject({
+        state: z.literal("person"),
+        version: handoffVersion,
+        memberId: identity,
+        memberName: z.string().min(1).max(128),
+        since: z.number().int().nonnegative(),
+    }),
+]);
+/** An addressed website binding; no visitor credentials or site keys. */
+export const appWebsiteSchema = z.strictObject({
+    bindingId: identity,
+    agentId: identity,
+    origins: z.array(z.string().min(1).max(2048)).min(1).max(16),
+    lifecycle: z.enum(["active", "suspended"]),
+});
+/** Owner-projected takeover state for one website conversation. */
+export const appWebsiteConversationSchema = z.strictObject({
+    sessionId: identity,
+    label: z.string().max(4096),
+    lastEventAt: z.number().int().nonnegative(),
+    needsYou: z
+        .strictObject({
+        at: z.number().int().nonnegative(),
+        reason: z.string().max(4000),
+    })
+        .nullable(),
+    held: z.boolean(),
+    heldByYou: z.boolean(),
+    heldByName: z.string().min(1).max(128).nullable(),
+    holdVersion: z.number().int().nonnegative(),
+});
+/** The binding is selected by its owner, never by an Agent identity. */
+export const appWebsiteSelectionSchema = z.strictObject({
+    bindingId: identity,
+});
+/** An exact conversation under that binding. */
+export const appWebsiteConversationSelectionSchema = appWebsiteSelectionSchema.extend({
+    sessionId: identity,
+});
+/** An idempotent member reply through the takeover owner, not Session.prompt. */
+export const appWebsiteReplySchema = appWebsiteConversationSelectionSchema.extend({
+    requestId: z.string().min(1).max(128),
+    text: z.string().trim().min(1).max(4000),
+});
+/** Take over or hand back only the handoff version the member observed. */
+export const handoffChangeSchema = z.strictObject({
+    expectedVersion: handoffVersion,
+    confirm: z.boolean(),
+});
+export const appWebsiteHoldSchema = appWebsiteConversationSelectionSchema.extend(handoffChangeSchema.shape);
+/** Dismiss only an Agent's unanswered request for a person. */
+export const appWebsiteDismissSchema = appWebsiteConversationSelectionSchema.extend({
+    expectedVersion: handoffVersion,
+});
+/** The bounded website directory returned by the channel owner. */
+export const appWebsitePageSchema = z.strictObject({
+    websites: z.array(appWebsiteSchema).max(1000),
+});
+/** At most 100 recent conversations projected by the App host. */
+export const appWebsiteConversationPageSchema = z.strictObject({
+    conversations: z.array(appWebsiteConversationSchema).max(100),
+});
+const conversationResult = z.strictObject({
+    conversation: appWebsiteConversationSchema,
+});
+/** Response to a successful member takeover action. */
+export const appWebsiteActionResponseSchema = conversationResult;
+/** A successful reply is recorded without starting an Agent turn. */
+export const appWebsiteReplyResponseSchema = z.strictObject({
+    status: z.literal("sent"),
+});
+/** Reading website conversations is never an automatic default-App grant. */
+export const channelsRead = defineCapability("channels.read", 1, rpcHandleSchema({
+    list: rpcMethod(rpcDataSchema(appWebsitePageSchema)),
+    conversations: rpcMethod(rpcDataSchema(appWebsiteConversationPageSchema)),
+}));
+/** Member-only takeover; separate consent from read-only channel access. */
+export const channelsPersonalManage = defineCapability("channels.personal.manage", 1, rpcHandleSchema({
+    hold: rpcMethod(rpcDataSchema(appWebsiteConversationSchema)),
+    release: rpcMethod(rpcDataSchema(appWebsiteConversationSchema)),
+    dismiss: rpcMethod(rpcDataSchema(appWebsiteConversationSchema)),
+    reply: rpcMethod(rpcDataSchema(appWebsiteReplyResponseSchema)),
+}));

package/dist/commands.d.ts

@@ -0,0 +1,33 @@
+import type { Disposer } from "./store.js";
+import type { WhistleCommand, WhistleCommandDefinition, WhistleExecutionOrigin, WhistleJsonValue } from "@fungi.computer/whistle";
+/** Semantic command metadata supplied by an App and owned by Whistle. */
+export type AppCommand = WhistleCommandDefinition;
+/** One invocation's semantic input; host correlation IDs are private. */
+export type AppCommandHandler = (invocation: AppCommandInvocation) => Promise<WhistleJsonValue | undefined> | WhistleJsonValue | undefined;
+/** One command invocation's semantic input, passed to its handler. */
+export type AppCommandInvocation = {
+    readonly arguments?: WhistleJsonValue;
+    readonly origin: WhistleExecutionOrigin;
+    readonly signal: AbortSignal;
+};
+/**
+ * Registers a command with the authenticated host for this page session.
+ * The promise resolves only after the host accepts the registration.
+ */
+export type AppCommands = {
+    /** Register one command and its handler with the host; resolves once
+     * the host accepts it. Call the returned Disposer to unregister. */
+    register(command: AppCommand, handler: AppCommandHandler): Promise<Disposer>;
+};
+/**
+ * Register one App's Whistle catalog with its host. An App defines each
+ * command once, contributes the same catalog to its own composer runtime for
+ * slash commands, and registers it here so the shell projects it into the
+ * palette, menus, keys and the agent view. Availability is read once at
+ * registration; register again to publish a change.
+ *
+ * @param commands - The App's host command door, `app.commands`.
+ * @param catalog - The App's Whistle commands, handlers included.
+ * @returns Release every registration made by this call.
+ */
+export declare function registerCatalog(commands: AppCommands, catalog: readonly WhistleCommand<never>[]): Disposer;

package/dist/commands.js

@@ -0,0 +1,46 @@
+import { parseJsonValue } from "@fungi.computer/whistle/wire";
+/**
+ * Register one App's Whistle catalog with its host. An App defines each
+ * command once, contributes the same catalog to its own composer runtime for
+ * slash commands, and registers it here so the shell projects it into the
+ * palette, menus, keys and the agent view. Availability is read once at
+ * registration; register again to publish a change.
+ *
+ * @param commands - The App's host command door, `app.commands`.
+ * @param catalog - The App's Whistle commands, handlers included.
+ * @returns Release every registration made by this call.
+ */
+export function registerCatalog(commands, catalog) {
+    let released = false;
+    const releases = [];
+    for (const command of catalog) {
+        const { availability, handler, ...metadata } = command;
+        const run = handler;
+        const definition = availability === undefined
+            ? metadata
+            : { ...metadata, availability: availability() };
+        void commands
+            .register(definition, async ({ arguments: args, origin, signal }) => {
+            const input = args === undefined
+                ? { origin, signal }
+                : { arguments: args, origin, signal };
+            const result = await run(input);
+            return result === undefined ? undefined : parseJsonValue(result);
+        })
+            .then((release) => {
+            if (released)
+                release();
+            else
+                releases.push(release);
+        }, (cause) => {
+            console.warn(`App command ${command.id} was not registered`, cause);
+        });
+    }
+    return () => {
+        if (released)
+            return;
+        released = true;
+        for (const release of releases.splice(0))
+            release();
+    };
+}

package/dist/computer-contracts.d.ts

@@ -0,0 +1,73 @@
+import * as z from "zod";
+/** Public metadata for one host-admitted Workflow Git pass; parsing never grants authority. */
+export declare const workflowGitPassResultSchema: z.ZodObject<{
+    passId: z.ZodString;
+    remote: z.ZodURL;
+    expiresAt: z.ZodNumber;
+    bearer: z.ZodExactOptional<z.ZodString>;
+}, z.core.$strict>;
+/** The complete remote stays opaque; the host owns admission, renewal and revocation. */
+export type WorkflowGitPassResult = z.output<typeof workflowGitPassResultSchema>;
+/** Existing attachment budget operation kinds shared by Computer and Media. */
+export declare const connectorOperationBudgetKindSchema: z.ZodEnum<{
+    write: "write";
+    media: "media";
+    exec: "exec";
+}>;
+/** Existing owner budget refusal; it remains a domain result, not a wire envelope. */
+export declare const connectorOperationBudgetRefusalSchema: z.ZodObject<{
+    error: z.ZodLiteral<"attachment_budget_exceeded">;
+    kind: z.ZodEnum<{
+        write: "write";
+        media: "media";
+        exec: "exec";
+    }>;
+    retryAfterMs: z.ZodNumber;
+}, z.core.$strict>;
+/** Computer admission refusals returned before native dispatch. */
+export declare const appComputerAdmissionRefusalSchema: z.ZodUnion<readonly [z.ZodObject<{
+    error: z.ZodEnum<{
+        unavailable: "unavailable";
+        revoked: "revoked";
+        not_granted: "not_granted";
+        grantor_lost_authority: "grantor_lost_authority";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    error: z.ZodLiteral<"attachment_budget_exceeded">;
+    kind: z.ZodEnum<{
+        write: "write";
+        media: "media";
+        exec: "exec";
+    }>;
+    retryAfterMs: z.ZodNumber;
+}, z.core.$strict>]>;
+/** Existing Computer broker argument refusals. */
+export declare const appComputerInputRefusalSchema: z.ZodObject<{
+    error: z.ZodEnum<{
+        invalid: "invalid";
+        too_large: "too_large";
+        invalid_path: "invalid_path";
+    }>;
+}, z.core.$strict>;
+/** Existing Computer dispatch status/decoding refusals. */
+export declare const appComputerDispatchRefusalSchema: z.ZodObject<{
+    error: z.ZodEnum<{
+        unavailable: "unavailable";
+        conflict: "conflict";
+        not_granted: "not_granted";
+        too_large: "too_large";
+    }>;
+}, z.core.$strict>;
+/** An execution wait can time out while its durable request remains identifiable. */
+export declare const appComputerExecTimeoutSchema: z.ZodObject<{
+    error: z.ZodLiteral<"timeout">;
+    requestId: z.ZodString;
+}, z.core.$strict>;
+/** The Workflow Git-pass owner has exactly these existing domain refusals. */
+export declare const workflowGitPassRefusalSchema: z.ZodObject<{
+    error: z.ZodEnum<{
+        unavailable: "unavailable";
+        revoked: "revoked";
+        not_granted: "not_granted";
+    }>;
+}, z.core.$strict>;

package/dist/computer-contracts.js

@@ -0,0 +1,57 @@
+import * as z from "zod";
+/** Public metadata for one host-admitted Workflow Git pass; parsing never grants authority. */
+export const workflowGitPassResultSchema = z.strictObject({
+    passId: z.string().min(1),
+    remote: z.url({ protocol: /^https$/, abort: true }).refine((value) => {
+        const remote = new URL(value);
+        return remote.username === "" && remote.password === "";
+    }, "Workflow Git remotes must not contain credentials"),
+    expiresAt: z.number().int().positive(),
+    /**
+     * Present when the host admits this pass by `Authorization: Bearer` on the
+     * remote. It is never part of the remote; a command receives it only as
+     * command-local Git config, never written to a repository config.
+     */
+    bearer: z.string().min(1).exactOptional(),
+});
+/** Existing attachment budget operation kinds shared by Computer and Media. */
+export const connectorOperationBudgetKindSchema = z.enum([
+    "exec",
+    "write",
+    "media",
+]);
+/** Existing owner budget refusal; it remains a domain result, not a wire envelope. */
+export const connectorOperationBudgetRefusalSchema = z.strictObject({
+    error: z.literal("attachment_budget_exceeded"),
+    kind: connectorOperationBudgetKindSchema,
+    retryAfterMs: z.number(),
+});
+/** Computer admission refusals returned before native dispatch. */
+export const appComputerAdmissionRefusalSchema = z.union([
+    z.strictObject({
+        error: z.enum([
+            "revoked",
+            "not_granted",
+            "grantor_lost_authority",
+            "unavailable",
+        ]),
+    }),
+    connectorOperationBudgetRefusalSchema,
+]);
+/** Existing Computer broker argument refusals. */
+export const appComputerInputRefusalSchema = z.strictObject({
+    error: z.enum(["too_large", "invalid_path", "invalid"]),
+});
+/** Existing Computer dispatch status/decoding refusals. */
+export const appComputerDispatchRefusalSchema = z.strictObject({
+    error: z.enum(["not_granted", "too_large", "conflict", "unavailable"]),
+});
+/** An execution wait can time out while its durable request remains identifiable. */
+export const appComputerExecTimeoutSchema = z.strictObject({
+    error: z.literal("timeout"),
+    requestId: z.string(),
+});
+/** The Workflow Git-pass owner has exactly these existing domain refusals. */
+export const workflowGitPassRefusalSchema = z.strictObject({
+    error: z.enum(["revoked", "not_granted", "unavailable"]),
+});