@sweny-ai/core 0.1.143 → 0.1.145

package/dist/schema.js

@@ -7,7 +7,7 @@
  * parsing untrusted input (JSON/YAML import, Studio editor).
  */
 import { z } from "zod";
-import { EVALUATOR_KINDS, EVAL_POLICIES, MCP_TRANSPORTS, NODE_ON_FAIL, REQUIRES_ON_FAIL, SKILL_CATEGORIES, SKILL_ID_MAX_LENGTH, SKILL_ID_PATTERN, TOOL_ACCESS, WORKFLOW_TYPES, } from "./types.js";
+import { AUTHOR_ASSOCIATIONS, EVALUATOR_KINDS, EVAL_POLICIES, MCP_TRANSPORTS, NODE_ACCESS, NODE_ON_FAIL, REQUIRES_ON_FAIL, SAFE_OUTPUT_APPLIERS, SAFE_OUTPUT_EXPIRES_PATTERN, SAFE_OUTPUT_MAX_CEILING, SAFE_OUTPUT_TYPES, SKILL_CATEGORIES, SKILL_ID_MAX_LENGTH, SKILL_ID_PATTERN, TOOL_ACCESS, TOOL_CLASSES, WORKFLOW_TYPES, } from "./types.js";
 import { sourceZ } from "./sources.js";
 import { workflowInputsZ, WORKFLOW_INPUT_TYPES } from "./inputs.js";
 export { sourceZ };
@@ -244,6 +244,47 @@ export const nodeRetryZ = z
     instruction: z.union([z.string().min(1), retryInstructionAutoZ, retryInstructionReflectZ]).optional(),
 })
     .strict();
+/**
+ * Node / workflow permissions (#365): `read` | `write`, or an object with
+ * `access`, `deny` (portable tool classes) and `strict`. The object form must
+ * declare at least one key.
+ */
+export const nodePermissionsZ = z.union([
+    z.enum(NODE_ACCESS),
+    z
+        .object({
+        access: z.enum(NODE_ACCESS).optional(),
+        deny: z.array(z.enum(TOOL_CLASSES)).min(1).optional(),
+        strict: z.boolean().optional(),
+    })
+        .strict()
+        .refine((p) => p.access !== undefined || p.deny !== undefined || p.strict !== undefined, {
+        message: "permissions must declare at least one of access, deny, strict",
+    }),
+]);
+/** One typed write intent a node may emit (#365). */
+export const safeOutputDeclarationZ = z
+    .object({
+    type: z.enum(SAFE_OUTPUT_TYPES),
+    via: z.string().min(1).optional(),
+    max: z.number().int().min(1).max(SAFE_OUTPUT_MAX_CEILING).optional(),
+    target: z.string().min(1).optional(),
+    title_prefix: z.string().min(1).max(64).optional(),
+    labels: z.array(z.string().min(1)).min(1).optional(),
+    expires: z.string().regex(SAFE_OUTPUT_EXPIRES_PATTERN).optional(),
+})
+    .strict();
+/** Workflow-level safe-output policy (#365): the ceiling and run-wide limits. */
+export const safeOutputsPolicyZ = z
+    .object({
+    allow: z.array(z.enum(SAFE_OUTPUT_TYPES)).min(1).optional(),
+    max: z.number().int().min(1).max(SAFE_OUTPUT_MAX_CEILING).optional(),
+    staged: z.boolean().optional(),
+    trusted_actors: z.array(z.string().min(1)).min(1).optional(),
+    trusted_associations: z.array(z.enum(AUTHOR_ASSOCIATIONS)).min(1).optional(),
+    screen: z.boolean().optional(),
+})
+    .strict();
 export const nodeZ = z
     .object({
     name: z.string().min(1),
@@ -255,6 +296,8 @@ export const nodeZ = z
     tools: nodeToolsZ.optional(),
     fail_soft: z.boolean().optional(),
     on_fail: z.enum(NODE_ON_FAIL).optional(),
+    permissions: nodePermissionsZ.optional(),
+    outputs: z.array(safeOutputDeclarationZ).min(1).optional(),
     rules: nodeSourcesZ.optional(),
     context: nodeSourcesZ.optional(),
     eval: z.array(evaluatorZ).min(1).optional(),
@@ -307,6 +350,8 @@ export const workflowZ = z.object({
     model: z.string().min(1).optional(),
     judge_budget: z.number().int().min(0).optional(),
     inputs: workflowInputsZ.optional(),
+    permissions: nodePermissionsZ.optional(),
+    safe_outputs: safeOutputsPolicyZ.optional(),
 });
 const LEGACY_VERIFY_MESSAGE = "uses the legacy 'verify:' field. It was renamed to 'eval:' in @sweny-ai/core v0.2.0 with a different shape (named evaluators with kind: value | function | judge). " +
     "Migration guide: https://spec.sweny.ai/nodes/#eval";
@@ -548,6 +593,48 @@ export function validateWorkflow(workflow, knownSkills) {
             });
         }
     }
