@pulsemcp/air-core 0.0.1

package/schemas/air.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/air.schema.json",
+  "title": "AIR Configuration",
+  "description": "Root configuration file for the AIR framework. Points to artifact index files that define skills, MCP servers, plugins, roots, hooks, and references. Each artifact property is an array of paths — files are loaded and merged in order, with later entries overriding earlier ones by ID.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for validation."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 100,
+      "pattern": "^[a-zA-Z0-9_-]+$",
+      "description": "Unique identifier for this AIR configuration."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Human-readable description of this AIR configuration scope (e.g., 'Acme Corp engineering team agent configs')."
+    },
+    "skills": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to skills index files. Merged in order — later entries override earlier ones by ID."
+    },
+    "references": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to references index files. Merged in order — later entries override earlier ones by ID."
+    },
+    "mcp": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to MCP server configuration files. Merged in order — later entries override earlier ones by ID."
+    },
+    "plugins": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to plugins index files. Merged in order — later entries override earlier ones by ID."
+    },
+    "roots": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to roots index files. Merged in order — later entries override earlier ones by ID."
+    },
+    "hooks": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to hooks index files. Merged in order — later entries override earlier ones by ID."
+    }
+  },
+  "required": ["name"],
+  "additionalProperties": false
+}

package/schemas/hooks.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/hooks.schema.json",
+  "title": "AIR Hooks Index",
+  "description": "Index of hooks that run in response to agent lifecycle events. Hooks are shell commands triggered at specific points during an agent session.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for validation."
+    }
+  },
+  "additionalProperties": {
+    "$ref": "#/$defs/Hook"
+  },
+  "propertyNames": {
+    "pattern": "^[$a-zA-Z0-9_-]+$",
+    "description": "Hook identifier key. Must be alphanumeric with hyphens or underscores."
+  },
+  "$defs": {
+    "Hook": {
+      "type": "object",
+      "description": "A hook that runs a command in response to an agent lifecycle event.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z0-9_-]+$",
+          "description": "Unique identifier for this hook. Must match the key in the parent object."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Human-readable display name for the hook."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "description": "Concise description of what this hook does."
+        },
+        "event": {
+          "type": "string",
+          "enum": [
+            "session_start",
+            "session_end",
+            "pre_tool_call",
+            "post_tool_call",
+            "pre_commit",
+            "post_commit",
+            "notification"
+          ],
+          "description": "Lifecycle event that triggers this hook."
+        },
+        "command": {
+          "type": "string",
+          "description": "Shell command to execute when the event fires."
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Arguments to pass to the command."
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Environment variables for the hook process."
+        },
+        "timeout_seconds": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Maximum execution time in seconds before the hook is killed."
+        },
+        "matcher": {
+          "type": "string",
+          "description": "Regex pattern to match against event data. Hook only fires when matched."
+        }
+      },
+      "required": ["id", "description", "event", "command"],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/mcp.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/mcp.schema.json",
+  "title": "AIR MCP Servers Configuration",
+  "description": "Configuration file defining MCP (Model Context Protocol) servers. Follows the mcp.json open standard — a flat map of server names to fully-resolved connection configurations.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for validation."
+    }
+  },
+  "additionalProperties": {
+    "$ref": "#/$defs/ServerConfiguration"
+  },
+  "propertyNames": {
+    "pattern": "^[$a-zA-Z0-9_\\[\\]-]+$",
+    "description": "Server name (identifier key). Must be alphanumeric with hyphens, underscores, or brackets allowed."
+  },
+  "$defs": {
+    "OAuthConfiguration": {
+      "type": "object",
+      "description": "OAuth configuration for remote servers using OAuth authorization.",
+      "properties": {
+        "clientId": {
+          "type": "string",
+          "description": "OAuth client ID. If omitted, the client uses Dynamic Client Registration (DCR) or discovery."
+        },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "OAuth scopes to request in the authorization request. Passed as the scope parameter (RFC 6749 §3.3)."
+        },
+        "redirectUri": {
+          "type": "string",
+          "format": "uri",
+          "description": "Redirect URI for the OAuth callback. For CLI/desktop clients this is typically http://localhost:{port}/callback (RFC 8252)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "ServerConfiguration": {
+      "type": "object",
+      "description": "Configuration for a single MCP server.",
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Human-readable display name for the server."
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Human-readable description of what the server provides."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["stdio", "sse", "streamable-http"],
+          "description": "Transport type. 'stdio' for local process servers, 'sse' for Server-Sent Events, 'streamable-http' for HTTP streaming."
+        },
+        "command": {
+          "type": "string",
+          "description": "Executable command to run for stdio servers. Supports ${ENV_VAR} interpolation."
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Command-line arguments for stdio servers. Supports ${ENV_VAR} interpolation."
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Environment variables for the server process. Values support ${ENV_VAR} interpolation."
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Endpoint URL for sse or streamable-http servers. Supports ${ENV_VAR} interpolation."
+        },
+        "headers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "HTTP headers for remote servers. Values support ${ENV_VAR} interpolation."
+        },
+        "oauth": {
+          "$ref": "#/$defs/OAuthConfiguration"
+        }
+      },
+      "required": ["type"],
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "type": { "const": "stdio" }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "required": ["command"],
+            "properties": {
+              "url": false,
+              "headers": false,
+              "oauth": false
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": { "enum": ["sse", "streamable-http"] }
+            },
+            "required": ["type"]
+          },
+          "then": {
+            "required": ["url"],
+            "properties": {
+              "command": false,
+              "args": false
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/plugins.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/plugins.schema.json",
+  "title": "AIR Plugins Index",
+  "description": "Index of agent plugins available in this AIR configuration. Plugins extend agent capabilities beyond what MCP servers and skills provide. AIR plugins are agent-agnostic and translated to agent-specific formats at session start time.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for validation."
+    }
+  },
+  "additionalProperties": {
+    "$ref": "#/$defs/Plugin"
+  },
+  "propertyNames": {
+    "pattern": "^[$a-zA-Z0-9_-]+$",
+    "description": "Plugin identifier key. Must be alphanumeric with hyphens or underscores."
+  },
+  "$defs": {
+    "Plugin": {
+      "type": "object",
+      "description": "An agent plugin that extends capabilities via external commands.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z0-9_-]+$",
+          "description": "Unique identifier for this plugin. Must match the key in the parent object."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Human-readable display name for the plugin."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "description": "Concise description of what this plugin does."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["command"],
+          "description": "Plugin type. Currently only 'command' is supported."
+        },
+        "command": {
+          "type": "string",
+          "description": "Executable command to run for this plugin."
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Command-line arguments for the plugin command."
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Environment variables for the plugin process. Values support ${ENV_VAR} interpolation."
+        },
+        "timeout_seconds": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Maximum execution time in seconds before the plugin is killed."
+        }
+      },
+      "required": ["id", "description", "type", "command"],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/references.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/references.schema.json",
+  "title": "AIR References Index",
+  "description": "Index of reference documents shared across skills and agents. References are broken out from skills to keep documentation DRY — a single reference can be used by multiple skills.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for validation."
+    }
+  },
+  "additionalProperties": {
+    "$ref": "#/$defs/Reference"
+  },
+  "propertyNames": {
+    "pattern": "^[$a-zA-Z0-9_-]+$",
+    "description": "Reference identifier key. Must be alphanumeric with hyphens or underscores."
+  },
+  "$defs": {
+    "Reference": {
+      "type": "object",
+      "description": "A shared reference document that can be attached to multiple skills.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z0-9_-]+$",
+          "description": "Unique identifier for this reference. Must match the key in the parent object."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Human-readable display name for the reference."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "description": "Concise description of what knowledge this reference contains."
+        },
+        "file": {
+          "type": "string",
+          "description": "Relative path to the reference document file (typically Markdown)."
+        }
+      },
+      "required": ["id", "description", "file"],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/roots.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/roots.schema.json",
+  "title": "AIR Roots Index",
+  "description": "Index of agent root configurations. A root is a self-contained agent workspace — a git repository (or subdirectory within one) that contains everything an agent needs to operate in a specific domain.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for validation."
+    }
+  },
+  "additionalProperties": {
+    "$ref": "#/$defs/Root"
+  },
+  "propertyNames": {
+    "pattern": "^[$a-zA-Z0-9_-]+$",
+    "description": "Root identifier key. Must be alphanumeric with hyphens or underscores."
+  },
+  "$defs": {
+    "Root": {
+      "type": "object",
+      "description": "An agent root — a self-contained workspace for a specific domain.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z0-9_-]+$",
+          "description": "Unique identifier for this root. Must match the key in the parent object."
+        },
+        "display_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Human-readable display name."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "description": "What this agent root is for. Should be clear to anyone in the organization."
+        },
+        "url": {
+          "type": "string",
+          "description": "Git repository URL for this root."
+        },
+        "default_branch": {
+          "type": "string",
+          "description": "Default branch to use when cloning (defaults to 'main')."
+        },
+        "subdirectory": {
+          "type": "string",
+          "description": "Path within the repository to the root directory (for monorepo setups)."
+        },
+        "default_mcp_servers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of MCP servers to activate by default for sessions using this root."
+        },
+        "default_skills": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of skills to make available by default for sessions using this root."
+        },
+        "default_plugins": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of plugins to activate by default for sessions using this root."
+        },
+        "default_hooks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of hooks to activate by default for sessions using this root."
+        },
+        "user_invocable": {
+          "type": "boolean",
+          "description": "Whether this root can be directly invoked by users to start a session.",
+          "default": true
+        },
+        "default_stop_condition": {
+          "type": "string",
+          "description": "Default condition that signals the agent should hand back control (e.g., 'open-reviewed-green-pr')."
+        }
+      },
+      "required": ["name", "description"],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/schemas/air.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/air.schema.json",
+  "title": "AIR Configuration",
+  "description": "Root configuration file for the AIR framework. Points to artifact index files that define skills, MCP servers, plugins, roots, hooks, and references. Each artifact property is an array of paths — files are loaded and merged in order, with later entries overriding earlier ones by ID.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for validation."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 100,
+      "pattern": "^[a-zA-Z0-9_-]+$",
+      "description": "Unique identifier for this AIR configuration."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Human-readable description of this AIR configuration scope (e.g., 'Acme Corp engineering team agent configs')."
+    },
+    "skills": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to skills index files. Merged in order — later entries override earlier ones by ID."
+    },
+    "references": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to references index files. Merged in order — later entries override earlier ones by ID."
+    },
+    "mcp": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to MCP server configuration files. Merged in order — later entries override earlier ones by ID."
+    },
+    "plugins": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to plugins index files. Merged in order — later entries override earlier ones by ID."
+    },
+    "roots": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to roots index files. Merged in order — later entries override earlier ones by ID."
+    },
+    "hooks": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to hooks index files. Merged in order — later entries override earlier ones by ID."
+    }
+  },
+  "required": ["name"],
+  "additionalProperties": false
+}

