comisai 1.0.4

package/node_modules/@comis/daemon/bundled-skills/skill-creator/references/schema.md

@@ -0,0 +1,101 @@
+# Skill Manifest Schema Reference
+
+Complete reference for SKILL.md frontmatter fields and validation rules.
+
+## Frontmatter Fields
+
+### Required
+
+| Field | Type | Rules |
+|-------|------|-------|
+| `name` | string | 1-64 chars, lowercase alphanumeric + hyphens, no consecutive hyphens, no leading/trailing hyphens. Regex: `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$` |
+| `description` | string | 1-1024 chars. Primary trigger mechanism -- include both what the skill does AND when to use it |
+
+### Optional (top-level)
+
+| Field | Type | Default | Purpose |
+|-------|------|---------|---------|
+| `type` | `"prompt"` | `"prompt"` | Always "prompt" for Markdown instruction skills |
+| `version` | string | - | Semver version string |
+| `license` | string | - | SPDX license identifier |
+| `userInvocable` | boolean | `true` | Whether users can invoke via `/skill:name` |
+| `disableModelInvocation` | boolean | `false` | When true, hidden from model's available skills listing |
+| `allowedTools` | string[] | `[]` | Tool restrictions when skill is active; empty = no restriction |
+| `argumentHint` | string | - | Hint text shown to users (e.g., "[query]") |
+| `permissions` | object | see below | Required permissions |
+| `inputSchema` | object | - | JSON Schema for input parameters |
+| `metadata` | Record<string, string> | - | Arbitrary key-value pairs |
+
+### Permissions Block
+
+```yaml
+permissions:
+  fsRead: []      # Filesystem read paths
+  fsWrite: []     # Filesystem write paths
+  net: []         # Network domains
+  env: []         # Environment variables (read-only)
+```
+
+### Comis Namespace (`comis:`)
+
+Platform-specific fields that only apply within Comis. Other pi-coding-agent hosts ignore this block.
+
+```yaml
+comis:
+  os: ["linux", "darwin"]           # Target operating systems (coerced: string -> [string])
+  requires:                          # External prerequisites
+    bins: ["ripgrep", "fd"]          # Required binaries on PATH
+    env: ["OPENAI_API_KEY"]          # Required environment variables
+  skill-key: my-custom-key           # Explicit skill key override (slug format)
+  primary-env: discord               # Display/grouping hint for primary environment
+  command-dispatch: my-command       # Metadata-only dispatch tag for command routing
+```
+
+## Body Constraints
+
+- Maximum length: **20,000 characters** (configurable via `skills.promptSkills.maxBodyLength`)
+- Exceeding the limit: body truncated with `[TRUNCATED]` marker appended
+- Ideal: keep SKILL.md body under **500 lines**; use references/ for large docs
+
+## Content Scanning
+
+Skill bodies are scanned at load time for dangerous patterns. **CRITICAL** findings block loading by default.
+
+### Blocked Patterns (CRITICAL severity)
+
+- Shell injection: `$(...)`, backticks with dangerous binaries, `eval()`
+- Pipe to shell: `| bash`, `| sh`, `| zsh`
+- Crypto mining: `stratum://` pools, miner binaries, mining domains
+- Reverse shells: `/dev/tcp`, `nc -e`
+- Obfuscated execution: `base64 -d |`
+- XML breakout: `</available_skills>`, `</skill_invocation>`, `<system>`, `</system>`, `<tool_result>`
+
+### Warning Patterns (WARN severity)
+
+- Environment harvesting: `printenv`, `/proc/self/environ`
+- Long base64 strings (80+ chars)
+- Long hex sequences (20+ pairs)
+- Network fetching: `curl | bash`, `wget -O -`
+
+## Discovery
+
+Skills are found by scanning configured `discoveryPaths` (default: `~/.comis/skills/`):
+
+- **Root .md files**: `.md` files directly in the skills directory root
+- **Recursive SKILL.md**: `SKILL.md` files in any subdirectory
+
+First-loaded-wins on name collision across discovery paths.
+
+## Hot Reload
+
+The skill watcher monitors discovery paths for file changes. After a 400ms debounce, the registry re-discovers all skills. No daemon restart needed -- just save the file and the skill is available.
+
+## Runtime Eligibility
+
+When `comis.requires` or `comis.os` is set, the skill is only available if:
+
+1. Current OS matches `comis.os` (if specified)
+2. All binaries in `comis.requires.bins` exist on PATH
+3. All env vars in `comis.requires.env` are set (via SecretManager)
+
+Failed eligibility checks make the skill invisible to the model -- no error, just not listed.