+    // Permissions and safe outputs (#365). The workflow's `permissions` and
+    // `safe_outputs.allow` are a ceiling every node inherits.
+    const wfAccess = typeof workflow.permissions === "string" ? workflow.permissions : workflow.permissions?.access;
+    const allowedOutputs = workflow.safe_outputs?.allow;
+    for (const [nodeId, node] of Object.entries(workflow.nodes)) {
+        const nodeAccess = typeof node.permissions === "string" ? node.permissions : node.permissions?.access;
+        if (wfAccess === "read" && nodeAccess === "write") {
+            errors.push({
+                code: "PERMISSION_CEILING",
+                message: `Node "${nodeId}" asks for permissions write, above the workflow's permissions read`,
+                nodeId,
+            });
+        }
+        const seenTypes = new Set();
+        for (const out of node.outputs ?? []) {
+            if (seenTypes.has(out.type)) {
+                errors.push({
+                    code: "DUPLICATE_OUTPUT",
+                    message: `Node "${nodeId}" declares output "${out.type}" more than once; merge them into one entry`,
+                    nodeId,
+                });
+            }
+            seenTypes.add(out.type);
+            if (allowedOutputs && !allowedOutputs.includes(out.type)) {
+                errors.push({
+                    code: "OUTPUT_NOT_ALLOWED",
+                    message: `Node "${nodeId}" declares output "${out.type}", outside the workflow's safe_outputs.allow [${allowedOutputs.join(", ")}]`,
+                    nodeId,
+                });
+            }
+            if (out.via && !SAFE_OUTPUT_APPLIERS[out.via]?.includes(out.type)) {
+                const supported = Object.entries(SAFE_OUTPUT_APPLIERS)
+                    .filter(([, types]) => types.includes(out.type))
+                    .map(([id]) => id);
+                errors.push({
+                    code: "UNSUPPORTED_OUTPUT",
+                    message: `Node "${nodeId}" output "${out.type}" names via "${out.via}", which cannot apply it (supported: ${supported.join(", ")})`,
+                    nodeId,
+                });
+            }
+        }
+    }
     // Skill references
     if (knownSkills) {
         // Merge workflow inline skills into known set
@@ -705,6 +792,71 @@ export const workflowJsonSchema = {
                 },
             ],
         },
