@fungi.computer/oyster 0.47.3 → 0.47.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/host.d.ts CHANGED
@@ -23,7 +23,7 @@ import { type ResourceOption } from "./apps/permissions.js";
23
23
  import type { AppToolPolicy } from "./apps/tools.js";
24
24
  import type { LiveOysterKey } from "./keys.js";
25
25
  import { type ServedTable, type RouteDeclaration, type Routes } from "./authorization.js";
26
- import { type AppMethodReply } from "@fungi.computer/agar/backend";
26
+ import { type AppFailureReason, type AppMethodReply } from "@fungi.computer/agar/backend";
27
27
  import type { AppCapabilityId, HostActor } from "@fungi.computer/puffball/app";
28
28
  import { type CapabilityDescriptor } from "./capability-descriptor.js";
29
29
  export { capabilityDescriptorSchema, capabilityMethodKindSchema, capabilityMethodSchema, type CapabilityDescriptor, type CapabilityMethodKind, } from "./capability-descriptor.js";
@@ -90,6 +90,10 @@ export type InstanceResult<T> = Readonly<{
90
90
  code: AppInstanceErrorCode | "failed";
91
91
  /** Closed host diagnostic; absent when the execution owner did not supply one. */
92
92
  causeClass?: "Error" | "TypeError" | "RangeError" | "SyntaxError" | "AbortError" | "TimeoutError" | "Other";
93
+ /** Why a `failed` execution failed, when the execution owner recorded it. */
94
+ reason?: AppFailureReason;
95
+ /** Names the owner's log line for that failure; shown to the person who reports it. */
96
+ ref?: string;
93
97
  }>;
94
98
  /** One running App Instance, wherever the host runs it. */
