@capybara-hq/kernel 0.1.0-rc.26 → 0.1.0-rc.28

package/dist/tools/git-push-policy.d.ts

@@ -0,0 +1,89 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { type UnattendedRun } from "../schedules/unattended.js";
+import { type GitRunState } from "./git-asks.js";
+import type { ToolPolicy } from "./registry.js";
+/** Why {@link decideGitPush} decided as it did. */
+export type GitPushReason = 
+/** The org's default for the connector allows pushes. */
+"org_allow"
+/** The member's standing allow for the repository. */
+ | "member_allow"
+/** An approved 「这次允许」 of the run tree for the repository. */
+ | "run_grant"
+/** The scheduled task's `git:push` / `git:push:<owner>/<repo>` grant (unattended run). */
+ | "task_grant"
+/** The policy asks the actor. */
+ | "ask"
+/** The org's default denies pushes through the connector. */
+ | "org_deny"
+/** The member denied pushes to the repository for themselves. */
+ | "member_deny"
+/** The org forbids `git:push` (or the repository's key) in scheduled runs. */
+ | "forbidden"
+/** An unattended run in `fail` mode without a task grant: no one can be asked. */
+ | "unattended"
+/** The connector is not a live, active connector of the org. */
+ | "unavailable"
+/** The repository is not `<owner>/<repo>`. */
+ | "invalid_repo";
+/** The decision about one push. */
+export interface GitPushDecision {
+    decision: "allow" | "ask" | "deny";
+    reason: GitPushReason;
+    /** The repository as keyed (`<owner>/<repo>`, lower-cased); null when it was invalid. */
+    repo: string | null;
+    /** An unattended refusal's `missing_grants` key (`git:push:<owner>/<repo>`) and task run. */
+    missingGrant?: {
+        taskRunId: string;
+        key: string;
+    };
+}
+/** What {@link decideGitPush} decides about. */
+export interface GitPushInput {
+    orgId: string;
+    /** The actor whose credential the push uses (the ticket's account). */
+    accountId: string;
+    /** The run the exec belongs to (the ticket's run). */
+    runId: string;
+    /** The git source the push uses (the connector whose credential is injected). */
+    connectorId: string;
+    host: string;
+    /** `<owner>/<repo>` (a trailing `.git` and case are normalized here). */
+    repo: string;
+    /**
+     * The scheduled task context of the run, when the caller has it (`unattendedRunOf`); undefined:
+     * read here. Null: an attended run.
+     */
+    unattended?: UnattendedRun | null;
+}
+/** A decision the actor's or the org's policy settles without grants (pure). */
+export declare function gitPushBase(input: {
+    orgDefault: ToolPolicy;
+    /** The member's own setting for the repository (a personal connector only). */
+    member?: ToolPolicy | undefined;
+}): {
+    policy: ToolPolicy;
+    reason: GitPushReason;
+};
+/**
+ * Decides a push (sandbox git credentials spec §7), highest first:
+ * 1. the org's default `deny` for the connector; the member's own `deny` for the repository;
+ * 2. an unattended run (no trial, no person joined) whose org forbids `git:push` or the
+ *    repository's key in scheduled runs (scheduled tasks spec §7): deny, whatever allows it below;
+ * 3. the member's standing allow for the repository on the host (personal connector), else the
+ *    org's default `allow`; a member's `ask` keeps an org `allow` asking;
+ * 4. an ask is allowed by a run grant (an approved `once` git ask of the live run tree for the
+ *    host, repository and connector, decided for the same actor);
+ * 5. an unattended run: a task grant `git:push` or `git:push:<owner>/<repo>` allows; else `fail`
+ *    mode refuses (`unattended`, with the missing grant to record) and `wait` mode asks the
+ *    creator.
+ * Grants never lift a deny. The caller records the missing grant and the Redis ask record.
+ */
+export declare function decideGitPush(db: KernelSchemaDb, config: Pick<KernelConfigService, "get">, input: GitPushInput): Promise<GitPushDecision>;
+/**
+ * The run tree's git asks (the network asks' rules, network ask-to-allow spec §6.8): the
+ * repositories granted and refused in the tree (keyed `<host>/<owner>/<repo>`, {@link gitRepoKey}),
+ * this run's asks, a pending ask of the tree.
+ */
+export declare function gitRunState(db: KernelSchemaDb, runId: string): Promise<GitRunState>;

package/dist/tools/git-push-policy.js

