knapsack

Import

Import

import * as api from "@fungi.computer/knapsack";

Exports

Kind	Export	Description
Cclass	FilesEditError	Expected Files edit refusal, kept distinct from unexpected host failures.
Cclass	ComputerUnavailableError	One Computer whose advertisement could not be acquired.
Cclass	McpServerUnavailableError	One MCP server whose tools could not be acquired.
Ttype alias	FilesEditErrorReason	Typed refusal from a bounded or conditional Files edit.
Ttype alias	FilesPatch	Host-owned native patch operation receiving the invocation’s deadline and signal.
Ttype alias	FilesPort	Captured host file authority; the host owns path confinement and atomic replacement.
Ttype alias	FileToolName	Closed set of direct, model-visible Files tools; changing it is an ADR.
Ttype alias	FileTool	A MuleTool minted only by this module, named from the closed FileToolName set. No host can construct one: the brand has no public constructor, so a host-made MuleTool fails typecheck against files?.
Ttype alias	FilesSurface	One Mycelium module and the direct Files tools built from the same port.
Ttype alias	FilesConnectionOptions	Host inputs for a captured Files connection.
Ttype alias	KnapsackComputer	Generic advertised-call interface supplied by one Computer provider.
Ttype alias	ComputerConnectionOptions	Selection and naming required to connect one Computer to Mycelium.
Ttype alias	ComputerUnavailableReason	Why one Computer contributed no module to an acquisition.
Ttype alias	ComputersConnectionOptions	A captured host connection list; authority remains with its supplying host.
Ttype alias	McpServerConnection	One remote MCP server a host has admitted for an Agent.
Ttype alias	McpServersConnectionOptions	A captured host list of remote MCP servers; authority stays with the host.
Ttype alias	McpServerUnavailableReason	Why one MCP server contributed no module to an acquisition.
Ttype alias	UiConnectionOptions	How one Agent host connects its Sessions’ open Apps to Knapsack.ui.
Ttype alias	UiConnection	Live commands of the App open in each Agent Session’s browser. The Agent reaches them through the ui module (ui.discover, ui.execute); the browser runs them through Whistle over the transport this connection serves.
constconstant	listInputSchema	List one directory level.
constconstant	globInputSchema	Match paths below a directory by glob.
constconstant	grepInputSchema	Search file content, optionally restricted to matching paths.
constconstant	searchOutputSchema	Found paths or matching lines, and which cap (if any) cut the search short.
constconstant	editInputSchema	Text replacement request decoded before the captured Files port is called.
constconstant	filesEditFailureSchema	Structured edit refusal, including its reason and affected path.
constconstant	editOutputSchema	Successful edit metadata or a typed edit refusal.
constconstant	Knapsack	Agent tool connections available for composition through Mycelium.
fnfunction	edit()	Apply the same edit behavior as the Files edit operation directly through a captured FilesPort.
fnfunction	presentReadForGuest()	Guest code and MCP callers never receive base64: the image goes through the execution’s image collector (the images.view path) and the value is a caption.

FilesEditErrorCclass

Expected Files edit refusal, kept distinct from unexpected host failures.

Extends

• Error

Constructors

Constructor

Signature

new FilesEditError(
   reason,
   path,
   detail
): FilesEditError;

Parameters

Parameter	Type
reason	FilesEditErrorReason
path	string
detail	string

Returns

FilesEditError

Overrides

Signature

Error.constructor;

Properties

reason

Signature

readonly reason: FilesEditErrorReason;

path

Signature

readonly path: string;

---

ComputerUnavailableErrorCclass

One Computer whose advertisement could not be acquired.

Extends

• Error

Constructors

Constructor

Signature

new ComputerUnavailableError(
   computerId,
   reason,
   cause?
): ComputerUnavailableError;

Parameters

Parameter	Type
computerId	string
reason	ComputerUnavailableReason
cause?	unknown

Returns

ComputerUnavailableError

Overrides

Signature

Error.constructor;

Properties

name

Signature

readonly name: "ComputerUnavailableError" = "ComputerUnavailableError";

Overrides

Signature

Error.name;

computerId

Signature

readonly computerId: string;

reason

Signature

readonly reason: ComputerUnavailableReason;

---

McpServerUnavailableErrorCclass

One MCP server whose tools could not be acquired.

Extends

• Error

Constructors

Constructor

Signature

