Skip to content
Forage0.2.0
API reference

forage

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/forage";

Exports

Section titled “Exports”
Kind Export Description
class ForageError A bounded, machine-readable failure at a Forage public seam.
type alias ForageCatalog Immutable public facade for one prepared catalog revision.
type alias ForageDefinition Structural operation definition consumed by a capability composer.
type alias ForageApi Public convenience namespace contract.
type alias JsonSchemaTarget Options Forage passes when it asks a schema for its JSON Schema.
type alias JsonSchemaSource Any schema that describes itself through Standard JSON Schema: Zod 4 schemas natively, and Effect schemas through Mycelium. Forage only renders descriptions; validation stays with the schema’s owner.
type alias ForageSearchInput Parsed search request type.
type alias ForageListInput Exhaustive listing request type.
type alias ListOutput Exhaustive page response type.
type alias ForageDescribeInput Parsed description request type.
type alias SearchResult One ranked search result type.
type alias SearchOutput Search response envelope type.
type alias DescribeOutput Description response type.
type alias ForageFailure Typed failure value type.
type alias Operation Catalog operation descriptor type.
type alias CatalogInput Catalog construction input type.
constant forageSearchDefinition The search operation has schema metadata only; it has no host behavior.
constant forageDescribeDefinition The description operation has schema metadata only; it has no host behavior.
constant forageListDefinition Pure exhaustive catalog listing; no execution or authority is granted.
constant Forage Narrow convenience namespace for the package’s public seams.
constant forageSearchInput Input accepted by the pure catalog search seam.
constant forageDescribeInput Input accepted by the pure catalog description seam.
constant forageListInput Exhaustive listing request; cursor is scoped to one immutable catalog and filter.
constant searchResultSchema One ranked operation in a search response.
constant searchOutputSchema Bounded search response envelope.
constant listOutputSchema One exhaustive page, using the exact search operation summary schema.
constant describeOutputSchema Deterministic description response.
constant forageFailureSchema Closed failure vocabulary for malformed or absent catalog requests.
constant operationSchema A secret-free, callback-free operation descriptor.
constant catalogInputSchema Input used to construct one immutable catalog revision.
function jsonSchemaToZod() The shared JSON-Schema compiler for App methods and OpenAPI operations.
function appMethodSchemas() Compile App validators and their Standard JSON Schema descriptions. Validation enforces both the declaration and JSON-only values; discovery describes the declaration without adding JSON guard nesting. Agar’s emitted output already includes Pending for opted-in methods.
function appToolSchemas() Compile discoverable App methods only; direct RPC validation uses appMethodSchemas.
function appToolFamilySchemas() Decode the signed listing before compiling dynamic discovery schemas. Rows retain App-owned selectors as data. Hosts supply call admission and invocation arguments; this projection supplies neither defaults nor handlers.
function appApiOperations() Project an already decoded Release API into discovery data with the same paths the Agent catalog uses (PRINTS.generate, called as env.PRINTS.generate()). The introduction owner supplies the installation’s binding name; this function grants no access and supplies no execution handler. Role aliases can project the same API.
function createCatalog() Construct one immutable catalog revision with a narrow public facade.
function listOperations() Page a trusted immutable operation-summary view. Hosts may filter the existing catalog to their bound operations before paging; this is the one cursor owner. Order is namespace then full path, compared by UTF-16 code units, never locale. Unlike search, no equivalent operations are merged into peers.

ForageErrorclass

Section titled “ForageError”

A bounded, machine-readable failure at a Forage public seam.

Extends

Section titled “Extends”
  • Error

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new ForageError(
   code,
   message,
   options?
): ForageError;
Parameters
Section titled “Parameters”
Parameter Type
code | "empty_query" | "empty_catalog" | "unknown_target" | "duplicate_operation" | "invalid_input"
message string
options? ErrorOptions
Returns
Section titled “Returns”

ForageError

