Skip to content
Nacre0.1.0
API reference

app-directory

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/nacre/app-directory";

Exports

Section titled “Exports”
Kind Export Description
type alias AppAddress Decoded address of a default App or an installation.
type alias AppAuthorityEnforcement A host-reported authority change and its remaining work.
type alias AppDirectoryGill A Release-declared Gill carried by the host’s App directory. The named mapped type keeps consumer declarations attached to this public contract.
type alias AppDirectoryEntry An App directory row before host-specific permissions are attached.
type alias AppComputerOperation One operation an App may request for a Computer.
type alias AppComputerPermission Decoded Computer permission scope attached to an App directory entry.
type alias AppAgentPermission Decoded Agent permission scope attached to an App directory entry.
type alias AppGenerationPermissions Decoded generation permissions attached to an App directory entry.
type alias AppMarketplacePermissions Decoded marketplace permissions attached to an App directory entry.
type alias AppDirectory The host-resolved Team App directory and its permission projections.
type alias AppCatalog Parsed metadata returned by the read-only APPS.catalog binding.
constant appAddressSchema An App address selects a host default or a specific installation.
constant appAuthorityEnforcementSchema Host-reported progress of applying a revised App authority version.
constant appDirectoryEntrySchema Reusable App metadata supplied by an embedding host; it conveys no permissions.
constant appRoleSelectionSchema A host-resolved role selection; a surface address is not launch authority.
constant appComputerPermissionSchema App Computer permissions limited to selected Computers or the Team’s Computers.
constant appAgentPermissionSchema Agent directory and session operations an App may request from its host.
constant appGenerationPermissionsSchema Whether an App may use language-model and media generation services.
constant appMarketplacePermissionsSchema Whether an App may browse, buy, or install free marketplace entries.
constant appDirectoryResponseSchema A host’s Team App directory with its permission projection, parsed strictly by every consumer: an unknown field is a contract change both sides make.
constant appCatalogEntrySchema Read-only catalog metadata for one App, without host-specific role policy.
constant appCatalogResponseSchema Read-only desktop metadata; identities are surface addresses, never launch authority.
constant appCatalogBrokerResultSchema Complete APPS.catalog reply, including broker admission failures.
function addressKey() Stable identity of one App address across directory and settings views.

AppAddresstype alias

Section titled “AppAddress”
Signature
type AppAddress = z.output<typeof appAddressSchema>;

Decoded address of a default App or an installation.

AppAuthorityEnforcementtype alias

Section titled “AppAuthorityEnforcement”
Signature
type AppAuthorityEnforcement = z.output<typeof appAuthorityEnforcementSchema>;

A host-reported authority change and its remaining work.

AppDirectoryGilltype alias

Section titled “AppDirectoryGill”
Signature
type AppDirectoryGill = {
  [
    Field in keyof Schema.Schema.Type<typeof appDeclaredGillSchema>
  ]: Schema.Schema.Type<typeof appDeclaredGillSchema>[Field];
};

A Release-declared Gill carried by the host’s App directory. The named mapped type keeps consumer declarations attached to this public contract.

AppDirectoryEntrytype alias

Section titled “AppDirectoryEntry”
Signature
type AppDirectoryEntry = z.output<typeof appDirectoryEntrySchema>;

An App directory row before host-specific permissions are attached.

AppComputerOperationtype alias

Section titled “AppComputerOperation”
Signature
type AppComputerOperation = Extract<
  z.output<typeof appComputerPermissionSchema>,
  {
    kind: "all-team-computers";
  }
>["operations"][number];

One operation an App may request for a Computer.

AppComputerPermissiontype alias

Section titled “AppComputerPermission”
Signature
type AppComputerPermission = z.output<typeof appComputerPermissionSchema>;

Decoded Computer permission scope attached to an App directory entry.

AppAgentPermissiontype alias

Section titled “AppAgentPermission”
Signature
type AppAgentPermission = z.output<typeof appAgentPermissionSchema>;

Decoded Agent permission scope attached to an App directory entry.

AppGenerationPermissionstype alias

Section titled “AppGenerationPermissions”
Signature
type AppGenerationPermissions = z.output<typeof appGenerationPermissionsSchema>;

Decoded generation permissions attached to an App directory entry.

AppMarketplacePermissionstype alias

Section titled “AppMarketplacePermissions”
Signature
type AppMarketplacePermissions = z.output<
  typeof appMarketplacePermissionsSchema
>;

Decoded marketplace permissions attached to an App directory entry.

AppDirectorytype alias