new McpServerUnavailableError(
   serverId,
   reason,
   cause?
): McpServerUnavailableError;

Parameters

Parameter	Type
serverId	string
reason	McpServerUnavailableReason
cause?	unknown

Returns

McpServerUnavailableError

Overrides

Signature

Error.constructor;

Properties

name

Signature

readonly name: "McpServerUnavailableError" = "McpServerUnavailableError";

Overrides

Signature

Error.name;

serverId

Signature

readonly serverId: string;

reason

Signature

readonly reason: McpServerUnavailableReason;

FilesEditErrorReasonTtype alias

Signature

type FilesEditErrorReason =
  | "not-found"
  | "ambiguous"
  | "file-too-large"
  | "partial-character"
  | "unchanged"
  | "not-text"
  | "conflict";

Typed refusal from a bounded or conditional Files edit.

---

FilesPatchTtype alias

Signature

type FilesPatch = (
  input,
  context,
) => Promise<z.output<typeof patchOutputSchema>>;

Host-owned native patch operation receiving the invocation’s deadline and signal.

Parameters

Parameter	Type
input	z.output<typeof patchInputSchema>
context	InvocationContext

Returns

Promise<z.output<typeof patchOutputSchema>>

---

FilesPortTtype alias

Signature

type FilesPort = Readonly<{
  patch?: FilesPatch;
  read: (input, context) => Promise<z.output<typeof readOutputSchema>>;
  list: (input, context) => Promise<z.output<typeof searchOutputSchema>>;
  glob: (input, context) => Promise<z.output<typeof searchOutputSchema>>;
  grep: (input, context) => Promise<z.output<typeof searchOutputSchema>>;
  replace: (
    input,
    context,
  ) => Promise<
    Readonly<{
      path: string;
      bytes: number;
    }>
  >;
}>;

Captured host file authority; the host owns path confinement and atomic replacement.

---

FileToolNameTtype alias

Signature

type FileToolName = "read" | "list" | "glob" | "grep" | "apply_patch";

Closed set of direct, model-visible Files tools; changing it is an ADR.

---

FileToolTtype alias

Signature

type FileTool = LabelledTool &
  Readonly<{
    [fileToolBrand]: true;
  }> &
  Readonly<{
    descriptor: Readonly<{
      name: FileToolName;
    }>;
    module: "files";
    access: Access;
  }>;

A MuleTool minted only by this module, named from the closed FileToolName set. No host can construct one: the brand has no public constructor, so a host-made MuleTool fails typecheck against files?.

---

FilesSurfaceTtype alias

Signature

type FilesSurface = Readonly<{
  module: ModuleRegistration;
  tools: readonly FileTool[];
}>;

One Mycelium module and the direct Files tools built from the same port.

---

FilesConnectionOptionsTtype alias

Signature

type FilesConnectionOptions = Readonly<{
  port: FilesPort;
  pathInstructions?: string;
}>;

Host inputs for a captured Files connection.

---

KnapsackComputerTtype alias

Signature

type KnapsackComputer = Readonly<{
  getCapabilities: (signal) => Promise<MyceliumJsonValue>;
  call: (capabilityId, input, context) => Promise<MyceliumJsonValue>;
}>;

Generic advertised-call interface supplied by one Computer provider.

---

ComputerConnectionOptionsTtype alias

Signature

type ComputerConnectionOptions = Readonly<{
  id: string;
  name: string;
  namespace?: readonly string[];
  confirmCalls?: boolean;
  files?: FilesConnectionOptions;
  role?: string;
  computer: KnapsackComputer;
}>;

Selection and naming required to connect one Computer to Mycelium.

---

ComputerUnavailableReasonTtype alias

Signature

type ComputerUnavailableReason =
  "rejected" | "timeout" | "invalid-advertisement";

Why one Computer contributed no module to an acquisition.

---

ComputersConnectionOptionsTtype alias

Signature

type ComputersConnectionOptions = Readonly<{
  id: string;
  read: () => Readonly<{
    version: string;
    connections: readonly ComputerConnectionOptions[];
  }>;
  subscribe: (invalidate) => () => void;
  onUnavailable: (error) => void;
  describeTimeoutMillis?: number;
}>;

A captured host connection list; authority remains with its supplying host.

---

McpServerConnectionTtype alias

Signature