Overrides
Section titled “Overrides”
Signature
Error.constructor;

Properties

Section titled “Properties”

code

Section titled “code”
Signature
readonly code:
  | "empty_query"
  | "empty_catalog"
  | "unknown_target"
  | "duplicate_operation"
  | "invalid_input";

failure

Section titled “failure”
Signature
readonly failure: object;
code
Section titled “code”
Signature
code:
  | "empty_query"
  | "empty_catalog"
  | "unknown_target"
  | "duplicate_operation"
  | "invalid_input";
message
Section titled “message”
Signature
message: string;

ForageCatalogtype alias

Section titled “ForageCatalog”
Signature
type ForageCatalog = Readonly<{
  revision: string;
  search: (rawInput) => SearchOutput;
  describe: (rawInput) => DescribeOutput;
  list: (rawInput) => ListOutput;
  stamp: () => string;
}>;

Immutable public facade for one prepared catalog revision.

ForageDefinitiontype alias

Section titled “ForageDefinition”
Signature
type ForageDefinition = Readonly<{
  replay: "safe";
  path: string;
  description: string;
  input:
    | typeof forageSearchInput
    | typeof forageDescribeInput
    | typeof forageListInput;
  output:
    | typeof searchOutputSchema
    | typeof describeOutputSchema
    | typeof listOutputSchema;
}>;

Structural operation definition consumed by a capability composer.

ForageApitype alias

Section titled “ForageApi”
Signature
type ForageApi = object;

Public convenience namespace contract.

Properties

Section titled “Properties”

createCatalog

Section titled “createCatalog”
Signature
createCatalog: typeof createCatalog;

Construct one immutable catalog revision.

forageSearchDefinition

Section titled “forageSearchDefinition”
Signature
forageSearchDefinition: typeof forageSearchDefinition;

Structural search operation definition.

forageDescribeDefinition

Section titled “forageDescribeDefinition”
Signature
forageDescribeDefinition: typeof forageDescribeDefinition;

Structural description operation definition.

forageListDefinition

Section titled “forageListDefinition”
Signature
forageListDefinition: typeof forageListDefinition;

Structural exhaustive listing definition.

JsonSchemaTargettype alias

Section titled “JsonSchemaTarget”
Signature
type JsonSchemaTarget = Readonly<{
  target: "draft-2020-12";
}>;

Options Forage passes when it asks a schema for its JSON Schema.

JsonSchemaSourcetype alias

Section titled “JsonSchemaSource”
Signature
type JsonSchemaSource = Readonly<{
  ~standard: Readonly<{
     jsonSchema: Readonly<{
        input: (options) => object;
        output: (options) => object;
     }>;
  }>;
}>;

Any schema that describes itself through Standard JSON Schema: Zod 4 schemas natively, and Effect schemas through Mycelium. Forage only renders descriptions; validation stays with the schema’s owner.

ForageSearchInputtype alias

Section titled “ForageSearchInput”
Signature
type ForageSearchInput = z.input<typeof forageSearchInput>;

Parsed search request type.

ForageListInputtype alias

Section titled “ForageListInput”
Signature
type ForageListInput = z.input<typeof forageListInput>;

Exhaustive listing request type.

ListOutputtype alias

Section titled “ListOutput”
Signature
type ListOutput = z.infer<typeof listOutputSchema>;

Exhaustive page response type.

ForageDescribeInputtype alias

Section titled “ForageDescribeInput”
Signature
type ForageDescribeInput = z.input<typeof forageDescribeInput>;

Parsed description request type.

SearchResulttype alias

Section titled “SearchResult”
Signature
type SearchResult = z.infer<typeof searchResultSchema>;

One ranked search result type.

SearchOutputtype alias

Section titled “SearchOutput”
Signature
type SearchOutput = z.infer<typeof searchOutputSchema>;

Search response envelope type.

DescribeOutputtype alias

Section titled “DescribeOutput”
Signature
type DescribeOutput = z.infer<typeof describeOutputSchema>;

