@fungi.computer/knapsack 0.0.0-stage → 0.0.2

package/docs/api/index.md

@@ -0,0 +1,733 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/knapsack**](README.md)
+
+---
+
+[@fungi.computer/knapsack](README.md) / index
+
+# index
+
+## Classes
+
+### FilesEditError
+
+Expected Files edit refusal, kept distinct from unexpected host failures.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new FilesEditError(
+   reason,
+   path,
+   detail
+): FilesEditError;
+```
+
+###### Parameters
+
+| Parameter | Type                                            |
+| --------- | ----------------------------------------------- |
+| `reason`  | [`FilesEditErrorReason`](#filesediterrorreason) |
+| `path`    | `string`                                        |
+| `detail`  | `string`                                        |
+
+###### Returns
+
+[`FilesEditError`](#filesediterror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### reason
+
+```ts
+readonly reason: FilesEditErrorReason;
+```
+
+##### path
+
+```ts
+readonly path: string;
+```
+
+---
+
+### ComputerUnavailableError
+
+One Computer whose advertisement could not be acquired.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ComputerUnavailableError(
+   computerId,
+   reason,
+   cause?
+): ComputerUnavailableError;
+```
+
+###### Parameters
+
+| Parameter    | Type                                                      |
+| ------------ | --------------------------------------------------------- |
+| `computerId` | `string`                                                  |
+| `reason`     | [`ComputerUnavailableReason`](#computerunavailablereason) |
+| `cause?`     | `unknown`                                                 |
+
+###### Returns
+
+[`ComputerUnavailableError`](#computerunavailableerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### name
+
+```ts
+readonly name: "ComputerUnavailableError" = "ComputerUnavailableError";
+```
+
+###### Overrides
+
+```ts
+Error.name;
+```
+
+##### computerId
+
+```ts
+readonly computerId: string;
+```
+
+##### reason
+
+```ts
+readonly reason: ComputerUnavailableReason;
+```
+
+---
+
+### McpServerUnavailableError
+
+One MCP server whose tools could not be acquired.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new McpServerUnavailableError(
+   serverId,
+   reason,
+   cause?
+): McpServerUnavailableError;
+```
+
+###### Parameters
+
+| Parameter  | Type                                                        |
+| ---------- | ----------------------------------------------------------- |
+| `serverId` | `string`                                                    |
+| `reason`   | [`McpServerUnavailableReason`](#mcpserverunavailablereason) |
+| `cause?`   | `unknown`                                                   |
+
+###### Returns
+
+[`McpServerUnavailableError`](#mcpserverunavailableerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### name
+
+```ts
+readonly name: "McpServerUnavailableError" = "McpServerUnavailableError";
+```
+
+###### Overrides
+
+```ts
+Error.name;
+```
+
+##### serverId
+
+```ts
+readonly serverId: string;
+```
+
+##### reason
+
+```ts
+readonly reason: McpServerUnavailableReason;
+```
+
+## Type Aliases
+
+### FilesEditErrorReason
+
+```ts
+type FilesEditErrorReason =
+  | "not-found"
+  | "ambiguous"
+  | "file-too-large"
+  | "partial-character"
+  | "unchanged"
+  | "conflict";
+```
+
+Typed refusal from a bounded or conditional Files edit.
+
+---
+
+### FilesPatch
+
+```ts
+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`](files-patch.md#patchinputschema)\> |
+| `context` | `InvocationContext`                                                          |
+
+#### Returns
+
+`Promise`\<`z.output`\<_typeof_
+[`patchOutputSchema`](files-patch.md#patchoutputschema)\>\>
+
+---
+
+### FilesPort
+
+```ts
+type FilesPort = Readonly<{
+  patch?: FilesPatch;
+  read: (input, context) => Promise<z.output<typeof readOutputSchema>>;
+  list: (input, context) => Promise<z.output<typeof listOutputSchema>>;
+  glob: (input, context) => Promise<z.output<typeof globOutputSchema>>;
+  grep: (input, context) => Promise<z.output<typeof grepOutputSchema>>;
+  replace: (
+    input,
+    context,
+  ) => Promise<
+    Readonly<{
+      path: string;
+      bytes: number;
+    }>
+  >;
+}>;
+```
+
+Captured host file authority; the host owns path confinement and atomic
+replacement.
+
+---
+
+### FileToolName
+
+```ts
+type FileToolName = "read" | "list" | "glob" | "grep" | "apply_patch";
+```
+
+Closed set of direct, model-visible Files tools; widening one is an ADR.
+
+---
+
+### FileTool
+
+```ts
+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?`.
+
+---
+
+### FilesSurface
+
+```ts
+type FilesSurface = Readonly<{
+  module: ModuleRegistration;
+  tools: readonly FileTool[];
+}>;
+```
+
+One Mycelium module and the direct Files tools built from the same port.
+
+---
+
+### FilesConnectionOptions
+
+```ts
+type FilesConnectionOptions = Readonly<{
+  port: FilesPort;
+  pathInstructions?: string;
+}>;
+```
+
+Host inputs for a captured Files connection.
+
+---
+
+### KnapsackComputer
+
+```ts
+type KnapsackComputer = Readonly<{
+  getCapabilities: (signal) => Promise<MyceliumJsonValue>;
+  call: (capabilityId, input, context) => Promise<MyceliumJsonValue>;
+}>;
+```
+
+Generic advertised-call interface supplied by one Computer provider.
+
+---
+
+### ComputerConnectionOptions
+
+```ts
+type ComputerConnectionOptions = Readonly<{
+  id: string;
+  name: string;
+  namespace?: readonly string[];
+  files?: FilesConnectionOptions;
+  role?: string;
+  computer: KnapsackComputer;
+}>;
+```
+
+Selection and naming required to connect one Computer to Mycelium.
+
+---
+
+### ComputerUnavailableReason
+
+```ts
+type ComputerUnavailableReason =
+  "rejected" | "timeout" | "invalid-advertisement";
+```
+
+Why one Computer contributed no module to an acquisition.
+
+---
+
+### ComputersConnectionOptions
+
+```ts
+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.
+
+---
+
+### McpServerConnection
+
+```ts
+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.
+
+---
+
+### McpServersConnectionOptions
+
+```ts
+type McpServersConnectionOptions = Readonly<{
+  id: string;
+  read: () => Promise<
+    Readonly<{
+      version: string;
+      servers: readonly McpServerConnection[];
+    }>
+  >;
+  subscribe: (invalidate) => () => void;
+  onUnavailable: (error) => void;
+  fetch: FetchLike;
+  namespace?: readonly string[];
+  connectTimeoutMillis?: number;
+}>;
+```
+
+A captured host list of remote MCP servers; authority stays with the host.
+
+---
+
+### McpServerUnavailableReason
+
+```ts
+type McpServerUnavailableReason =
+  "rejected" | "unauthorized" | "timeout" | "invalid-advertisement";
+```
+
+Why one MCP server contributed no module to an acquisition.
+
+## Variables
+
+### listInputSchema
+
+```ts
+const listInputSchema: ZodObject<
+  {
+    path: ZodString;
+    limit: ZodDefault<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+Bounded directory listing request.
+
+---
+
+### listOutputSchema
+
+```ts
+const listOutputSchema: ZodObject<
+  {
+    path: ZodString;
+    entries: ZodArray<
+      ZodObject<
+        {
+          path: ZodString;
+          name: ZodString;
+          type: ZodEnum<{
+            file: "file";
+            directory: "directory";
+            symlink: "symlink";
+          }>;
+          size: ZodNumber;
+          modifiedAt: ZodNumber;
+        },
+        $strict
+      >
+    >;
+    truncated: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Directory entries and an explicit truncation flag.
+
+---
+
+### globInputSchema
+
+```ts
+const globInputSchema: ZodObject<
+  {
+    path: ZodString;
+    pattern: ZodString;
+    limit: ZodDefault<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+Bounded path-pattern search request.
+
+---
+
+### globOutputSchema
+
+```ts
+const globOutputSchema: ZodObject<
+  {
+    path: ZodString;
+    matches: ZodArray<ZodString>;
+    truncated: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Matching paths and an explicit truncation flag.
+
+---
+
+### grepInputSchema
+
+```ts
+const grepInputSchema: ZodObject<
+  {
+    path: ZodString;
+    pattern: ZodString;
+    regex: ZodDefault<ZodBoolean>;
+    ignoreCase: ZodDefault<ZodBoolean>;
+    limit: ZodDefault<ZodNumber>;
+  },
+  $strict
+>;
+```
+
+Bounded content-search request with optional regular-expression matching.
+
+---
+
+### grepOutputSchema
+
+```ts
+const grepOutputSchema: ZodObject<
+  {
+    path: ZodString;
+    matches: ZodArray<
+      ZodObject<
+        {
+          path: ZodString;
+          line: ZodNumber;
+          text: ZodString;
+        },
+        $strict
+      >
+    >;
+    truncated: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Content matches and an explicit truncation flag.
+
+---
+
+### editInputSchema
+
+```ts
+const editInputSchema: ZodObject<
+  {
+    path: ZodString;
+    oldText: ZodString;
+    newText: ZodString;
+  },
+  $strict
+>;
+```
+
+Text replacement request decoded before the captured Files port is called.
+
+---
+
+### filesEditFailureSchema
+
+```ts
+const filesEditFailureSchema: 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";
+        conflict: "conflict";
+     }>;
+     path: ZodString;
+     message: ZodString;
+  }, $strict>;
+}, $strict>;
+```
+
+Structured edit refusal, including its reason and affected path.
+
+---
+
+### editOutputSchema
+
+```ts
+const editOutputSchema: ZodUnion<readonly [ZodObject<{
+  path: ZodString;
+  bytes: ZodNumber;
+  diff: ZodString;
+  firstChangedLine: ZodNullable<ZodNumber>;
+  unifiedPatch: ZodNullable<ZodString>;
+  unifiedPatchBytes: ZodNumber;
+  unifiedPatchAddedLines: ZodNumber;
+  unifiedPatchRemovedLines: ZodNumber;
+  unifiedPatchTruncated: ZodBoolean;
+}, $strict>, 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";
+        conflict: "conflict";
+     }>;
+     path: ZodString;
+     message: ZodString;
+  }, $strict>;
+}, $strict>]>;
+```
+
+Successful edit metadata or a typed edit refusal.
+
+---
+
+### Knapsack
+
+```ts
+const Knapsack: Readonly<{
+  computer: (input) => CapabilitySource;
+  computers: (input) => CapabilitySource;
+  files: (input) => FilesSurface;
+  mcpServers: (input) => CapabilitySource;
+}>;
+```
+
+Agent tool connections available for composition through Mycelium.
+
+## Functions
+
+### edit()
+
+```ts
+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"
+          | "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`](#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"` \| `"conflict"`;
+`path`: `string`; `message`: `string`; \}; \}\>
+
+## References
+
+### readInputSchema
+
+Re-exports [readInputSchema](files-read.md#readinputschema)
+
+---
+
+### readOutputSchema
+
+Re-exports [readOutputSchema](files-read.md#readoutputschema)
+
+---
+
+### patchInputSchema
+
+Re-exports [patchInputSchema](files-patch.md#patchinputschema)
+
+---
+
+### patchOutputSchema
+
+Re-exports [patchOutputSchema](files-patch.md#patchoutputschema)