95
99
  export type InstanceHandle = Readonly<{
package/dist/host.js CHANGED
@@ -98,8 +98,13 @@ function installationOperationRefusal(cause) {
98
98
  function noStoreRefusal(status, error) {
99
99
  return Response.json({ error }, { status, headers: { "Cache-Control": "no-store" } });
100
100
  }
101
- function instanceRefusal(code, causeClass) {
101
+ function instanceRefusal({ code, causeClass, reason, ref, }) {
102
102
  if (code === "failed") {
103
+ // The owner recorded why: say it in the closed body Apps' pages decode.
104
+ if (reason !== undefined)
105
+ return Response.json(ref === undefined
106
+ ? { error: "App execution unavailable", reason }
107
+ : { error: "App execution unavailable", reason, ref }, { status: 502 });
103
108
  if (causeClass === undefined)
104
109
  console.error("AppInstance failure", {
105
110
  stage: "instance_execution",
@@ -661,7 +666,7 @@ export function oysterRouteTable(host) {
661
666
  const result = await host.instances
662
667
  .get(selectionOf(installation).instanceId, limits)
663
668
  .prepare({ ...selectionOf(installation), status: installation.status }, installation.release);
664
- return result.ok ? null : instanceRefusal(result.code, result.causeClass);
669
+ return result.ok ? null : instanceRefusal(result);
665
670
  };
666
671
  const apply = async (installation, verifiedRelease) => {
667
672
  if (verifiedRelease.backend === null)
@@ -669,7 +674,7 @@ export function oysterRouteTable(host) {
669
674
  const result = await host.instances
670
675
  .get(selectionOf(installation).instanceId, limits)
671
676
  .apply({ ...selectionOf(installation), status: installation.status }, installation.release);
672
- return result.ok ? null : instanceRefusal(result.code, result.causeClass);
677
+ return result.ok ? null : instanceRefusal(result);
673
678
  };
674
679
  table.post("/api/installations", owner("direct-or-app"), async (context, { origin, principal }) => {
675
680
  let request;
@@ -852,7 +857,7 @@ export function oysterRouteTable(host) {
852
857
  return noStoreRefusal(409, "Stale copy authority");
853
858
  const opened = await copyOwned.copies.open(copyOwned.authority, form.requestId);
854
859
  if (!opened.ok)
855
- return instanceRefusal(opened.code, opened.causeClass);
860
+ return instanceRefusal(opened);
856
861
  return new Response(null, {
857
862
  status: 303,
858
863
  headers: {
@@ -875,7 +880,7 @@ export function oysterRouteTable(host) {
875
880
  return noStoreRefusal(409, "Stale copy authority");
876
881
  const discarded = await copyOwned.copies.discard(copyOwned.authority, form.copyId);
877
882
  if (!discarded.ok)
878
- return instanceRefusal(discarded.code, discarded.causeClass);
883
+ return instanceRefusal(discarded);
879
884
  return new Response(null, {
880
885
  status: 303,
881
886
  headers: { Location: "/recovery", "Cache-Control": "no-store" },
@@ -887,7 +892,7 @@ export function oysterRouteTable(host) {
887
892
  return copyOwned;
888
893
  const observed = await copyOwned.copies.inspect(copyOwned.authority);
889
894
  if (!observed.ok)
890
- return instanceRefusal(observed.code, observed.causeClass);
895
+ return instanceRefusal(observed);
891
896
  if (observed.value?.copyId !== context.req.param("copyId"))
892
897
  return noStoreRefusal(404, "Test copy expired or discarded");
893
898
  return appTestCopyPage(copyOwned.installation.installationId, observed.value, (await releaseOf(copyOwned.installation.release)).declaration, (await assets()).page.path);
@@ -937,9 +942,7 @@ export function oysterRouteTable(host) {
937
942
  if (admitted.kind === "refused")
938
943
  return noStoreRefusal(admitted.code === "invalid_input" ? 400 : 403, admitted.code);
939
944
  const result = await copyOwned.copies.call(copyOwned.authority, copyId.data, name, input, invocationCallerContext(copyOwned.principal, null, host.tenantId));
940
- return result.ok
941
- ? methodResponse(result.value)
942
- : instanceRefusal(result.code, result.causeClass);
945
+ return result.ok ? methodResponse(result.value) : instanceRefusal(result);
943
946
  });
944
947
  table.get("/api/installations/:installationId/recovery", owner("direct"), async (context) => {
945
948
  if (!sameOriginReadRequest(context.req.raw))
@@ -1337,7 +1340,7 @@ export function oysterRouteTable(host) {
1337
1340
  release.backend === null)
1338
1341
  return refusal(404, "Gill is not declared");
1339
1342
  if (installation.instanceId === null)
1340
- return instanceRefusal("invalid_invocation_facts");
1343
+ return instanceRefusal({ code: "invalid_invocation_facts" });
1341
1344
  const params = request.params ?? {};
1342
1345
  const declared = gill.params ?? [];
1343
1346
  if (Object.keys(params).some((key) => !declared.some((param) => param.key === key)))
@@ -1406,13 +1409,16 @@ export function oysterRouteTable(host) {
1406
1409
  .get(facts.instanceId, limits)
1407
1410
  .gill(facts, release.api, source, { id: viewId, ...selectors });
1408
1411
  if (!result.ok)
1409
- return instanceRefusal(result.code, result.causeClass);
1412
+ return instanceRefusal(result);
1410
1413
  try {
1411
1414
  const reply = decodeGillReply(result.value);
1412
1415
  return Response.json("viewId" in reply ? decodeDeclaredGillResponse(reply, gill) : reply);
1413
1416
  }
1414
1417
  catch (error) {
1415
- return instanceRefusal("failed", causeClass(error));
1418
+ return instanceRefusal({
1419
+ code: "failed",
1420
+ causeClass: causeClass(error),
1421
+ });
1416
1422
  }
1417
1423
  });
1418
1424
  const executeMethod = async (installation, release, principal, name, request, recheck) => {
@@ -1454,7 +1460,7 @@ export function oysterRouteTable(host) {
1454
1460
  .get(selectionOf(installation).instanceId, limits)
1455
1461
  .call(await admittedMethodCallerFacts(host, installation, release, invocationCallerContext(principal, host.computerId ?? null, host.tenantId), decision.grants, { name, effect: method.effect }), release.api, name, input);
1456
1462
  if (!result.ok)
1457
- return instanceRefusal(result.code, result.causeClass);
1463
+ return instanceRefusal(result);
1458
1464
  return methodResponse(result.value);
1459
1465
  };
1460
1466
  table.post("/apps/:installationId/methods/:name", appRoute(), async (context, { principal }) => {
package/dist/mcp.d.ts CHANGED
@@ -4,6 +4,7 @@ import type { DeclaredOperations, Installation } from "./apps/installation.js";
4
4
  import { type CapabilitySource, type Grants, type ModuleRegistration } from "@fungi.computer/mycelium";
5
5
  import { computerPageSchema } from "@fungi.computer/computer/fleet/inventory-wire";
6
6
  import { localBackendDetachSchema } from "@fungi.computer/computer/fleet/wire";
7
+ import { computerStateSchema } from "@fungi.computer/computer/fleet/wire";
7
8
  import type { InvocationContext } from "@fungi.computer/mycelium";
8
9
  import type { ComputerControlPort } from "./computer-control-port.js";
9
10
  export type { ComputerControlPort } from "./computer-control-port.js";
@@ -22,6 +23,14 @@ export declare const appApprovalInstructions: string;
22
23
  declare const fleetComputerId: z.ZodObject<{
23
24
  computerId: z.ZodString;
24
25
  }, z.core.$strict>;
26
+ /**
27
+ * `reason: true` asks for a failed start's plain-words reason. Callers that
28
+ * never ask get the state shape every released client decodes strictly.
29
+ */
30
+ declare const fleetStateRead: z.ZodObject<{
31
+ computerId: z.ZodString;
32
+ reason: z.ZodExactOptional<z.ZodLiteral<true>>;
33
+ }, z.core.$strict>;
25
34
  declare const fleetCreate: z.ZodObject<{
26
35
  name: z.ZodDefault<z.ZodNullable<z.ZodString>>;
27
36
  size: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
@@ -145,25 +154,25 @@ export declare function computerControlSpecs(port: ComputerControlPort): {
145
154
  description: string;
146
155
  input: z.ZodObject<{
147
156
  computerId: z.ZodString;
157
+ reason: z.ZodExactOptional<z.ZodLiteral<true>>;
148
158
  }, z.core.$strict>;
149
- output: z.ZodDiscriminatedUnion<[z.ZodObject<{
159
+ output: z.ZodUnion<readonly [z.ZodObject<{
150
160
  state: z.ZodEnum<{
151
161
  running: "running";
152
162
  sleeping: "sleeping";
153
163
  starting: "starting";
154
- start_failed: "start_failed";
155
164
  }>;
165
+ }, z.core.$strict>, z.ZodObject<{
166
+ state: z.ZodLiteral<"start_failed">;
167
+ }, z.core.$strict>, z.ZodObject<{
168
+ state: z.ZodLiteral<"start_failed">;
169
+ reason: z.ZodString;
156
170
  }, z.core.$strict>, z.ZodObject<{
157
171
  state: z.ZodLiteral<"queued">;
158
172
  position: z.ZodNumber;
159
- }, z.core.$strict>], "state">;
173
+ }, z.core.$strict>]>;
160
174
  /** Return liveness without waking the runtime. */
161
- execute: (input: z.output<typeof fleetComputerId>, context: InvocationContext) => Promise<{
162
- state: "running" | "sleeping" | "starting" | "start_failed";
163
- } | {
164
- state: "queued";
165
- position: number;
166
- }>;
175
+ execute: (input: z.output<typeof fleetStateRead>, context: InvocationContext) => Promise<z.output<typeof computerStateSchema>>;
167
176
  };
168
177
  start: {
169
178
  replay: "unsafe";
@@ -171,20 +180,29 @@ export declare function computerControlSpecs(port: ComputerControlPort): {
171
180
  input: z.ZodObject<{
172
181
  computerId: z.ZodString;
173
182
  }, z.core.$strict>;
174
- output: z.ZodDiscriminatedUnion<[z.ZodObject<{
183
+ output: z.ZodUnion<readonly [z.ZodObject<{
175
184
  state: z.ZodEnum<{
176
185
  running: "running";
177
186
  sleeping: "sleeping";
178
187
  starting: "starting";
179
- start_failed: "start_failed";
180
188
  }>;
189
+ }, z.core.$strict>, z.ZodObject<{
190
+ state: z.ZodLiteral<"start_failed">;
191
+ }, z.core.$strict>, z.ZodObject<{
192
+ state: z.ZodLiteral<"start_failed">;
193
+ reason: z.ZodString;
181
194
  }, z.core.$strict>, z.ZodObject<{
182
195
  state: z.ZodLiteral<"queued">;
183
196
  position: z.ZodNumber;
184
- }, z.core.$strict>], "state">;
197
+ }, z.core.$strict>]>;
185
198
  /** Admit and start this Computer. */
186
199
  execute: (input: z.output<typeof fleetComputerId>, context: InvocationContext) => Promise<{
187
- state: "running" | "sleeping" | "starting" | "start_failed";
200
+ state: "running" | "sleeping" | "starting";
201
+ } | {
202
+ state: "start_failed";
203
+ } | {
204
+ state: "start_failed";
205
+ reason: string;
188
206
  } | {
189
207
  state: "queued";
190
208
  position: number;
package/dist/mcp.js CHANGED
@@ -38,6 +38,14 @@ const fleetIds = defineIdFamily({
38
38
  const fleetComputerId = z.strictObject({
39
39
  computerId: z.string().min(1).max(256),
40
40
  });
41
+ /**
42
+ * `reason: true` asks for a failed start's plain-words reason. Callers that
43
+ * never ask get the state shape every released client decodes strictly.
44
+ */
45
+ const fleetStateRead = z.strictObject({
46
+ computerId: z.string().min(1).max(256),
47
+ reason: z.literal(true).exactOptional(),
48
+ });
41
49
  const fleetCreate = z.strictObject({
42
50
  name: computerCreateRequestSchema.shape.name
43
51
  .unwrap()
@@ -107,11 +115,16 @@ export function computerControlSpecs(port) {
107
115
  state: {
108
116
  replay: "safe",
109
117
  access: "read",
110
- description: "Read runtime state without waking a Computer, including its live admission queue position.",
111
- input: fleetComputerId,
118
+ description: "Read runtime state without waking a Computer, including its live admission queue position. Pass reason: true to get why a failed start failed.",
119
+ input: fleetStateRead,
112
120
  output: computerStateSchema,
113
121
  /** Return liveness without waking the runtime. */
114
- execute: (input, context) => port.state(input.computerId, context),
122
+ execute: async (input, context) => {
123
+ const state = await port.state(input.computerId, context);
124
+ if (state.state !== "start_failed" || input.reason === true)
125
+ return state;
126
+ return { state: state.state };
127
+ },
115
128
  },
116
129
  start: {
117
130
  replay: "unsafe",
@@ -14,7 +14,7 @@ import { OysterAgentBrowserHost } from "./agent-browser.js";
14
14
  import { createPageLifetime } from "./lifetime.js";
15
15
  import { computerTargetUrl } from "../computer-target.js";
16
16
  import * as Schema from "effect/Schema";
17
- import { AppError, createCapabilityRegistry, } from "@fungi.computer/agar";
17
+ import { AppError, readAppFailure, createCapabilityRegistry, } from "@fungi.computer/agar";
18
18
  import { appStorage } from "@fungi.computer/agar/storage";
19
19
  import { approvals } from "@fungi.computer/agar/approvals";
20
20
  import { oysterStorageHandle } from "./storage.js";
@@ -51,10 +51,7 @@ async function answer(response) {
51
51
  retryable: false,
52
52
  });
53
53
  if (!response.ok)
54
- throw new AppError("App backend request failed", {
55
- code: "HOST_FAILURE",
56
- retryable: response.status >= 500,
57
- });
54
+ throw await readAppFailure(response);
58
55
  return parseJsonValue(await response.json());
59
56
  }
60
57
  /** The App's typed methods, reached through this host's method route. */