type McpServerConnection = Readonly<{
  id: string;
  name: string;
  url: URL;
  headers?: Readonly<Record<string, string>>;
}>;

One remote MCP server a host has admitted for an Agent.

---

McpServersConnectionOptionsTtype alias

Signature

type McpServersConnectionOptions = Readonly<{
  id: string;
  read: () => Promise<
    Readonly<{
      version: string;
      servers: readonly McpServerConnection[];
    }>
  >;
  subscribe: (invalidate) => () => void;
  onUnavailable: (error) => void;
  fetch: (url, init?) => Promise<Response>;
  namespace?: readonly string[];
  connectTimeoutMillis?: number;
}>;

A captured host list of remote MCP servers; authority stays with the host.

---

McpServerUnavailableReasonTtype alias

Signature

type McpServerUnavailableReason =
  "rejected" | "unauthorized" | "timeout" | "invalid-advertisement";

Why one MCP server contributed no module to an acquisition.

---

UiConnectionOptionsTtype alias

Signature

type UiConnectionOptions = Readonly<{
  id: string;
  hasSession: (sessionId) => Promise<boolean>;
}>;

How one Agent host connects its Sessions’ open Apps to Knapsack.ui.

---

UiConnectionTtype alias

Signature

type UiConnection = Readonly<{
  source: CapabilitySource;
  fetch: (request) => Promise<Response>;
  close: () => Promise<void>;
}>;

Live commands of the App open in each Agent Session’s browser. The Agent reaches them through the ui module (ui.discover, ui.execute); the browser runs them through Whistle over the transport this connection serves.

listInputSchemaconstconstant

Signature

const listInputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodDefault<ZodLazy<ZodString>>;
      limit: ZodDefault<ZodNumber>;
    },
    $strict
  >
>;

List one directory level.

---

globInputSchemaconstconstant

Signature

const globInputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodDefault<ZodLazy<ZodString>>;
      pattern: ZodString;
      limit: ZodDefault<ZodNumber>;
    },
    $strict
  >
>;

Match paths below a directory by glob.

---

grepInputSchemaconstconstant

Signature

const grepInputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodDefault<ZodLazy<ZodString>>;
      pattern: ZodString;
      include: ZodOptional<ZodString>;
      regex: ZodDefault<ZodBoolean>;
      ignoreCase: ZodDefault<ZodBoolean>;
      limit: ZodDefault<ZodNumber>;
    },
    $strict
  >
>;

Search file content, optionally restricted to matching paths.

---

searchOutputSchemaconstconstant

Signature

const searchOutputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodLazy<ZodString>;
      results: ZodArray<
        ZodLazy<
          ZodObject<
            {
              path: ZodLazy<ZodString>;
              type: ZodExactOptional<
                ZodEnum<{
                  file: "file";
                  directory: "directory";
                  symlink: "symlink";
                }>
              >;
              line: ZodExactOptional<ZodNumber>;
              text: ZodExactOptional<ZodString>;
            },
            $strict
          >
        >
      >;
      truncated: ZodNullable<
        ZodEnum<{
          limit: "limit";
          scan: "scan";
        }>
      >;
    },
    $strict
  >
>;

Found paths or matching lines, and which cap (if any) cut the search short.

---

editInputSchemaconstconstant

Signature

const editInputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodLazy<ZodString>;
      oldText: ZodString;
      newText: ZodString;
    },
    $strict
  >
>;

Text replacement request decoded before the captured Files port is called.

---

filesEditFailureSchemaconstconstant

Signature

const filesEditFailureSchema: ZodLazy<ZodObject<{
  status: ZodLiteral<"failed">;
  error: ZodObject<{
     kind: ZodEnum<{
        not-found: "not-found";
        ambiguous: "ambiguous";
        file-too-large: "file-too-large";
        partial-character: "partial-character";
        unchanged: "unchanged";
        not-text: "not-text";
        conflict: "conflict";
     }>;
     path: ZodLazy<ZodString>;
     message: ZodString;
  }, $strict>;
}, $strict>>;

Structured edit refusal, including its reason and affected path.

---

editOutputSchemaconstconstant

Signature