Section titled “AppDirectory”
Signature
type AppDirectory = z.output<typeof appDirectoryResponseSchema>;

The host-resolved Team App directory and its permission projections.

AppCatalogtype alias

Section titled “AppCatalog”
Signature
type AppCatalog = z.output<typeof appCatalogResponseSchema>;

Parsed metadata returned by the read-only APPS.catalog binding.

appAddressSchemaconstant

Section titled “appAddressSchema”
Signature
const appAddressSchema: ZodLazy<
  ZodUnion<
    readonly [
      ZodObject<
        {
          kind: ZodLiteral<"default">;
          appId: ZodString;
        },
        $strict
      >,
      ZodObject<
        {
          kind: ZodLiteral<"installation">;
          installationId: ZodString;
        },
        $strict
      >,
    ]
  >
>;

An App address selects a host default or a specific installation.

appAuthorityEnforcementSchemaconstant

Section titled “appAuthorityEnforcementSchema”
Signature
const appAuthorityEnforcementSchema: ZodLazy<
  ZodObject<
    {
      requestId: ZodString;
      address: ZodLazy<
        ZodUnion<
          readonly [
            ZodObject<
              {
                kind: ZodLiteral<"default">;
                appId: ZodString;
              },
              $strict
            >,
            ZodObject<
              {
                kind: ZodLiteral<"installation">;
                installationId: ZodString;
              },
              $strict
            >,
          ]
        >
      >;
      authorityVersion: ZodNumber;
      state: ZodEnum<{
        unaffected: "unaffected";
        pending: "pending";
        applied: "applied";
        expired: "expired";
      }>;
      outstanding: ZodNumber;
    },
    $strict
  >
>;

Host-reported progress of applying a revised App authority version.

appDirectoryEntrySchemaconstant

Section titled “appDirectoryEntrySchema”
Signature
const appDirectoryEntrySchema: ZodObject<{
  address: ZodLazy<ZodUnion<readonly [ZodObject<{
     kind: ZodLiteral<"default">;
     appId: ZodString;
   }, $strict>, ZodObject<{
     kind: ZodLiteral<"installation">;
     installationId: ZodString;
  }, $strict>]>>;
  installationId: ZodNullable<ZodString>;
  surfaceId: ZodString;
  appId: ZodString;
  displayName: ZodOptional<ZodString>;
  icon: ZodOptional<ZodNullable<ZodString>>;
  releaseId: ZodNullable<ZodString>;
  authorityVersion: ZodNumber;
  enforcement: ZodNullable<ZodLazy<ZodObject<{
     requestId: ZodString;
     address: ZodLazy<ZodUnion<readonly [ZodObject<{
        kind: ...;
        appId: ...;
      }, $strict>, ZodObject<{
        kind: ...;
        installationId: ...;
     }, $strict>]>>;
     authorityVersion: ZodNumber;
     state: ZodEnum<{
        unaffected: "unaffected";
        pending: "pending";
        applied: "applied";
        expired: "expired";
     }>;
     outstanding: ZodNumber;
  }, $strict>>>;
  handlers: ZodArray<ZodLiteral<"file.open">>;
  roles: ZodArray<ZodString>;
  declaredCapabilities: ZodArray<ZodString>;
  calls: ZodOptional<ZodPipe<ZodUnknown, ZodTransform<readonly object[], unknown>>>;
  commands: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<Readonly<{
     id: string;
     title: string;
     category: string;
     description?: string;
     sigil?: string;
     projections?: Readonly<{
        bindings?: ... | ...;
        agent?: ... | ...;
        help?: ... | ...;
        menu?: ... | ...;
        palette?: ... | ...;
        slash?: ... | ...;
     }>;
  }>[], unknown[]>>;
  gills: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<AppDirectoryGill[], unknown[]>>;
  availability: ZodEnum<{
     available: "available";
     unavailable: "unavailable";
  }>;
  surface: ZodNullable<ZodObject<{
     stableRoute: ZodString;
  }, $strict>>;
  surfacePath: ZodString;
}, $strict>;

Reusable App metadata supplied by an embedding host; it conveys no permissions.

appRoleSelectionSchemaconstant

Section titled “appRoleSelectionSchema”
Signature
const appRoleSelectionSchema: ZodObject<
  {
    surfaceId: ZodNullable<ZodString>;
    chosen: ZodBoolean;
  },
  $strict
>;

A host-resolved role selection; a surface address is not launch authority.

appComputerPermissionSchemaconstant