Description response type.

ForageFailuretype alias

Section titled “ForageFailure”
Signature
type ForageFailure = z.infer<typeof forageFailureSchema>;

Typed failure value type.

Operationtype alias

Section titled “Operation”
Signature
type Operation = z.infer<typeof operationSchema>;

Catalog operation descriptor type.

CatalogInputtype alias

Section titled “CatalogInput”
Signature
type CatalogInput = z.input<typeof catalogInputSchema>;

Catalog construction input type.

forageSearchDefinitionconstant

Section titled “forageSearchDefinition”
Signature
const forageSearchDefinition: ForageDefinition;

The search operation has schema metadata only; it has no host behavior.

forageDescribeDefinitionconstant

Section titled “forageDescribeDefinition”
Signature
const forageDescribeDefinition: ForageDefinition;

The description operation has schema metadata only; it has no host behavior.

forageListDefinitionconstant

Section titled “forageListDefinition”
Signature
const forageListDefinition: ForageDefinition;

Pure exhaustive catalog listing; no execution or authority is granted.

Forageconstant

Section titled “Forage”
Signature
const Forage: ForageApi;

Narrow convenience namespace for the package’s public seams.

forageSearchInputconstant

Section titled “forageSearchInput”
Signature
const forageSearchInput: ZodLazy<
  ZodObject<
    {
      query: ZodString;
      maxResults: ZodDefault<ZodNumber>;
    },
    $strip
  >
>;

Input accepted by the pure catalog search seam.

forageDescribeInputconstant

Section titled “forageDescribeInput”
Signature
const forageDescribeInput: ZodLazy<
  ZodObject<
    {
      path: ZodString;
      detail: ZodDefault<
        ZodEnum<{
          index: "index";
          full: "full";
        }>
      >;
      methods: ZodOptional<ZodArray<ZodString>>;
    },
    $strip
  >
>;

Input accepted by the pure catalog description seam.

forageListInputconstant

Section titled “forageListInput”
Signature
const forageListInput: ZodObject<
  {
    cursor: ZodOptional<ZodString>;
    limit: ZodDefault<ZodNumber>;
    namespace: ZodOptional<ZodString>;
  },
  $strip
>;

Exhaustive listing request; cursor is scoped to one immutable catalog and filter.

searchResultSchemaconstant

Section titled “searchResultSchema”
Signature
const searchResultSchema: ZodObject<
  {
    path: ZodString;
    description: ZodOptional<ZodString>;
    score: ZodNumber;
    matchReason: ZodOptional<ZodString>;
    sample: ZodOptional<ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>>;
    capabilityNotes: ZodOptional<ZodString>;
    peers: ZodOptional<
      ZodArray<
        ZodLazy<
          ZodObject<
            {
              path: ZodString;
              capabilityNotes: ZodOptional<ZodString>;
            },
            $strip
          >
        >
      >
    >;
  },
  $strip
>;

One ranked operation in a search response.

searchOutputSchemaconstant

Section titled “searchOutputSchema”
Signature
const searchOutputSchema: ZodLazy<ZodObject<{
  results: ZodArray<ZodObject<{
     path: ZodString;
     description: ZodOptional<ZodString>;
     score: ZodNumber;
     matchReason: ZodOptional<ZodString>;
     sample: ZodOptional<ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>>;
     capabilityNotes: ZodOptional<ZodString>;
     peers: ZodOptional<ZodArray<ZodLazy<ZodObject<{
        path: ...;
        capabilityNotes: ...;
     }, $strip>>>>;
  }, $strip>>;
  total: ZodNumber;
  truncated: ZodBoolean;
  topScore: ZodNumber;
  margin: ZodNumber;
  catalogStamp: ZodString;
}, $strip>>;

Bounded search response envelope.

listOutputSchemaconstant