package/node_modules/@comis/daemon/bundled-skills/skill-creator/scripts/init-skill.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Initialize a new Comis skill from template.
+
+Creates a skill directory with SKILL.md template and optional resource directories.
+
+Usage:
+    python3 init-skill.py <skill-name> [--path <dir>] [--resources scripts,references,assets] [--description "..."]
+
+Examples:
+    python3 init-skill.py my-skill
+    python3 init-skill.py my-skill --path ~/.comis/skills
+    python3 init-skill.py deploy-checker --resources scripts
+    python3 init-skill.py api-helper --resources scripts,references
+    python3 init-skill.py my-skill --description "Build dashboards with charts. Use when user mentions visualization."
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+MAX_NAME_LENGTH = 64
+NAME_REGEX = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
+ALLOWED_RESOURCES = {"scripts", "references", "assets"}
+
+DEFAULT_DESCRIPTION = (
+    "[TODO: What this skill does and when to use it. Be specific -- include trigger "
+    "phrases so the agent recognizes when to activate. Example: 'Build dashboards "
+    "with charts and filters. Use whenever the user mentions dashboards, data "
+    "visualization, or metrics display -- even if they don't say dashboard explicitly.']"
+)
+
+SKILL_TEMPLATE = """---
+name: {name}
+description: {description}
+---
+
+# {title}
+
+[TODO: 1-2 sentences explaining what this skill enables.]
+
+## [TODO: Choose a structure]
+
+Pick the pattern that best fits this skill's purpose:
+
+- **Workflow-based** -- for sequential processes with clear steps
+- **Task-based** -- for skills offering different operations/capabilities
+- **Reference/guidelines** -- for standards, specs, or company policies
+- **Capabilities-based** -- for integrated systems with interrelated features
+
+Patterns can be mixed. Delete this section after choosing.
+
+## [TODO: First main section]
+
+[TODO: Add content. Include:
+- Code samples for technical skills
+- Decision trees for complex workflows
+- Concrete examples with realistic user requests
+- References to scripts/references/assets as needed]
+"""
+
+
+def normalize_name(raw):
+    """Normalize a skill name to lowercase hyphen-case."""
+    name = raw.strip().lower()
+    name = re.sub(r"[^a-z0-9]+", "-", name)
+    name = name.strip("-")
+    name = re.sub(r"-{2,}", "-", name)
+    return name
+
+
+def title_case(name):
+    """Convert hyphenated name to Title Case."""
+    return " ".join(word.capitalize() for word in name.split("-"))
+
+
+def main():
+    p = argparse.ArgumentParser(description="Initialize a new Comis skill")
+    p.add_argument("skill_name", help="Skill name (normalized to hyphen-case)")
+    p.add_argument("--path", default=".", help="Parent directory for the skill (default: current dir)")
+    p.add_argument("--resources", default="", help="Comma-separated: scripts,references,assets")
+    p.add_argument("--description", default="", help="Skill description (skips TODO placeholder)")
+    args = p.parse_args()
+
+    name = normalize_name(args.skill_name)
+    if not name:
+        print("ERROR: Skill name must include at least one letter or digit.")
+        sys.exit(1)
+    if len(name) > MAX_NAME_LENGTH:
+        print(f"ERROR: Name '{name}' is {len(name)} chars (max {MAX_NAME_LENGTH}).")
+        sys.exit(1)
+    if not NAME_REGEX.match(name):
+        print(f"ERROR: Name '{name}' invalid (must be lowercase alphanumeric + hyphens).")
+        sys.exit(1)
+    if name != args.skill_name:
+        print(f"Note: Normalized '{args.skill_name}' to '{name}'")
+
+    # Parse resources
+    resources = []
+    if args.resources:
+        for r in args.resources.split(","):
+            r = r.strip()
+            if r and r not in ALLOWED_RESOURCES:
+                print(f"ERROR: Unknown resource type '{r}'. Allowed: {', '.join(sorted(ALLOWED_RESOURCES))}")
+                sys.exit(1)
+            if r:
+                resources.append(r)
+
+    # Create skill directory
+    skill_dir = Path(args.path).resolve() / name
+    if skill_dir.exists():
+        print(f"ERROR: Directory already exists: {skill_dir}")
+        sys.exit(1)
+
+    skill_dir.mkdir(parents=True)
+    print(f"Created: {skill_dir}/")
+
+    # Write SKILL.md
+    desc = args.description if args.description else DEFAULT_DESCRIPTION
+    content = SKILL_TEMPLATE.format(name=name, title=title_case(name), description=desc)
+    (skill_dir / "SKILL.md").write_text(content)
+    print("Created: SKILL.md")
+
+    # Create resource directories
+    for r in resources:
+        (skill_dir / r).mkdir()
+        print(f"Created: {r}/")
+
+    print(f"\nSkill '{name}' initialized at {skill_dir}")
+    print("\nNext steps:")
+    print("1. Edit SKILL.md -- fill in the TODO items")
+    print("2. Add resources to scripts/, references/, assets/ as needed")
+    print("3. Run validate-skill.py to check before use")
+
+
+if __name__ == "__main__":
+    main()

