@intentic/sandbox-contract 1.172.0 → 1.174.0

package/src/schemas.ts

@@ -1394,7 +1394,14 @@ export const WorkspaceSearchHitSchema = z.object({
     context: z.string().optional(),
 });
 export type WorkspaceSearchHit = z.infer<typeof WorkspaceSearchHitSchema>;
-export const WorkspaceSearchGroupSchema = z.object({ path: z.string(), score: z.number(), hits: z.array(WorkspaceSearchHitSchema) });
+export const WorkspaceSearchGroupSchema = z.object({
+    path: z.string(),
+    score: z.number(),
+    hits: z.array(WorkspaceSearchHitSchema),
+    // This file had more matching lines than the engine keeps per file, so `hits` is a floor — a panel showing a
+    // per-file count has to say "50+" rather than "50".
+    capped: z.boolean().optional(),
+});
 export type WorkspaceSearchGroup = z.infer<typeof WorkspaceSearchGroupSchema>;
 // `building` = index still filling (progress 0..1, e.g. embeddings pending); `stale` = revalidation was skipped
 // (cursor replay). ageMs = time since the index last matched the disk state.
@@ -1417,6 +1424,9 @@ export const WorkspaceSearchResultSchema = z.object({
     groups: z.array(WorkspaceSearchGroupSchema),
     freshness: WorkspaceSearchFreshnessSchema,
     truncated: z.boolean(),
+    // `total` is a FLOOR: at least one file had more matches than the engine keeps per file. Distinct from
+    // `truncated`, which is about this PAGE — a result can be complete on the page and still count partially.
+    partial: z.boolean().optional(),
     cursor: z.string().optional(),
     hint: z.string().optional(),
     // What the engine did with the query that the query did not ask for — a pattern rerun as literal text
@@ -1913,7 +1923,20 @@ export const CapabilitySummarySchema = z.object({
     status: CapabilityStatusSchema,
     config: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
 });
-export const CapabilitiesListSchema = z.object({ capabilities: z.array(CapabilitySummarySchema) });
+// A capability the WORKSPACE asks for but the manifest doesn't carry — derived from what is checked out under
+// /work, not from anything the user configured. It exists because the failure it prevents is illegible: a
+// compose-backed dev database (`pnpm db:up`) dies on a missing /var/run/docker.sock, and nothing on that error
+// points at the one-time privileged rebuild that fixes it. `evidence` is the workspace-relative path that
+// triggered it, rendered verbatim so the claim is checkable rather than magic.
+export const CapabilityRecommendationSchema = z.object({ kind: CapabilityKindSchema, evidence: z.string() });
+export type CapabilityRecommendation = z.infer<typeof CapabilityRecommendationSchema>;
+export const CapabilitiesListSchema = z.object({
+    capabilities: z.array(CapabilitySummarySchema),
+    // Defaulted for the daemon-older-than-browser seam: the platform's web app talks to whichever sandbox
+    // version the user has, and a required field here would fail the parse — taking the whole Capabilities page
+    // down on every sandbox predating this route, to hide a badge.
+    recommendations: z.array(CapabilityRecommendationSchema).default([]),
+});
 export const CapabilityIdParamSchema = z.object({ id: z.string() });
 // POST /capabilities/{id}/secret body: replace just the capability's secret field (its key is per-kind, see the
 // sandbox's secretField) and re-run its idempotent apply — the /secrets page's edit path.
@@ -2435,6 +2458,158 @@ export type CiRunParam = z.infer<typeof CiRunParamSchema>;
 export const CiFixResponseSchema = z.object({ conversationId: z.string() });
 export type CiFixResponse = z.infer<typeof CiFixResponseSchema>;
 
+/* ---- Komodo deployments: the Deployments rail view's wire shape ----
+ *
+ * The daemon does the VENDOR translation (Komodo's tagged unions and enums → the flat shapes below); the
+ * extension does the ATTENTION model on top of them (which alerts are incidents, which have been seen, what
+ * the rail says). Same split as CI, and for the same reason: what a breakage MEANS is a UI decision that has
+ * to be unit-testable without a daemon, while what Komodo's `ContainerStateChange` variant looks like is a
+ * detail no view should ever learn.
+ *
+ * Routes are per-connection (`/komodo/{capability}/…`): a sandbox can hold two Komodo capabilities, and the
+ * credential the daemon resolves per call is the one the path names. The browser never holds either half of
+ * the API key — that is the whole reason these routes exist rather than the view calling Komodo directly. */
+
+// Every Komodo container state (DeploymentState ∪ StackState — eleven words between them) collapsed onto the
+// five a view can tone. `stopped` swallows exited/stopped/paused/created/down/not_deployed on purpose: being
+// down is a LEVEL and says nothing about whether it was meant to be. What says a running thing STOPPED is the
+// alert log, which is why the badge reads alerts and this enum only colours a chip.
+export const DeployStateSchema = z.enum(["running", "deploying", "stopped", "unhealthy", "unknown"]);
+export type DeployState = z.infer<typeof DeployStateSchema>;
+
+// Stacks and deployments are one row type in the view: a stack is a compose project, a deployment a single
+// container, and an operator looking for what is down does not want them in separate lists.
+export const DeployResourceKindSchema = z.enum(["deployment", "stack"]);
+export type DeployResourceKind = z.infer<typeof DeployResourceKindSchema>;
+
+// One service inside a stack — free of extra calls (Komodo's ListStacks already returns them under `info`),
+// so a stack row can expand without a per-row fetch.
+export const DeployServiceSchema = z.object({
+    name: z.string(),
+    image: z.string(),
+    updateAvailable: z.boolean(),
+});
+export type DeployService = z.infer<typeof DeployServiceSchema>;
+
+export const DeployResourceSchema = z.object({
+    kind: DeployResourceKindSchema,
+    // Komodo's resource id — what the action routes address (names collide across resource types, ids don't).
+    id: z.string(),
+    name: z.string(),
+    state: DeployStateSchema,
+    // Komodo's own status prose ("Up 4 days", "Exited (1) 20 minutes ago"). Passed through rather than
+    // regenerated: docker's phrasing is more precise than anything we would compose from a state word.
+    status: z.string().optional(),
+    // The host it runs on — the grouping key of the whole view. Absent on a resource Komodo has not placed yet.
+    server: z.string().optional(),
+    image: z.string().optional(),
+    // A newer image exists at the same tag. An opportunity, never a breakage — see the tone table in
+    // ext-deployments' incidents.ts for why this may not reach the rail as `danger`.
+    updateAvailable: z.boolean(),
+    // Stacks only, and empty when the stack has none deployed yet.
+    services: z.array(DeployServiceSchema),
+    // Deep link into Komodo's own UI for this resource — we do not reimplement Komodo, we get you there.
+    url: z.string(),
+});
+export type DeployResource = z.infer<typeof DeployResourceSchema>;
+
+export const DeployServerStateSchema = z.enum(["ok", "unreachable", "disabled"]);
+export type DeployServerState = z.infer<typeof DeployServerStateSchema>;
+
+// A host, with the three gauges that explain a large share of deployment failures. All three ride ListServers'
+// own `info.stats`, so the strip costs nothing extra; absent when the server is unreachable (no stats to have).
+export const DeployServerSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    state: DeployServerStateSchema,
+    cpuPercent: z.number().optional(),
+    memPercent: z.number().optional(),
+    diskPercent: z.number().optional(),
+    url: z.string(),
+});
+export type DeployServer = z.infer<typeof DeployServerSchema>;
+
+// One entry from Komodo's alert log — an EDGE, already timestamped and resolve-flagged server-side. This is
+// what makes the rail badge possible without keeping any local history: Komodo records the transition, we only
+// decide whether the owner has seen it. `type` stays the raw AlertData variant tag (ContainerStateChange,
+// ServerUnreachable, DeploymentImageUpdateAvailable, BuildFailed…) — a variant we have not met yet is exactly
+// the one worth surfacing, so it passes through instead of being dropped into an "other" bucket.
+export const DeployAlertSchema = z.object({
+    id: z.string(),
+    type: z.string(),
+    level: z.enum(["ok", "warning", "critical"]),
+    // Komodo closes an alert when the condition clears; a resolved container-state alert IS the recovery.
+    resolved: z.boolean(),
+    // Epoch ms the alert OPENED — compared against seenAt, so further trouble inside one open alert can't re-badge.
+    ts: z.number(),
+    // The resource it is about, when the variant names one, and the host it sits on.
+    resource: z.string().optional(),
+    server: z.string().optional(),
+    // The container/stack state transition, on the variants that carry one ("running" → "restarting").
+    from: z.string().optional(),
+    to: z.string().optional(),
+});
+export type DeployAlert = z.infer<typeof DeployAlertSchema>;
+
+export const DeployOverviewResponseSchema = z.object({
+    komodoUrl: z.string(),
+    // FALSE means Komodo did not answer — the view says so loudly and the badge must not read `danger`.
+    // "We cannot see production" is not "production is broken", the same line ciAttention draws when it
+    // leaves the last known state standing rather than blanking the tile.
+    reachable: z.boolean(),
+    // Why it did not answer, in Komodo's own words — the view shows it instead of a bare "unavailable".
+    unreachableReason: z.string().optional(),
+    resources: z.array(DeployResourceSchema),
+    servers: z.array(DeployServerSchema),
+    // Newest first. Unresolved and resolved both: the view shows recent history, the badge reads only the
+    // unresolved half.
+    alerts: z.array(DeployAlertSchema),
+    // When the owner last opened THIS connection's view. Rides the response so the rail decides what is new
+    // without a second call. Absent ⇒ never opened, so everything counts as unseen.
+    seenAt: z.number().optional(),
+});
+export type DeployOverviewResponse = z.infer<typeof DeployOverviewResponseSchema>;
+
+// Which Komodo connection a call addresses — the capability id, which is also the rail tile's key.
+export const DeployCapabilityParamSchema = z.object({ capability: z.string() });
+export type DeployCapabilityParam = z.infer<typeof DeployCapabilityParamSchema>;
+
+// The five state-changing operations the view offers. Deliberately no `write/*`: editing config from a
+// dashboard is how you get drift the desired-state repo then fights, so configuration stays in Komodo or in
+// the intent repo. `pull` pulls the newest image AND deploys — the routine version bump as one click.
+export const DeployActionSchema = z.enum(["deploy", "restart", "start", "stop", "pull"]);
+export type DeployAction = z.infer<typeof DeployActionSchema>;
+
+export const DeployActionParamSchema = z.object({
+    capability: z.string(),
+    kind: DeployResourceKindSchema,
+    // Komodo's resource id. Re-resolved to a live resource per call, so a stale card cannot act on something
+    // that has since been deleted — the CI actions' "re-resolve per call" rule.
+    id: z.string(),
+    action: DeployActionSchema,
+});
+export type DeployActionParam = z.infer<typeof DeployActionParamSchema>;
+
+export const DeployLogsParamSchema = z.object({
+    capability: z.string(),
+    kind: DeployResourceKindSchema,
+    id: z.string(),
+});
+export type DeployLogsParam = z.infer<typeof DeployLogsParamSchema>;
+
+// Komodo returns a `Log` with both channels; the view renders them together, newest at the bottom, the way a
+// terminal would.
+export const DeployLogsResponseSchema = z.object({ stdout: z.string(), stderr: z.string() });
+export type DeployLogsResponse = z.infer<typeof DeployLogsResponseSchema>;
+
+// The fix route opens an isolated conversation seeded with the resource, its state, and its log tail — the
+// thing Komodo's own UI structurally cannot do, since the repo that holds the bug is open in the next tab.
+export const DeployFixResponseSchema = z.object({ conversationId: z.string() });
+export type DeployFixResponse = z.infer<typeof DeployFixResponseSchema>;
+
+export const DeploySeenResponseSchema = z.object({ seenAt: z.number() });
+export type DeploySeenResponse = z.infer<typeof DeploySeenResponseSchema>;
+
 /* ---- the pre-push check: the workspace's own answer to "would this push go red" ----
  *
  * WHERE THIS SITS. A fleet of 5-20 agents lands work into the main tree, the user reviews and commits it by

package/src/workspace-state.ts

@@ -77,6 +77,11 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
      * Both entries below are outside that by design, so an empty set is the honest record — naming a key no
      * query uses would put the drift this table exists to remove straight back into it. Each says which
      * constraint would have to move first, so the next reader doesn't re-derive it. */
+    {
+        path: ".intentic/webchat-installs.json",
+        invalidates: [],
+        why: "Which origins have loaded a Doorbell's widget, written on a 30s flush timer while a customer's site serves page views. The install panel that renders it fetches on open and polls itself while it is on screen, which is the whole window in which the answer changes for anyone. Pushing instead would bill every connected browser a refetch per flush, for a panel almost nobody has open.",
+    },
     {
         path: ".intentic/webchat-sessions.json",
         invalidates: [],
@@ -121,6 +126,11 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
         invalidates: [],
         why: "Webhook secret + conclusion memory; the Pipelines view reads it through /ci/runs, not off disk.",
     },
+    {
+        path: ".intentic/komodo.json",
+        invalidates: [],
+        why: "Per-connection 'when the owner last looked at Deployments'; the view reads it through /komodo/{capability}/overview, not off disk — and it is written BY that view being opened, so invalidating on it would refetch the board in answer to the browser's own click.",
+    },
     { path: ".intentic/bridge-tokens.json", invalidates: [], why: "Hashed ACP bridge tokens, listed on demand by the owner." },
     {
         path: ".intentic/owner.json",