Section titled “listOutputSchema”
Signature
const listOutputSchema: ZodObject<{
  results: ZodArray<ZodObject<{
     path: ZodString;
     description: ZodOptional<ZodString>;
     score: ZodNumber;
     matchReason: ZodOptional<ZodString>;
     sample: ZodOptional<ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>>;
     capabilityNotes: ZodOptional<ZodString>;
     peers: ZodOptional<ZodArray<ZodLazy<ZodObject<{
        path: ZodString;
        capabilityNotes: ZodOptional<...>;
     }, $strip>>>>;
  }, $strip>>;
  total: ZodNumber;
  nextCursor: ZodNullable<ZodString>;
  catalogStamp: ZodString;
}, $strip>;

One exhaustive page, using the exact search operation summary schema.

describeOutputSchemaconstant

Section titled “describeOutputSchema”
Signature
const describeOutputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodString;
      description: ZodOptional<ZodString>;
      types: ZodString;
      inputSchema: ZodOptional<ZodJSONSchema>;
      kind: ZodEnum<{
        module: "module";
        operation: "operation";
      }>;
      usage: ZodOptional<ZodString>;
    },
    $strip
  >
>;

Deterministic description response.

forageFailureSchemaconstant

Section titled “forageFailureSchema”
Signature
const forageFailureSchema: ZodLazy<
  ZodObject<
    {
      code: ZodEnum<{
        empty_query: "empty_query";
        empty_catalog: "empty_catalog";
        unknown_target: "unknown_target";
        duplicate_operation: "duplicate_operation";
        invalid_input: "invalid_input";
      }>;
      message: ZodString;
    },
    $strip
  >
>;

Closed failure vocabulary for malformed or absent catalog requests.

operationSchemaconstant

Section titled “operationSchema”
Signature
const operationSchema: ZodLazy<ZodObject<{
  path: ZodString;
  description: ZodOptional<ZodString>;
  input: ZodLazy<ZodCustom<Readonly<{
     ~standard: Readonly<{
        jsonSchema: Readonly<{
           input: ...;
           output: ...;
        }>;
     }>;
   }>, Readonly<{
     ~standard: Readonly<{
        jsonSchema: Readonly<{
           input: ...;
           output: ...;
        }>;
     }>;
  }>>>;
  output: ZodOptional<ZodLazy<ZodCustom<Readonly<{
     ~standard: Readonly<{
        jsonSchema: Readonly<...>;
     }>;
   }>, Readonly<{
     ~standard: Readonly<{
        jsonSchema: Readonly<...>;
     }>;
  }>>>>;
  capabilityNotes: ZodOptional<ZodString>;
  instructions: ZodOptional<ZodString>;
}, $strip>>;

A secret-free, callback-free operation descriptor.

catalogInputSchemaconstant

Section titled “catalogInputSchema”
Signature
const catalogInputSchema: ZodLazy<ZodObject<{
  revision: ZodString;
  operations: ZodArray<ZodLazy<ZodObject<{
     path: ZodString;
     description: ZodOptional<ZodString>;
     input: ZodLazy<ZodCustom<Readonly<{
        ~standard: ...;
      }>, Readonly<{
        ~standard: ...;
     }>>>;
     output: ZodOptional<ZodLazy<ZodCustom<Readonly<...>, Readonly<...>>>>;
     capabilityNotes: ZodOptional<ZodString>;
     instructions: ZodOptional<ZodString>;
  }, $strip>>>;
}, $strip>>;

Input used to construct one immutable catalog revision.

jsonSchemaToZod()function

Section titled “jsonSchemaToZod()”
Signature
function jsonSchemaToZod(
  source,
  defaultTarget?,
): ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>;

The shared JSON-Schema compiler for App methods and OpenAPI operations.

Parameters

Section titled “Parameters”
Parameter Type Default value
source unknown undefined
defaultTarget "draft-2020-12" | "openapi-3.0" "draft-2020-12"

Returns

Section titled “Returns”

ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

appMethodSchemas()function