package/schemas/schemas/hooks.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/hooks.schema.json",
+  "title": "AIR Hooks Index",
+  "description": "Index of hooks that run in response to agent lifecycle events. Hooks are shell commands triggered at specific points during an agent session.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for validation."
+    }
+  },
+  "additionalProperties": {
+    "$ref": "#/$defs/Hook"
+  },
+  "propertyNames": {
+    "pattern": "^[$a-zA-Z0-9_-]+$",
+    "description": "Hook identifier key. Must be alphanumeric with hyphens or underscores."
+  },
+  "$defs": {
+    "Hook": {
+      "type": "object",
+      "description": "A hook that runs a command in response to an agent lifecycle event.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z0-9_-]+$",
+          "description": "Unique identifier for this hook. Must match the key in the parent object."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Human-readable display name for the hook."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500,
+          "description": "Concise description of what this hook does."
+        },
+        "event": {
+          "type": "string",
+          "enum": [
+            "session_start",
+            "session_end",
+            "pre_tool_call",
+            "post_tool_call",
+            "pre_commit",
+            "post_commit",
+            "notification"
+          ],
+          "description": "Lifecycle event that triggers this hook."
+        },
+        "command": {
+          "type": "string",
+          "description": "Shell command to execute when the event fires."
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Arguments to pass to the command."
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Environment variables for the hook process."
+        },
+        "timeout_seconds": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Maximum execution time in seconds before the hook is killed."
+        },
+        "matcher": {
+          "type": "string",
+          "description": "Regex pattern to match against event data. Hook only fires when matched."
+        }
+      },
+      "required": ["id", "description", "event", "command"],
+      "additionalProperties": false
+    }
+  }
+}