+        Permissions: {
+            description: "What a node's agent may do. 'read' runs it read-only: only access: read skill tools, no external skill MCP servers, no shell, file-write, edit, fetch or subagent built-ins. On the workflow it is the default and the ceiling for every node.",
+            oneOf: [
+                { type: "string", enum: [...NODE_ACCESS] },
+                {
+                    type: "object",
+                    additionalProperties: false,
+                    minProperties: 1,
+                    properties: {
+                        access: { type: "string", enum: [...NODE_ACCESS] },
+                        deny: {
+                            type: "array",
+                            items: { type: "string", enum: [...TOOL_CLASSES] },
+                            minItems: 1,
+                            description: "Built-in tool classes the agent must not have, compiled per harness.",
+                        },
+                        strict: {
+                            type: "boolean",
+                            description: "Exclusive MCP (only the servers sweny injects), and refuse the node on a harness that cannot enforce the policy.",
+                        },
+                    },
+                },
+            ],
+        },
+        SafeOutput: {
+            type: "object",
+            required: ["type"],
+            additionalProperties: false,
+            properties: {
+                type: { type: "string", enum: [...SAFE_OUTPUT_TYPES] },
+                via: {
+                    type: "string",
+                    minLength: 1,
+                    description: "Skill that applies the write. Default: the first node skill that supports the type.",
+                },
+                max: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: SAFE_OUTPUT_MAX_CEILING,
+                    description: "Max writes of this type from this node per run. Default 1.",
+                },
+                target: {
+                    type: "string",
+                    minLength: 1,
+                    description: "Pinned target (GitHub owner/repo, Linear team id). GitHub default: GITHUB_REPOSITORY.",
+                },
+                title_prefix: {
+                    type: "string",
+                    minLength: 1,
+                    maxLength: 64,
+                    description: "Prepended to issue and PR titles that do not already start with it.",
+                },
+                labels: {
+                    type: "array",
+                    items: { type: "string", minLength: 1 },
+                    minItems: 1,
+                    description: "issue / pr: labels always added. label: the only labels the agent may add.",
+                },
+                expires: {
+                    type: "string",
+                    pattern: SAFE_OUTPUT_EXPIRES_PATTERN.source,
+                    description: "Drop an intent older than this when the write stage runs (e.g. 30m, 2h, 7d).",
+                },
+            },
+        },
     },
     properties: {
         id: { type: "string", minLength: 1 },
@@ -739,6 +891,46 @@ export const workflowJsonSchema = {
             minLength: 1,
             description: "Default execution model for every node. Overridable per-node. Free-text passthrough (no registry); resolved as node.model ?? workflow.model ?? executor default.",
         },
+        permissions: {
+            $ref: "#/$defs/Permissions",
+            description: "Default and ceiling for every node's permissions. Absent: write.",
+        },
+        safe_outputs: {
+            type: "object",
+            description: "Workflow-level safe-output policy: the ceiling on output types and run-wide limits.",
+            additionalProperties: false,
+            properties: {
+                allow: {
+                    type: "array",
+                    items: { type: "string", enum: [...SAFE_OUTPUT_TYPES] },
+                    minItems: 1,
+                    description: "Output types any node may declare. Absent: all types.",
+                },
+                max: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: SAFE_OUTPUT_MAX_CEILING,
+                    description: "Total writes per run across all nodes.",
+                },
+                staged: { type: "boolean", description: "Preview every write and apply none." },
+                trusted_actors: {
+                    type: "array",
+                    items: { type: "string", minLength: 1 },
+                    minItems: 1,
+                    description: "GitHub logins whose runs may write.",
+                },
+                trusted_associations: {
+                    type: "array",
+                    items: { type: "string", enum: [...AUTHOR_ASSOCIATIONS] },
+                    minItems: 1,
+                    description: "Author associations (from the GitHub event payload) whose runs may write.",
+                },
+                screen: {
+                    type: "boolean",
+                    description: "One model call that may veto the writes after every deterministic check. It can never authorize one.",
+                },
+            },
+        },
         judge_budget: {
             type: "integer",
             minimum: 0,
@@ -890,6 +1082,16 @@ export const workflowJsonSchema = {
                         enum: [...NODE_ON_FAIL],
                         description: "What to do when this node finishes 'failed' (agent-level failure, or an eval failure that exhausted retries and was not softened by fail_soft). 'halt' (default) stops the workflow with the failure surfaced so a broken node never advances down a conditional edge; 'continue' preserves the legacy fall-through where routing proceeds from the failed node. Distinct from requires.on_fail (the pre-condition gate).",
                     },
+                    permissions: {
+                        $ref: "#/$defs/Permissions",
+                        description: "What this node's agent may do. Absent: read when the node declares outputs, else the workflow's permissions, else write.",
+                    },
+                    outputs: {
+                        type: "array",
+                        items: { $ref: "#/$defs/SafeOutput" },
+                        minItems: 1,
+                        description: "Typed write intents this node may emit with the emit_output tool. sweny applies them after the node, within the declared caps.",
+                    },
                     rules: {
                         $ref: "#/$defs/NodeSources",
                         description: "Per-node rules. Additive by default; set { only: true } to block cascade.",

package/dist/skills/github.js

@@ -229,6 +229,24 @@ export const github = {
                 return reused ? { ...pr, reused: true } : pr;
             },
         },
+        {
+            name: "github_add_labels",
+            access: "write",
+            description: "Add labels to a GitHub issue or pull request",
+            input_schema: {
+                type: "object",
+                properties: {
+                    repo: { type: "string", description: "owner/repo" },
+                    issue_number: { type: "number", description: "Issue or PR number" },
+                    labels: { type: "array", items: { type: "string" }, description: "Labels to add" },
+                },
+                required: ["repo", "issue_number", "labels"],
+            },
+            handler: async (input, ctx) => gh(`/repos/${input.repo}/issues/${input.issue_number}/labels`, ctx, {
+                method: "POST",
+                body: JSON.stringify({ labels: input.labels }),
+            }),
+        },
         {
             name: "github_list_recent_commits",
             access: "read",

package/dist/types.d.ts

@@ -362,6 +362,93 @@ export interface Node {
      * Distinct from `requires.on_fail`, which is the pre-condition gate.
      */
     on_fail?: NodeOnFail;
+    /**
+     * What this node's agent may do (#365). `read` runs the node read-only:
+     * only `access: "read"` skill tools, no external skill MCP servers, no
+     * shell / file-write / edit / fetch / subagent built-ins. Absent: `read`
+     * when the node declares `outputs`, else the workflow's `permissions`,
+     * else `write` (today's behavior).
+     */
+    permissions?: NodePermissions;
+    /**
+     * Typed write intents this node may emit (#365). The agent records them with
+     * the `emit_output` tool; sweny applies them after the node, within the
+     * declared caps. See {@link SafeOutputDeclaration}.
+     */
+    outputs?: SafeOutputDeclaration[];
+}
+/** Node access level. `read` = no write-capable tool reaches the agent. */
+export declare const NODE_ACCESS: readonly ["read", "write"];
+export type NodeAccess = (typeof NODE_ACCESS)[number];
+/** Portable built-in tool classes, compiled per harness (Claude Code: native tool names). */
+export declare const TOOL_CLASSES: readonly ["shell", "write", "edit", "net", "subagent"];
+/** Object form of {@link NodePermissions}. */
+export interface NodePermissionsSpec {
+    access?: NodeAccess;
+    /** Built-in tool classes the agent must not have. */
+    deny?: (typeof TOOL_CLASSES)[number][];
+    /** Exclusive MCP, and refuse the node on a harness that cannot enforce the policy. */
+    strict?: boolean;
+}
+/** `read` / `write` shorthand, or the object form. */
+export type NodePermissions = NodeAccess | NodePermissionsSpec;
+/** Write operations a node may request through `emit_output`. */
+export declare const SAFE_OUTPUT_TYPES: readonly ["comment", "issue", "pr", "label"];
+export type SafeOutputType = (typeof SAFE_OUTPUT_TYPES)[number];
+/**
+ * Skills that can apply each output type. The write stage calls the skill's
+ * own tool handler; a skill not listed here cannot apply safe outputs.
+ */
+export declare const SAFE_OUTPUT_APPLIERS: Readonly<Record<string, readonly SafeOutputType[]>>;
+/** GitHub author associations accepted by `safe_outputs.trusted_associations`. */
+export declare const AUTHOR_ASSOCIATIONS: readonly ["OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR", "FIRST_TIME_CONTRIBUTOR", "FIRST_TIMER", "NONE"];
+export type AuthorAssociation = (typeof AUTHOR_ASSOCIATIONS)[number];
+/** Upper bound on a single output's `max` and on `safe_outputs.max`. */
+export declare const SAFE_OUTPUT_MAX_CEILING = 100;
+/** `expires` grammar: a positive integer and a unit (s, m, h, d). */
+export declare const SAFE_OUTPUT_EXPIRES_PATTERN: RegExp;
+/** One declared output on a node. */
+export interface SafeOutputDeclaration {
+    type: SafeOutputType;
+    /** Skill that applies it. Default: the first node skill that supports the type. */
+    via?: string;
+    /** Max writes of this type from this node per run. Default 1. */
+    max?: number;
+    /** Pinned target (GitHub `owner/repo`, Linear team id). GitHub default: `GITHUB_REPOSITORY`. */
+    target?: string;
+    /** Prepended to issue / PR titles that do not already start with it. */
+    title_prefix?: string;
+    /** issue / pr: labels always added. label: the only labels the agent may add. */
+    labels?: string[];
+    /** Drop an intent older than this when the write stage runs (e.g. `30m`, `2h`, `7d`). */
+    expires?: string;
+}
+/** Workflow-level safe-output policy: the ceiling and run-wide limits. */
+export interface SafeOutputsPolicy {
+    /** Output types any node may declare. Absent: all types. */
+    allow?: SafeOutputType[];
+    /** Total writes per run across all nodes. */
+    max?: number;
+    /** Preview every write and apply none. */
+    staged?: boolean;
+    /** GitHub logins whose runs may write. */
+    trusted_actors?: string[];
+    /** Author associations whose runs may write (from the GitHub event payload). */
+    trusted_associations?: AuthorAssociation[];
+    /** One model call that may veto the writes. It can never authorize one. */
+    screen?: boolean;
+}
+/** What the write stage did with one intent. Metadata only: never a title or body. */
+export interface SafeOutputReceipt {
+    type: string;
+    /** Skill that applied (or would apply) it. */
+    via?: string;
+    status: "applied" | "staged" | "skipped" | "refused" | "vetoed" | "failed";
+    /** Why it was skipped, refused, vetoed or failed. Fixed wording, never model text. */
+    reason?: string;
+    target?: string;
+    /** Issue / PR / comment number or id the write produced. */
+    ref?: string | number;
 }
 /**
  * Per-node skill-tool filter. See {@link Node.tools}.
@@ -424,6 +511,10 @@ export interface Workflow {
      * See `src/inputs.ts` for the field shape and validation rules.
      */
     inputs?: import("./inputs.js").WorkflowInputs;
+    /** Default and ceiling for every node's `permissions` (#365). Absent: `write`. */
+    permissions?: NodePermissions;
+    /** Workflow-level safe-output policy (#365). */
+    safe_outputs?: SafeOutputsPolicy;
 }
 /**
  * Inline skill definition in a workflow's `skills` block.
@@ -490,6 +581,8 @@ export interface NodeResult {
     };
     /** Opinions this run could not honor natively. Always empty for Claude Code. */
     degraded?: string[];
+    /** Safe outputs (#365): what the write stage did with each intent. Absent when the node declares none. */
+    outputs?: SafeOutputReceipt[];
 }
 export interface ToolCall {
     tool: string;
@@ -652,6 +745,12 @@ export interface Claude {
          * (external MCP servers, shell, file-edit built-ins).
          */
         readOnly?: boolean;
+        /**
+         * The node's portable policy (#365), compiled per adapter. Legacy `Claude`
+         * implementations may ignore it; `readOnly` and `disallowedTools` above
+         * carry the same read-only and native-deny intent.
+         */
+        policy?: import("./harness/types.js").NodePolicy;
     }): Promise<NodeResult>;
     /**
      * Evaluate a routing condition — pick one of N choices.

package/dist/types.js

@@ -67,6 +67,35 @@ export const REQUIRES_ON_FAIL = ["fail", "skip"];
 export const NODE_ON_FAIL = ["halt", "continue"];
 /** MCP server transport type. Inferred from command/url when omitted. */
 export const MCP_TRANSPORTS = ["stdio", "http"];