package/node_modules/@comis/daemon/bundled-skills/skill-creator/scripts/validate-skill.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""Validate a SKILL.md file against Comis skill manifest rules.
+
+Checks frontmatter fields, name format, description length, body size,
+content scanning patterns, and directory structure.
+
+Usage:
+    python3 validate-skill.py /path/to/skill-dir
+    python3 validate-skill.py /path/to/SKILL.md
+"""
+
+import argparse
+import os
+import re
+import sys
+import json
+
+# ---------------------------------------------------------------------------
+# Constants matching Comis schema validation (schema-skills.ts, schema.ts)
+# ---------------------------------------------------------------------------
+
+NAME_REGEX = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
+NAME_MAX = 64
+DESC_MAX = 1024
+BODY_MAX = 20_000
+
+VALID_TOP_FIELDS = {
+    "name", "description", "type", "version", "license",
+    "userInvocable", "disableModelInvocation", "allowedTools",
+    "argumentHint", "permissions", "inputSchema", "metadata", "comis",
+}
+
+VALID_COMIS_FIELDS = {
+    "os", "requires", "skill-key", "primary-env", "command-dispatch",
+}
+
+VALID_PERMISSIONS_FIELDS = {"fsRead", "fsWrite", "net", "env"}
+
+# Content scanning patterns matching the exact Comis scanner (injection-patterns.ts)
+# These are applied AFTER stripping fenced code blocks to reduce false positives
+# from documentation examples. The real scanner applies to the raw body.
+
+# CRITICAL severity -- will block loading
+CRITICAL_PATTERNS = [
+    (r"\$\([^)]*(?:curl|wget|bash|sh|nc|ncat)\b[^)]*\)", "Exec injection: $(command) with dangerous binary"),
+    (r"`[^`]*\b(?:curl|wget|bash|sh|nc|ncat)\b(?:\s+[^`]+)`", "Exec injection: backtick with dangerous binary"),
+    (r"\beval\s*\(\s*[\"'`]", "Exec injection: eval() with string argument"),
+    (r"\|\s*(?:bash|sh|zsh|ksh)\b", "Pipe to shell interpreter"),
+    (r"stratum\+?(?:tcp|ssl)://", "Crypto mining: stratum pool"),
+    (r"\b(?:xmrig|cgminer|bfgminer|ethminer|minerd|cpuminer)\b", "Crypto mining: miner binary"),
+    (r"/dev/tcp/", "Reverse shell: /dev/tcp"),
+    (r"\bnc\s+-e\b", "Reverse shell: nc -e"),
+    (r"base64\s+(?:-d|--decode)\s*\|", "Obfuscated execution: base64 decode pipe"),
+    (r"</available_skills>", "XML breakout: </available_skills>"),
+    (r"</skill_invocation>", "XML breakout: </skill_invocation>"),
+    (r"<system>", "XML breakout: <system>"),
+    (r"</system>", "XML breakout: </system>"),
+    (r"<tool_result>", "XML breakout: <tool_result>"),
+]
+
+# WARN severity -- logged but does not block loading
+WARN_PATTERNS = [
+    (r"\bprintenv\b", "Env harvesting: printenv"),
+    (r"/proc/self/environ", "Env harvesting: /proc/self/environ"),
+    (r"[A-Za-z0-9+/]{80,}={0,2}", "Long base64 string (80+ chars)"),
+    (r"(?:\\x[0-9a-fA-F]{2}){20,}", "Long hex sequence (20+ pairs)"),
+]
+
+
+def strip_code_fences(text):
+    """Remove fenced code blocks (```...```) to reduce false positives from examples."""
+    return re.sub(r"```[^\n]*\n.*?```", "", text, flags=re.DOTALL)
+
+
+def parse_frontmatter(content):
+    """Parse YAML frontmatter from --- delimited block."""
+    if not content.startswith("---"):
+        return None, content, "File must start with '---'"
+
+    lines = content.split("\n")
+    end_idx = None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        return None, content, "Missing closing '---' marker"
+
+    yaml_block = "\n".join(lines[1:end_idx])
+    body = "\n".join(lines[end_idx + 1:]).strip()
+
+    # Simple YAML parsing (avoid external dependency)
+    try:
+        import yaml
+        fm = yaml.safe_load(yaml_block)
+    except ImportError:
+        # Fallback: basic key-value parsing for simple frontmatter
+        fm = {}
+        for line in yaml_block.split("\n"):
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if ":" in line:
+                key, _, value = line.partition(":")
+                value = value.strip()
+                if value.startswith('"') and value.endswith('"'):
+                    value = value[1:-1]
+                elif value.startswith("'") and value.endswith("'"):
+                    value = value[1:-1]
+                elif value.lower() == "true":
+                    value = True
+                elif value.lower() == "false":
+                    value = False
+                elif value.isdigit():
+                    value = int(value)
+                fm[key.strip()] = value
+    except Exception as e:
+        return None, body, f"YAML parse error: {e}"
+
+    if not isinstance(fm, dict):
+        return None, body, "Frontmatter must be a YAML object"
+
+    return fm, body, None
+
+
+def validate(path):
+    """Validate a skill directory or SKILL.md file. Returns (errors, warnings)."""
+    errors = []
+    warnings = []
+
+    # Resolve path
+    if os.path.isdir(path):
+        skill_dir = path
+        skill_file = os.path.join(path, "SKILL.md")
+    elif os.path.isfile(path):
+        skill_file = path
+        skill_dir = os.path.dirname(path)
+    else:
+        return [f"Path does not exist: {path}"], []
+
+    if not os.path.isfile(skill_file):
+        return [f"SKILL.md not found at: {skill_file}"], []
+
+    with open(skill_file, "r") as f:
+        content = f.read()
+
+    # Parse frontmatter
+    fm, body, parse_err = parse_frontmatter(content)
+    if parse_err:
+        errors.append(f"Frontmatter: {parse_err}")
+        return errors, warnings
+    if fm is None:
+        errors.append("Frontmatter: empty or missing")
+        return errors, warnings
+
+    # Required fields
+    if "name" not in fm:
+        errors.append("Missing required field: name")
+    else:
+        name = str(fm["name"])
+        if len(name) > NAME_MAX:
+            errors.append(f"name too long: {len(name)} chars (max {NAME_MAX})")
+        if not NAME_REGEX.match(name):
+            errors.append(f"name '{name}' invalid: must be lowercase alphanumeric + hyphens, no consecutive/leading/trailing hyphens")
+        if "--" in name:
+            errors.append(f"name '{name}' contains consecutive hyphens")
+
+    if "description" not in fm:
+        errors.append("Missing required field: description")
+    else:
+        desc = str(fm["description"])
+        if len(desc) > DESC_MAX:
+            errors.append(f"description too long: {len(desc)} chars (max {DESC_MAX})")
+        if len(desc) < 1:
+            errors.append("description is empty")
+
+    # Unknown top-level fields
+    for key in fm:
+        if key not in VALID_TOP_FIELDS:
+            warnings.append(f"Unknown top-level field: '{key}' (will cause strict parse failure)")
+
+    # Type field
+    if "type" in fm and fm["type"] != "prompt":
+        errors.append(f"type must be 'prompt', got '{fm['type']}'")
+
+    # Boolean fields
+    for field in ("userInvocable", "disableModelInvocation"):
+        if field in fm and not isinstance(fm[field], bool):
+            errors.append(f"{field} must be boolean, got {type(fm[field]).__name__}")
+
+    # allowedTools
+    if "allowedTools" in fm:
+        if not isinstance(fm["allowedTools"], list):
+            errors.append("allowedTools must be an array")
+
+    # Permissions
+    if "permissions" in fm:
+        perms = fm["permissions"]
+        if isinstance(perms, dict):
+            for key in perms:
+                if key not in VALID_PERMISSIONS_FIELDS:
+                    warnings.append(f"Unknown permissions field: '{key}'")
+        else:
+            errors.append("permissions must be an object")
+
+    # Comis namespace
+    if "comis" in fm and fm["comis"] is not None:
+        comis = fm["comis"]
+        if isinstance(comis, dict):
+            for key in comis:
+                if key not in VALID_COMIS_FIELDS:
+                    warnings.append(f"Unknown comis: field: '{key}'")
+            if "requires" in comis and isinstance(comis["requires"], dict):
+                for rk in comis["requires"]:
+                    if rk not in ("bins", "env"):
+                        warnings.append(f"Unknown comis.requires field: '{rk}'")
+        else:
+            errors.append("comis: must be an object (or omitted)")
+
+    # Body checks
+    if len(body) > BODY_MAX:
+        warnings.append(f"Body is {len(body)} chars (max {BODY_MAX}) -- will be truncated at load time")
+
+    body_lines = body.count("\n") + 1
+    if body_lines > 500:
+        warnings.append(f"Body is {body_lines} lines (recommended max: 500) -- consider using references/")
+
+    # Content scanning (strip code fences to reduce false positives from examples)
+    scannable = strip_code_fences(body)
+    for pattern, desc in CRITICAL_PATTERNS:
+        if re.search(pattern, scannable, re.IGNORECASE):
+            errors.append(f"CRITICAL content scan: {desc}")
+
+    for pattern, desc in WARN_PATTERNS:
+        if re.search(pattern, scannable, re.IGNORECASE):
+            warnings.append(f"Content scan warning: {desc}")
+
+    # Also warn if the raw body (with code fences) would trigger the real scanner
+    for pattern, desc in CRITICAL_PATTERNS:
+        if re.search(pattern, body, re.IGNORECASE) and not re.search(pattern, scannable, re.IGNORECASE):
+            warnings.append(f"Code fence contains scannable pattern (may trigger real scanner): {desc}")
+
+    # Directory structure hints
+    scripts_dir = os.path.join(skill_dir, "scripts")
+    refs_dir = os.path.join(skill_dir, "references")
+    assets_dir = os.path.join(skill_dir, "assets")
+
+    if os.path.isdir(scripts_dir):
+        scripts = [f for f in os.listdir(scripts_dir) if not f.startswith(".")]
+        if scripts:
+            # Check scripts are referenced in body
+            for s in scripts:
+                if s not in body:
+                    warnings.append(f"Bundled script '{s}' not referenced in SKILL.md body")
+
+    return errors, warnings
+
+
+def main():
+    p = argparse.ArgumentParser(description="Validate a Comis SKILL.md")
+    p.add_argument("path", help="Path to skill directory or SKILL.md file")
+    args = p.parse_args()
+
+    errors, warnings = validate(args.path)
+
+    if warnings:
+        print(f"Warnings ({len(warnings)}):")
+        for w in warnings:
+            print(f"  ! {w}")
+        print()
+
+    if errors:
+        print(f"Errors ({len(errors)}):")
+        for e in errors:
+            print(f"  X {e}")
+        print()
+        print("RESULT: INVALID")
+        sys.exit(1)
+    else:
+        print("RESULT: VALID")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/node_modules/@comis/daemon/dist/announcement-batcher.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Announcement batcher for coalescing near-simultaneous sub-agent completions.
+ * When multiple sub-agents complete within seconds of each other for the same
+ * parent session, the batcher debounces and combines their announcements into a
+ * single batched LLM execution -- reducing N sequential parent calls to 1.
+ * Single completions with no siblings deliver after the debounce timer with
+ * original text unmodified (no batching overhead).
+ * @module
+ */
+import { type SessionKey } from "@comis/core";
+export interface QueuedAnnouncement {
+    announcementText: string;
+    announceChannelType: string;
+    announceChannelId: string;
+    callerAgentId: string;
+    callerSessionKey: string;
+    runId: string;
+}
+export interface AnnouncementBatcherDeps {
+    announceToParent: (callerAgentId: string, callerSessionKey: SessionKey, text: string, channelType: string, channelId: string) => Promise<void>;
+    sendToChannel: (channelType: string, channelId: string, text: string, options?: {
+        extra?: Record<string, unknown>;
+    }) => Promise<boolean>;
+    logger?: {
+        debug(obj: Record<string, unknown>, msg: string): void;
+        warn(obj: Record<string, unknown>, msg: string): void;
+    };
+    debounceMs?: number;
+    /** Optional dead-letter queue for persisting fallback delivery failures */
+    deadLetterQueue?: {
+        enqueue(entry: {
+            announcementText: string;
+            channelType: string;
+            channelId: string;
+            runId: string;
+            failedAt: number;
+            attemptCount: number;
+            lastError?: string;
+        }): void;
+    };
+}
+export interface AnnouncementBatcher {
+    enqueue(params: QueuedAnnouncement): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    readonly pending: number;
+}
+/**
+ * Sanitize announcement text for direct user delivery (fallback path).
+ * Extracts human-readable content (Summary or Result sections) and strips
+ * internal metadata (session keys, file paths, condensation stats, subagent
+ * markers, runtime stats). Returns a safe generic message if no extractable
+ * content is found.
+ * Used only in fallback `sendToChannel` calls -- the `announceToParent` path
+ * goes through the LLM which can filter metadata itself.
+ */
+export declare function sanitizeForUser(text: string): string;
+export declare function createAnnouncementBatcher(deps: AnnouncementBatcherDeps): AnnouncementBatcher;