Section titled “appMethodSchemas()”
Signature
function appMethodSchemas(api): object;

Compile App validators and their Standard JSON Schema descriptions. Validation enforces both the declaration and JSON-only values; discovery describes the declaration without adding JSON guard nesting. Agar’s emitted output already includes Pending for opted-in methods.

Parameters

Section titled “Parameters”
Parameter Type
api AppApi

Returns

Section titled “Returns”

object

appToolSchemas()function

Section titled “appToolSchemas()”
Signature
function appToolSchemas(api): object;

Compile discoverable App methods only; direct RPC validation uses appMethodSchemas.

Parameters

Section titled “Parameters”
Parameter Type
api AppApi

Returns

Section titled “Returns”

object

appToolFamilySchemas()function

Section titled “appToolFamilySchemas()”
Signature
function appToolFamilySchemas(
  api,
  reply,
): {
  name: string;
  call: string;
  effect: "write" | "external" | "read";
  requires: readonly (
    | "approvals"
    | "agent.list"
    | "agent.manage"
    | "agent.rename"
    | "agent.avatar"
    | "agent.toolPolicy"
    | "agent.read"
    | "agent.send"
    | "computer.list"
    | "computer.readFile"
    | "computer.writeFile"
    | "computer.execute"
    | "llm.generation"
    | "media.generation"
    | "games:servers"
    | "git.repository"
    | "apps.open"
    | "apps.call"
    | "app.storage"
    | "app.events.emit"
    | "team.workbenchHost"
    | "marketplace.browse"
    | "marketplace.purchase"
    | "workflow.run"
    | "workflow.publish"
    | "workflow.arm"
    | "world"
    | "channels.read"
    | "channels.personal.manage"
  )[];
  kind: "ready" | "unindexed";
  tools: object[];
} | null;

Decode the signed listing before compiling dynamic discovery schemas. Rows retain App-owned selectors as data. Hosts supply call admission and invocation arguments; this projection supplies neither defaults nor handlers.

Parameters

Section titled “Parameters”
Parameter Type
api AppApi
reply unknown

Returns

Section titled “Returns”

| { name: string; call: string; effect: "write" | "external" | "read"; requires: readonly ( | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage")[]; kind: "ready" | "unindexed"; tools: object[]; } | null

appApiOperations()function

Section titled “appApiOperations()”
Signature
function appApiOperations(name, api): readonly object[];

Project an already decoded Release API into discovery data with the same paths the Agent catalog uses (PRINTS.generate, called as env.PRINTS.generate()). The introduction owner supplies the installation’s binding name; this function grants no access and supplies no execution handler. Role aliases can project the same API.

Parameters

Section titled “Parameters”
Parameter Type
name string
api AppApi

Returns

Section titled “Returns”

readonly object[]

createCatalog()function

Section titled “createCatalog()”
Signature
function createCatalog(input): ForageCatalog;

Construct one immutable catalog revision with a narrow public facade.

Parameters

Section titled “Parameters”
Parameter Type
input { revision: string; operations: object[]; }
input.revision string
input.operations object[]

Returns

Section titled “Returns”

ForageCatalog

listOperations()function

Section titled “listOperations()”
Signature
function listOperations(operations, catalogStamp, rawInput): object;

Page a trusted immutable operation-summary view. Hosts may filter the existing catalog to their bound operations before paging; this is the one cursor owner. Order is namespace then full path, compared by UTF-16 code units, never locale. Unlike search, no equivalent operations are merged into peers.

Parameters

Section titled “Parameters”
Parameter Type
operations readonly object[]
catalogStamp string
rawInput { cursor?: string; limit?: number; namespace?: string; }
rawInput.cursor? string
rawInput.limit? number
rawInput.namespace? string

Returns

Section titled “Returns”

object

Name Type
results object[]
total number
nextCursor string | null
catalogStamp string

References

Section titled “References”

default

Section titled “default”

Renames and re-exports Forage