const editOutputSchema: ZodUnion<readonly [ZodLazy<ZodObject<{
  path: ZodLazy<ZodString>;
  bytes: ZodNumber;
  diff: ZodString;
  firstChangedLine: ZodNullable<ZodNumber>;
  unifiedPatch: ZodNullable<ZodString>;
  unifiedPatchBytes: ZodNumber;
  unifiedPatchAddedLines: ZodNumber;
  unifiedPatchRemovedLines: ZodNumber;
  unifiedPatchTruncated: ZodBoolean;
}, $strict>>, ZodLazy<ZodObject<{
  status: ZodLiteral<"failed">;
  error: ZodObject<{
     kind: ZodEnum<{
        not-found: "not-found";
        ambiguous: "ambiguous";
        file-too-large: "file-too-large";
        partial-character: "partial-character";
        unchanged: "unchanged";
        not-text: "not-text";
        conflict: "conflict";
     }>;
     path: ZodLazy<ZodString>;
     message: ZodString;
  }, $strict>;
}, $strict>>]>;

Successful edit metadata or a typed edit refusal.

---

Knapsackconstconstant

Signature

const Knapsack: Readonly<{
  computer: (input) => CapabilitySource;
  computers: (input) => CapabilitySource;
  files: (input) => FilesSurface;
  mcpServers: (input) => CapabilitySource;
  ui: (options) => UiConnection;
}>;

Agent tool connections available for composition through Mycelium.

edit()fnfunction

Signature

function edit(
  port,
  input,
  context,
): Promise<
  | {
      path: string;
      bytes: number;
      diff: string;
      firstChangedLine: number | null;
      unifiedPatch: string | null;
      unifiedPatchBytes: number;
      unifiedPatchAddedLines: number;
      unifiedPatchRemovedLines: number;
      unifiedPatchTruncated: boolean;
    }
  | {
      status: "failed";
      error: {
        kind:
          | "not-found"
          | "ambiguous"
          | "file-too-large"
          | "partial-character"
          | "unchanged"
          | "not-text"
          | "conflict";
        path: string;
        message: string;
      };
    }
>;

Apply the same edit behavior as the Files edit operation directly through a captured FilesPort.

Parameters

Parameter	Type
port	FilesPort
input	{ path: string; oldText: string; newText: string; }
input.path	string
input.oldText	string
input.newText	string
context	InvocationContext

Returns

Promise< | { path: string; bytes: number; diff: string; firstChangedLine: number | null; unifiedPatch: string | null; unifiedPatchBytes: number; unifiedPatchAddedLines: number; unifiedPatchRemovedLines: number; unifiedPatchTruncated: boolean; } | { status: "failed"; error: { kind: | "not-found" | "ambiguous" | "file-too-large" | "partial-character" | "unchanged" | "not-text" | "conflict"; path: string; message: string; }; }>

---

presentReadForGuest()fnfunction

Signature

function presentReadForGuest(
  result,
  context,
):
  | {
      path: string;
      content: string;
      offset: number;
      nextOffset: number | null;
      truncated: boolean;
      file?: {
        computerId: string;
        path: string;
      };
    }
  | {
      path: string;
      image: {
        ref: string;
        mimeType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
        bytes: number;
      };
    };

Guest code and MCP callers never receive base64: the image goes through the execution’s image collector (the images.view path) and the value is a caption.

Parameters

Parameter	Type
result	| { path: string; content: string; offset: number; nextOffset: number | null; truncated: boolean; file?: { computerId: string; path: string; }; } | { path: string; image: { mimeType: "image/png" | "image/jpeg" | "image/gif" | "image/webp"; data: string; bytes: number; }; file?: { computerId: string; path: string; }; }
context	InvocationContext

Returns

Type Literal

Signature

{
  path: string;
  content: string;
  offset: number;
  nextOffset: number | null;
  truncated: boolean;
  file?: {
     computerId: string;
     path: string;
  };
}

Name	Type	Default value	Description
path	string	pathSchema	-
content	string	-	-
offset	number	-	-
nextOffset	number | null	-	-
truncated	boolean	-	-
file?	object	-	Captured hosted file identity; a local Files host may have no Computer identity.
file.computerId	string	-	-
file.path	string	-	-

---

Type Literal

Signature

{
  path: string;
  image: {
    ref: string;
    mimeType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
    bytes: number;
  }
}

References

readInputSchema

Re-exports readInputSchema

---

readOutputSchema

Re-exports readOutputSchema

---

readGuestOutputSchema

Re-exports readGuestOutputSchema

---

patchInputSchema

Re-exports patchInputSchema

---

patchOutputSchema

Re-exports patchOutputSchema