+// ─── Permissions and safe outputs (#365) ─────────────────────────
+/** Node access level. `read` = no write-capable tool reaches the agent. */
+export const NODE_ACCESS = ["read", "write"];
+/** Portable built-in tool classes, compiled per harness (Claude Code: native tool names). */
+export const TOOL_CLASSES = ["shell", "write", "edit", "net", "subagent"];
+/** Write operations a node may request through `emit_output`. */
+export const SAFE_OUTPUT_TYPES = ["comment", "issue", "pr", "label"];
+/**
+ * Skills that can apply each output type. The write stage calls the skill's
+ * own tool handler; a skill not listed here cannot apply safe outputs.
+ */
+export const SAFE_OUTPUT_APPLIERS = {
+    github: ["comment", "issue", "pr", "label"],
+    linear: ["comment", "issue"],
+};
+/** GitHub author associations accepted by `safe_outputs.trusted_associations`. */
+export const AUTHOR_ASSOCIATIONS = [
+    "OWNER",
+    "MEMBER",
+    "COLLABORATOR",
+    "CONTRIBUTOR",
+    "FIRST_TIME_CONTRIBUTOR",
+    "FIRST_TIMER",
+    "NONE",
+];
+/** Upper bound on a single output's `max` and on `safe_outputs.max`. */
+export const SAFE_OUTPUT_MAX_CEILING = 100;
+/** `expires` grammar: a positive integer and a unit (s, m, h, d). */
+export const SAFE_OUTPUT_EXPIRES_PATTERN = /^[1-9][0-9]*(s|m|h|d)$/;
 /**
  * Workflow type discriminator. Cloud uses this to render runs in a
  * type-specific way. Adding a value requires a corresponding renderer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.143",
+  "version": "0.1.145",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"