@intentic/sandbox-contract 1.253.0 → 1.254.1

package/src/schemas/repo-checks.ts

@@ -0,0 +1,64 @@
+// repo-checks: what a REPOSITORY says should be run on its own code, declared in the repository, at
+// `<repo>/.intentic/checks.json`.
+//
+// The line between this file and the sandbox's own settings is authority, not subject matter: a repository may declare
+// WHAT to run, because the command belongs beside the scripts it names and travels with the checkout; only the sandbox
+// owner decides what happens when it fails (whether work lands, whether a push goes), and that stays in settings.json.
+// Nothing declared here runs until the owner adopts it for that repository (settings `adoptedChecks`), the same rule
+// git keeps for hooks, which are never cloned.
+import { z } from "zod";
+
+// Named for the occasion as a repository would say it, not for the daemon's wire moment: `turn` is `turn.ending` and
+// `push` is `push.starting` (rules/repo-checks.ts maps them). Two, because these are the two occasions whose command a
+// repository actually owns; a verdict moment has nothing here to express.
+export const RepoCheckMomentSchema = z.enum(["turn", "push"]);
+export type RepoCheckMoment = z.infer<typeof RepoCheckMomentSchema>;
+
+export const RepoCheckSchema = z.object({
+    when: RepoCheckMomentSchema.describe("When to run it: `turn` before the assistant finishes, `push` before code leaves the machine."),
+    run: z.string().min(1).max(500).describe("The command, run in this repository's own directory, so it reads as it would in a terminal there."),
+    label: z.string().min(1).max(80).optional().describe("What to call it on screen. Absent names it after the command."),
+    // Same ceiling as a rule's own command; past it the process group is killed and the run is a failure, never a
+    // silent pass.
+    timeoutMs: z.number().min(60_000).max(3_600_000).optional().describe("How long it may take before it is killed and counted as failed."),
+    // Repo-relative, as anybody reading this file would write them; the daemon prefixes the repo id before matching,
+    // since a rule's globs are workspace-relative.
+    paths: z
+        .array(z.string().min(1))
+        .max(20)
+        .optional()
+        .describe("Only run it when the change touches these paths, written relative to this repository. Absent runs it on every change here."),
+});
+export type RepoCheck = z.infer<typeof RepoCheckSchema>;
+
+// The file itself. One key, so a second concern can be added later without breaking a file anyone has written.
+export const RepoChecksFileSchema = z.object({ checks: z.array(RepoCheckSchema).max(10).default([]) });
+export type RepoChecksFile = z.infer<typeof RepoChecksFileSchema>;
+
+// One repository, as a screen reads it: what it declares, and where that stands with the owner.
+export const RepoChecksSummarySchema = z.object({
+    repo: z.string().describe('Which repository, by its workspace id ("root" is the workspace itself).'),
+    path: z.string().describe("Where the declaration lives, relative to the workspace, whether or not the file exists yet."),
+    checks: z.array(RepoCheckSchema).describe("What it declares, in the order the file lists them."),
+    adopted: z
+        .boolean()
+        .describe("Whether these are running. False means declared and inert: nothing a repository writes runs until the owner switches it on."),
+    changed: z
+        .boolean()
+        .describe(
+            "Whether the declaration changed since it was adopted, which holds it until the owner looks again. True only for a repository that was adopted before.",
+        ),
+    error: z.string().optional().describe("Why the file could not be read, when it exists but does not parse. The checks list is empty in that case."),
+});
+export type RepoChecksSummary = z.infer<typeof RepoChecksSummarySchema>;
+export const RepoChecksListSchema = z.object({
+    repos: z.array(RepoChecksSummarySchema).describe("Every repository that declares checks, plus any the owner has adopted before, sorted by id."),
+});
+export type RepoChecksList = z.infer<typeof RepoChecksListSchema>;
+export const RepoChecksAdoptSchema = z.object({
+    repo: z.string().min(1).describe("Which repository's declaration to switch."),
+    on: z
+        .boolean()
+        .describe("On adopts what it declares as it stands now; off stops running it. Adopting again is how a changed declaration is accepted."),
+});
+export type RepoChecksAdopt = z.infer<typeof RepoChecksAdoptSchema>;

package/src/schemas/settings.ts

@@ -369,8 +369,18 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Whether a turn killed by the sandbox restarting is re-run once it comes back. Off to begin with, for the same reason: it would spend your allowance on work you are not watching and edit files while you are still waiting for the sandbox to return. Either way the interruption is recorded rather than silently lost.",
         ),
+    // Which repositories' own declarations (`<repo>/.intentic/checks.json`) the owner has switched on, each against the
+    // fingerprint of what was declared when they did. A declaration that has since changed no longer matches its
+    // fingerprint and is held rather than run, which is what makes adoption a decision about a command rather than a
+    // permanent permission on a folder. Keyed by repo id, so `/` in the key is ordinary.
+    adoptedChecks: z
+        .record(z.string(), z.string())
+        .default({})
+        .describe(
+            "Which repositories may run the checks they declare for themselves, and exactly which version of those checks you agreed to. A repository's declaration does nothing until it appears here, the same rule git keeps for hooks, which are never cloned; and a declaration that changes afterwards is held until you look at it again.",
+        ),
     // Lives in the owner's own settings, not the workspace: a rule can hold work and gate a push, so it answers to the
-    // sandbox owner alone. Repo- or extension-contributed rules aren't supported yet.
+    // sandbox owner alone. A repository may declare a COMMAND of its own (see `adoptedChecks`), never a verdict.
     rules: z
         .array(RuleSchema)
         .max(50)
@@ -511,6 +521,22 @@ export const TierReportSchema = z.object({
     denied: z.number(),
 });
 export type TierReport = z.infer<typeof TierReportSchema>;
+// One dependency version or library improvement suggested or pinned.
+export const DependencyImprovementSchema = z.object({
+    prevented: z.string(),
+    chosen: z.string(),
+    reason: z.string(),
+    at: z.number().optional(),
+});
+export type DependencyImprovement = z.infer<typeof DependencyImprovementSchema>;
+// Rollup of registry freshness interventions over the queried day window.
+export const DependencySavingsSchema = z.object({
+    checked: z.number(),
+    improved: z.number(),
+    recent: z.array(DependencyImprovementSchema),
+    updatedAt: z.number().optional(),
+});
+export type DependencySavings = z.infer<typeof DependencySavingsSchema>;
 export const SavingsReportSchema = z.object({
     input: InputSavingsSchema,
     search: TurnExperimentSchema.optional(),
@@ -518,5 +544,6 @@ export const SavingsReportSchema = z.object({
     map: TurnExperimentSchema.optional(),
     // Automatic tier selection's readout, see TierReportSchema. Absent ⇒ nothing was judged in the window.
     tier: TierReportSchema.optional(),
+    dependencies: DependencySavingsSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;