Section titled “appComputerPermissionSchema”
Signature
const appComputerPermissionSchema: ZodDiscriminatedUnion<[ZodLazy<ZodObject<{
  kind: ZodLiteral<"selected-computers">;
  computers: ZodArray<ZodObject<{
     computerId: ZodString;
     operations: ZodArray<ZodEnum<{
        computer.list: ...;
        computer.readFile: ...;
        computer.writeFile: ...;
        computer.execute: ...;
     }>>;
  }, $strict>>;
}, $strict>>, ZodLazy<ZodObject<{
  kind: ZodLiteral<"all-team-computers">;
  operations: ZodArray<ZodEnum<{
     computer.list: "computer.list";
     computer.readFile: "computer.readFile";
     computer.writeFile: "computer.writeFile";
     computer.execute: "computer.execute";
  }>>;
}, $strict>>], "kind">;

App Computer permissions limited to selected Computers or the Team’s Computers.

appAgentPermissionSchemaconstant

Section titled “appAgentPermissionSchema”
Signature
const appAgentPermissionSchema: ZodDiscriminatedUnion<[ZodObject<{
  kind: ZodLiteral<"all-team-agents">;
  directoryOperations: ZodArray<ZodEnum<{
     agent.list: "agent.list";
  }>>;
  sessionOperations: ZodArray<ZodEnum<{
     agent.read: "agent.read";
     agent.send: "agent.send";
     agent.manage: "agent.manage";
  }>>;
}, $strict>, ZodObject<{
  kind: ZodLiteral<"selected-agents">;
  directoryOperations: ZodArray<ZodEnum<{
     agent.list: "agent.list";
  }>>;
  agents: ZodArray<ZodObject<{
     agentId: ZodString;
     sessionOperations: ZodArray<ZodEnum<{
        agent.read: "agent.read";
        agent.send: "agent.send";
        agent.manage: "agent.manage";
     }>>;
  }, $strict>>;
}, $strict>], "kind">;

Agent directory and session operations an App may request from its host.

appGenerationPermissionsSchemaconstant

Section titled “appGenerationPermissionsSchema”
Signature
const appGenerationPermissionsSchema: ZodObject<
  {
    llm: ZodBoolean;
    media: ZodBoolean;
  },
  $strict
>;

Whether an App may use language-model and media generation services.

appMarketplacePermissionsSchemaconstant

Section titled “appMarketplacePermissionsSchema”
Signature
const appMarketplacePermissionsSchema: ZodObject<
  {
    browse: ZodBoolean;
    purchase: ZodBoolean;
    installFree: ZodBoolean;
  },
  $strict
>;

Whether an App may browse, buy, or install free marketplace entries.

appDirectoryResponseSchemaconstant

Section titled “appDirectoryResponseSchema”
Signature
const appDirectoryResponseSchema: ZodLazy<ZodObject<{
  actorIsTeamOwner: ZodBoolean;
  needsUpdate: ZodOptional<ZodArray<ZodObject<{
     installationId: ZodNullable<ZodString>;
     appId: ZodNullable<ZodString>;
     displayName: ZodString;
  }, $strict>>>;
  apps: ZodArray<ZodObject<{
     address: ZodLazy<ZodUnion<readonly [ZodObject<{
        kind: ...;
        appId: ...;
      }, $strict>, ZodObject<{
        kind: ...;
        installationId: ...;
     }, $strict>]>>;
     installationId: ZodNullable<ZodString>;
     surfaceId: ZodString;
     appId: ZodString;
     displayName: ZodOptional<ZodString>;
     icon: ZodOptional<ZodNullable<ZodString>>;
     releaseId: ZodNullable<ZodString>;
     authorityVersion: ZodNumber;
     enforcement: ZodNullable<ZodLazy<ZodObject<{
        requestId: ZodString;
        address: ZodLazy<...>;
        authorityVersion: ZodNumber;
        state: ZodEnum<...>;
        outstanding: ZodNumber;
     }, $strict>>>;
     handlers: ZodArray<ZodLiteral<"file.open">>;
     roles: ZodArray<ZodString>;
     declaredCapabilities: ZodArray<ZodString>;
     calls: ZodOptional<ZodPipe<ZodUnknown, ZodTransform<readonly object[], unknown>>>;
     commands: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<Readonly<{
        id: ...;
        title: ...;
        category: ...;
        description?: ...;
        sigil?: ...;
        projections?: ...;
     }>[], unknown[]>>;
     gills: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<AppDirectoryGill[], unknown[]>>;
     availability: ZodEnum<{
        available: "available";
        unavailable: "unavailable";
     }>;
     surface: ZodNullable<ZodObject<{
        stableRoute: ZodString;
     }, $strict>>;
     surfacePath: ZodString;
     override: ZodNullable<ZodObject<{
        appId: ZodOptional<ZodString>;
        releaseId: ZodString;
        surfaceRoute: ZodNullable<ZodString>;
     }, $strict>>;
     grants: ZodArray<ZodObject<{
        operation: ZodString;
        resourceId: ZodString;
     }, $strict>>;
     computerPermission: ZodOptional<ZodNullable<ZodDiscriminatedUnion<[ZodLazy<...>, ZodLazy<...>], "kind">>>;
     generationPermissions: ZodObject<{
        llm: ZodBoolean;
        media: ZodBoolean;
     }, $strict>;
     marketplacePermissions: ZodObject<{
        browse: ZodBoolean;
        purchase: ZodBoolean;
        installFree: ZodBoolean;
     }, $strict>;
     agentPermission: ZodDiscriminatedUnion<[ZodObject<{
        kind: ZodLiteral<...>;
        directoryOperations: ZodArray<...>;
        sessionOperations: ZodArray<...>;
      }, $strict>, ZodObject<{
        kind: ZodLiteral<...>;
        directoryOperations: ZodArray<...>;
        agents: ZodArray<...>;
     }, $strict>], "kind">;
  }, $strict>>;
  roles: ZodRecord<ZodString, ZodObject<{
     surfaceId: ZodNullable<ZodString>;
     chosen: ZodBoolean;
  }, $strict>>;
}, $strict>>;