@@ -0,0 +1,175 @@
+import { sql } from "kysely";
+import { budgetRunOf } from "../runtime/subagents/limits.js";
+import { GIT_PUSH_GRANT, gitPushForbidden, gitPushGrantKey, normalizeGitRepo, } from "../schedules/grant-rules.js";
+import { unattendedRules, unattendedRunOf } from "../schedules/unattended.js";
+import { gitPushPolicyName, personalAuth } from "./connector-account-policies.js";
+import { gitRepoKey } from "./git-asks.js";
+import { connectorPolicy } from "./policy.js";
+/**
+ * The push policy of the git gateway (sandbox git credentials spec §7): fetches run, a push
+ * follows the connector's virtual tool `git_push`. Read from PG on every push (no in-process
+ * state), so a decision on one replica holds on every other.
+ *
+ * Storage (no new table): the org's default is `connectors.git_push_policy` (default `ask`); a
+ * member's standing allow (or deny) for one repository is their `connector_tool_account_policies`
+ * row `git_push:<host>/<owner>/<repo>` (a personal connector only: an org connector's push acts as the
+ * org); a run grant is an approved `once` git ask of the run tree; a scheduled task's grants are
+ * `git:push` and `git:push:<owner>/<repo>` in `scheduled_task_grants`.
+ */
+/** The statuses of a run that has not ended: its run grants still apply. */
+const LIVE_RUN = ["queued", "running", "waiting"];
+/** The statuses of a git ask that refuse its repository for the rest of the run tree. */
+const REFUSING = new Set(["denied", "expired", "skipped", "cancelled"]);
+/** A decision the actor's or the org's policy settles without grants (pure). */
+export function gitPushBase(input) {
+    const r = connectorPolicy({ orgDefault: input.orgDefault, member: input.member });
+    if (r.policy === "deny")
+        return { policy: "deny", reason: r.source === "org" ? "org_deny" : "member_deny" };
+    if (r.policy === "allow") {
+        return { policy: "allow", reason: r.source === "member" ? "member_allow" : "org_allow" };
+    }
+    return { policy: "ask", reason: "ask" };
+}
+/**
+ * Decides a push (sandbox git credentials spec §7), highest first:
+ * 1. the org's default `deny` for the connector; the member's own `deny` for the repository;
+ * 2. an unattended run (no trial, no person joined) whose org forbids `git:push` or the
+ *    repository's key in scheduled runs (scheduled tasks spec §7): deny, whatever allows it below;
+ * 3. the member's standing allow for the repository on the host (personal connector), else the
+ *    org's default `allow`; a member's `ask` keeps an org `allow` asking;
+ * 4. an ask is allowed by a run grant (an approved `once` git ask of the live run tree for the
+ *    host, repository and connector, decided for the same actor);
+ * 5. an unattended run: a task grant `git:push` or `git:push:<owner>/<repo>` allows; else `fail`
+ *    mode refuses (`unattended`, with the missing grant to record) and `wait` mode asks the
+ *    creator.
+ * Grants never lift a deny. The caller records the missing grant and the Redis ask record.
+ */
+export async function decideGitPush(db, config, input) {
+    const repo = normalizeGitRepo(input.repo);
+    if (repo === null)
+        return { decision: "deny", reason: "invalid_repo", repo: null };
+    const host = input.host.toLowerCase();
+    const connector = await db
+        .selectFrom("connectors")
+        .select(["auth", "status", "git_push_policy"])
+        .where("id", "=", input.connectorId)
+        .where("org_id", "=", input.orgId)
+        .where("deleted_at", "is", null)
+        .executeTakeFirst();
+    if (connector?.status !== "active") {
+        return { decision: "deny", reason: "unavailable", repo };
+    }
+    let member;
+    if (personalAuth(connector.auth)) {
+        const row = await db
+            .selectFrom("connector_tool_account_policies")
+            .select("policy")
+            .where("connector_id", "=", input.connectorId)
+            .where("account_id", "=", input.accountId)
+            .where("tool_name", "=", gitPushPolicyName(host, repo))
+            .executeTakeFirst();
+        member = row?.policy;
+    }
+    const base = gitPushBase({ orgDefault: connector.git_push_policy, member });
+    if (base.policy === "deny")
+        return { decision: "deny", reason: base.reason, repo };
+    // what an unattended run may not do at all comes before every allow (as the tool policy)
+    const key = gitPushGrantKey(repo);
+    const unattended = input.unattended !== undefined
+        ? input.unattended
+        : await unattendedRunOf(db, config, input.orgId, input.runId);
+    const rules = unattendedRules(unattended) ? unattended : null;
+    if (rules !== null && gitPushForbidden(rules.forbiddenTools, key)) {
+        return { decision: "deny", reason: "forbidden", repo };
+    }
+    if (base.policy === "allow")
+        return { decision: "allow", reason: base.reason, repo };
+    if (await hasRunGrant(db, input, host, repo)) {
+        return { decision: "allow", reason: "run_grant", repo };
+    }
+    if (rules !== null) {
+        const granted = await db
+            .selectFrom("scheduled_task_grants")
+            .select("tool_key")
+            .where("task_id", "=", rules.taskId)
+            .where("tool_key", "in", [GIT_PUSH_GRANT, key])
+            .executeTakeFirst();
+        if (granted !== undefined)
+            return { decision: "allow", reason: "task_grant", repo };
+        if (rules.unattendedAsk === "fail") {
+            return {
+                decision: "deny",
+                reason: "unattended",
+                repo,
+                missingGrant: { taskRunId: rules.taskRunId, key },
+            };
+        }
+    }
+    return { decision: "ask", reason: "ask", repo };
+}
+/** The runs of the tree whose budget run is `root`. */
+const treeOf = (db, root) => db
+    .selectFrom("runs")
+    .select("id")
+    .where((eb) => eb.or([eb("id", "=", root), eb("budget_run_id", "=", root)]));
+/**
+ * Whether the run tree holds a run grant for this push: an approved `once` git ask of the tree in
+ * the org about the same host, repository and connector, asked of the same actor, while the tree's
+ * root run has not ended (a grant ends with its run; a later run of the same budget window does
+ * not inherit it). An `always` decision is the member's policy row and is read there, not here.
+ */
+async function hasRunGrant(db, input, host, repo) {
+    const root = await budgetRunOf(db, input.runId);
+    const live = await db
+        .selectFrom("runs")
+        .select("id")
+        .where("id", "=", root)
+        .where("status", "in", LIVE_RUN)
+        .executeTakeFirst();
+    if (live === undefined)
+        return false;
+    const row = await db
+        .selectFrom("approvals")
+        .select("id")
+        .where("kind", "=", "git")
+        .where("org_id", "=", input.orgId)
+        .where("connector_id", "=", input.connectorId)
+        .where("requested_for", "=", input.accountId)
+        .where("status", "=", "approved")
+        .where("scope", "=", "once")
+        .where(sql `detail->>'repo'`, "=", repo)
+        .where(sql `lower(detail->>'host')`, "=", host)
+        .where("run_id", "in", treeOf(db, root))
+        .executeTakeFirst();
+    return row !== undefined;
+}
+/**
+ * The run tree's git asks (the network asks' rules, network ask-to-allow spec §6.8): the
+ * repositories granted and refused in the tree (keyed `<host>/<owner>/<repo>`, {@link gitRepoKey}),
+ * this run's asks, a pending ask of the tree.
+ */
+export async function gitRunState(db, runId) {
+    const root = await budgetRunOf(db, runId);
+    const rows = await db
+        .selectFrom("approvals")
+        .select(["run_id", "status", "scope", "detail"])
+        .where("kind", "=", "git")
+        .where("run_id", "in", treeOf(db, root))
+        .execute();
+    const state = { granted: new Set(), refused: new Set(), asks: 0, pending: false };
+    for (const r of rows) {
+        if (r.run_id === runId)
+            state.asks++;
+        const d = r.detail;
+        if (r.status === "pending")
+            state.pending = true;
+        else if (typeof d?.repo !== "string" || typeof d.host !== "string")
+            continue;
+        else if (r.status === "approved" && r.scope === "once") {
+            state.granted.add(gitRepoKey(d.host, d.repo));
+        }
+        else if (REFUSING.has(r.status))
+            state.refused.add(gitRepoKey(d.host, d.repo));
+    }
+    return state;
+}

package/dist/tools/info.d.ts

@@ -69,9 +69,9 @@ export interface ToolInfoDeps {
  * - Extension tools resolve deployment-wide (from the loaded host), not per org: a tool of an
  *   extension that is not enabled in this org still answers `source: extension` with its title.
  *   That is deliberate: old conversation logs keep their labels, and the data is not sensitive.
- * - A key whose prefix is both a loaded extension's name and a connector slug resolves to the
- *   extension. When an agent's tools are built, the registry's `claim()` reports that collision;
- *   here it only changes the label.
+ * - Extension and connector keys never compete for one key: extension tools are
+ *   `plugin__<plugin>__<tool>` and connector tools `mcp__<slug>__<tool>`, so an extension name and
+ *   a connector slug may be the same.
  */
 export declare function toolInfo(deps: ToolInfoDeps, orgId: string, keys: readonly string[]): Promise<ToolInfo[]>;
 /** `GET /conversations/:id/tools`: {@link toolInfo} for a conversation the viewer can read. */

package/dist/tools/info.js

@@ -39,9 +39,9 @@ const display = (spec) => ({
  * - Extension tools resolve deployment-wide (from the loaded host), not per org: a tool of an
  *   extension that is not enabled in this org still answers `source: extension` with its title.
  *   That is deliberate: old conversation logs keep their labels, and the data is not sensitive.
- * - A key whose prefix is both a loaded extension's name and a connector slug resolves to the
- *   extension. When an agent's tools are built, the registry's `claim()` reports that collision;
- *   here it only changes the label.
+ * - Extension and connector keys never compete for one key: extension tools are
+ *   `plugin__<plugin>__<tool>` and connector tools `mcp__<slug>__<tool>`, so an extension name and
+ *   a connector slug may be the same.
  */
 export async function toolInfo(deps, orgId, keys) {
     const unique = [...new Set(keys)];

package/dist/tools/network-asks.d.ts

@@ -107,3 +107,8 @@ export declare const withNetworkNotes: (text: string, notes: readonly string[])
  * {@link NETWORK_ASK_CLIPPED_NOTE}. The caller archives large output first, so this rarely cuts.
  */
 export declare function clipKept(content: string): string;
+/**
+ * `content` within {@link NETWORK_ASK_KEPT_MAX_BYTES} (UTF-8): unchanged when it fits, else its
+ * head and then `note` on a line of its own (the git asks clip with their own note).
+ */
+export declare function clipKeptWith(content: string, note: string): string;

package/dist/tools/network-asks.js

@@ -210,13 +210,20 @@ export const withNetworkNotes = (text, notes) => notes.length === 0 ? text : `${
  * {@link NETWORK_ASK_CLIPPED_NOTE}. The caller archives large output first, so this rarely cuts.
  */
 export function clipKept(content) {
+    return clipKeptWith(content, NETWORK_ASK_CLIPPED_NOTE);
+}
+/**
+ * `content` within {@link NETWORK_ASK_KEPT_MAX_BYTES} (UTF-8): unchanged when it fits, else its
+ * head and then `note` on a line of its own (the git asks clip with their own note).
+ */
+export function clipKeptWith(content, note) {
     const bytes = Buffer.from(content, "utf8");
     if (bytes.length <= NETWORK_ASK_KEPT_MAX_BYTES)
         return content;
-    const room = NETWORK_ASK_KEPT_MAX_BYTES - Buffer.byteLength(NETWORK_ASK_CLIPPED_NOTE) - 1;
+    const room = NETWORK_ASK_KEPT_MAX_BYTES - Buffer.byteLength(note) - 1;
     // a cut inside a multi-byte character drops it rather than keeping half of it
     const head = new TextDecoder("utf-8", { fatal: false })
         .decode(bytes.subarray(0, room))
         .replace(/�$/, "");
-    return `${head}\n${NETWORK_ASK_CLIPPED_NOTE}`;
+    return `${head}\n${note}`;
 }

package/dist/tools/tools.module.js

@@ -33,7 +33,7 @@ import { WebPages } from "./builtins/web/page-cache.js";
 import { ConnectorAccountPolicies } from "./connector-account-policies.js";
 import { ConnectorContent } from "./connector-content.js";
 import { ConnectorsService } from "./connectors.service.js";
-import { Credentials } from "./credentials.js";
+import { CredentialsModule } from "./credentials.module.js";
 import { DeviceOpResolver } from "./device-op-resolver.js";
 import { ToolDrift } from "./drift.js";
 import { ConversationToolInfo, OrgExtensionTools } from "./info.js";
@@ -83,9 +83,10 @@ ToolsModule = __decorate([
             QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
             // a trial run's approvals become its scheduled task's grants (scheduled tasks spec §7)
             ScheduledTaskStoreModule,
+            // connector credentials (also the git gateway's, without importing this module)
+            CredentialsModule,
         ],
         providers: [
-            Credentials,
             ToolOutputs,
             BuiltinTools,
             // `ScheduleUpdate`'s write in one transaction (scheduled tasks spec §11)
@@ -112,7 +113,7 @@ ToolsModule = __decorate([
         ],
         exports: [
             ScheduleToolsPort,
-            Credentials,
+            CredentialsModule,
             ToolOutputs,
             BuiltinTools,
             ToolRegistry,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/kernel",
-  "version": "0.1.0-rc.26",
+  "version": "0.1.0-rc.28",
   "description": "Capybara kernel: config, database, plugin host and HTTP API of the Capybara agent platform",
   "license": "Apache-2.0",
   "repository": {
@@ -65,7 +65,7 @@
     "yaml": "^2.9.1",
     "yauzl": "3.4.0",
     "zod": "^4.6.7",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.20"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.21"
   },
   "devDependencies": {
     "@langchain/langgraph-checkpoint-validation": "^1.2.0",
@@ -74,7 +74,7 @@
     "@types/ws": "^8.18.2",
     "@types/yauzl": "3.4.0",
     "ws": "^8.22.0",
-    "@capybara-hq/testing": "0.1.0-rc.17"
+    "@capybara-hq/testing": "0.1.0-rc.18"
   },
   "scripts": {
     "build": "tsc -b"

package/src/migrations/0126_git_gateway.sql

@@ -0,0 +1,10 @@
+-- Git credentials for sandboxes (spec 2026-11-12-sandbox-git-credentials-design.md): a connector
+-- may declare the git hosts it can serve, and an org-owned one may be used as the source of the
+-- git gateway (personal connectors are always sources). `git_hosts` is null for connectors that
+-- declare none.
+ALTER TABLE connectors ADD COLUMN IF NOT EXISTS git_hosts jsonb;
+ALTER TABLE connectors ADD COLUMN IF NOT EXISTS use_for_git boolean NOT NULL DEFAULT false;
+
+-- An approval of kind 'git' asks for a git operation through the gateway (widening 0114's CHECK).
+ALTER TABLE approvals DROP CONSTRAINT IF EXISTS approvals_kind_check;
+ALTER TABLE approvals ADD CONSTRAINT approvals_kind_check CHECK (kind IN ('tool', 'network', 'git'));

package/src/migrations/0127_git_push_policy.sql

@@ -0,0 +1,12 @@
+-- The org's push policy for a connector's git hosts (sandbox git credentials spec §7): the
+-- connector's virtual tool `git_push` (`allow` / `ask` / `deny`, default `ask`). It has no row in
+-- `connector_tools` (that table mirrors the tools the connector serves, kept in step by drift
+-- review), so it is the connector's own column. A member's standing allow for one repository is a
+-- `connector_tool_account_policies` row named `git_push:<host>/<owner>/<repo>` (no schema change).
+ALTER TABLE connectors ADD COLUMN IF NOT EXISTS git_push_policy text NOT NULL DEFAULT 'ask';
+ALTER TABLE connectors DROP CONSTRAINT IF EXISTS connectors_git_push_policy_check;
+ALTER TABLE connectors ADD CONSTRAINT connectors_git_push_policy_check
+  CHECK (git_push_policy IN ('allow', 'ask', 'deny'));
+
+-- Run grants and the per-run caps read the git asks of a run tree.
+CREATE INDEX IF NOT EXISTS approvals_git_run_idx ON approvals (run_id) WHERE kind = 'git';

package/src/migrations/0128_scheduled_task_plugin_disabled.sql

@@ -0,0 +1,10 @@
+-- A chat task whose channel extension is disabled in the org skips its runs with `plugin_disabled`
+-- (scheduled tasks spec §11), distinct from `target_gone`: the task stays active and recovers when
+-- the extension is enabled again. Widening the inline CHECK of 0113 (PG's default name
+-- scheduled_task_runs_skip_reason_check): drop and add in the file's one transaction, idempotent.
+ALTER TABLE scheduled_task_runs DROP CONSTRAINT IF EXISTS scheduled_task_runs_skip_reason_check;
+ALTER TABLE scheduled_task_runs ADD CONSTRAINT scheduled_task_runs_skip_reason_check
+  CHECK (skip_reason IN ('missed', 'overlap', 'rate_limited', 'queue_paused',
+    'removed', 'device_offline', 'creator_inactive', 'agent_gone', 'target_gone',
+    'conversation_gone', 'org_disabled', 'unsupported_target', 'task_deleted', 'task_paused',
+    'plugin_disabled'));

package/src/migrations/0129_connector_plugin_disabled.sql

@@ -0,0 +1,5 @@
+-- A connector's plugin was switched off in its org: the connector is kept with its endpoint and
+-- credentials but disabled, and marked with the plugin (the catalog item) that switched it off, so
+-- switching the plugin back on re-enables exactly the connectors it disabled. A connector an org
+-- admin disabled by hand has no marker (null) and stays disabled.
+ALTER TABLE connectors ADD COLUMN IF NOT EXISTS disabled_by_plugin_id uuid;