A host’s Team App directory with its permission projection, parsed strictly by every consumer: an unknown field is a contract change both sides make.

appCatalogEntrySchemaconstant

Section titled “appCatalogEntrySchema”
Signature
const appCatalogEntrySchema: ZodObject<{
  surfaceId: ZodString;
  appId: ZodString;
  displayName: ZodOptional<ZodString>;
  gills: ZodArray<ZodObject<{
     id: ZodString;
     title: ZodString;
     params: ZodOptional<ZodLazy<ZodArray<ZodObject<{
        key: ...;
        label: ...;
        kind: ...;
        required: ...;
        options: ...;
     }, $strict>> & ZodType<readonly object[], object[], $ZodTypeInternals<readonly ...[], ...[]>>>>;
     desktop: ZodOptional<ZodObject<{
        sizes: ZodArray<ZodEnum<{
           S: ...;
           M: ...;
           L: ...;
        }>>;
     }, $strict>>;
  }, $strict>>;
}, $strict>;

Read-only catalog metadata for one App, without host-specific role policy.

appCatalogResponseSchemaconstant

Section titled “appCatalogResponseSchema”
Signature
const appCatalogResponseSchema: ZodLazy<ZodObject<{
  apps: ZodArray<ZodObject<{
     surfaceId: ZodString;
     appId: ZodString;
     displayName: ZodOptional<ZodString>;
     gills: ZodArray<ZodObject<{
        id: ZodString;
        title: ZodString;
        params: ZodOptional<ZodLazy<...>>;
        desktop: ZodOptional<ZodObject<..., ...>>;
     }, $strict>>;
  }, $strict>>;
  roles: ZodObject<{
     inbox: ZodOptional<ZodObject<{
        surfaceId: ZodNullable<ZodString>;
        chosen: ZodBoolean;
     }, $strict>>;
  }, $strict>;
}, $strict>>;

Read-only desktop metadata; identities are surface addresses, never launch authority.

appCatalogBrokerResultSchemaconstant

Section titled “appCatalogBrokerResultSchema”
Signature
const appCatalogBrokerResultSchema: ZodLazy<ZodUnion<readonly [ZodLazy<ZodObject<{
  apps: ZodArray<ZodObject<{
     surfaceId: ZodString;
     appId: ZodString;
     displayName: ZodOptional<ZodString>;
     gills: ZodArray<ZodObject<..., ...>>;
  }, $strict>>;
  roles: ZodObject<{
     inbox: ZodOptional<ZodObject<{
        surfaceId: ...;
        chosen: ...;
     }, $strict>>;
  }, $strict>;
}, $strict>>, ZodObject<{
  error: ZodString;
}, $strict>]>>;

Complete APPS.catalog reply, including broker admission failures.

addressKey()function

Section titled “addressKey()”
Signature
function addressKey(address): string;

Stable identity of one App address across directory and settings views.

Parameters

Section titled “Parameters”
Parameter Type
address | { kind: "default"; appId: string; } | { kind: "installation"; installationId: string; }

Returns

Section titled “Returns”

string