create-safe-output-type

Add New Safe Output Type

This guide covers adding a new safe output type to process AI agent outputs in JSONL format through a validation pipeline (TypeScript types → JSON schema → JavaScript collection).

Implementation Steps

1. Update JSON Schema (schemas/agent-output.json)

Add object definition in $defs section:

"YourNewTypeOutput": {
  "title": "Your New Type Output",
  "description": "Output for your new functionality",
  "type": "object",
  "properties": {
    "type": {
      "const": "your-new-type"
    },
    "required_field": {
      "type": "string",
      "description": "Description of required field",
      "minLength": 1
    },
    "optional_field": {
      "type": "string", 
      "description": "Description of optional field"
    }
  },
  "required": ["type", "required_field"],
  "additionalProperties": false
}

Add to SafeOutput oneOf array: {"$ref": "#/$defs/YourNewTypeOutput"}

Validation Notes: Use const for type field, minLength: 1 for required strings, additionalProperties: false, oneOf for union types.

2. Update TypeScript Types

File: pkg/workflow/js/types/safe-outputs.d.ts

/**
 * JSONL item for [description]
 */
interface YourNewTypeItem extends BaseSafeOutputItem {
  type: "your-new-type";
  /** Required field description */
  required_field: string;
  /** Optional field description */
  optional_field?: string;
}
}

Add to `SafeOutputItem` union type and export list.

**File**: `pkg/workflow/js/types/safe-outputs-config.d.ts` - Add config interface, add to `SpecificSafeOutputConfig` union, export.

### 3. Update Safe Outputs Tools JSON (`pkg/workflow/js/safe_outputs_tools.json`)

Add tool signature to expose to AI agents:

```json
{
"name": "your_new_type",
"description": "Brief description of what this tool does (use underscores in name, not hyphens)",
"inputSchema": {
 "type": "object",
 "required": ["required_field"],
 "properties": {
   "required_field": {
     "type": "string",
     "description": "Description of the required field"
   },
   "optional_field": {
     "type": "string",
     "description": "Description of the optional field"
   },
   "numeric_field": {
     "type": ["number", "string"],
     "description": "Numeric field that accepts both number and string types"
   }
 },
 "additionalProperties": false
}
}

Guidelines: Use underscores in tool name, match with type field, set additionalProperties: false, use "type": ["number", "string"] for numeric fields.

Important: File is embedded via //go:embed - must rebuild with make build after changes.

4. Update MCP Server JavaScript (If Custom Handler Needed) (pkg/workflow/js/safe_outputs_mcp_server.cjs)

Most types use the default JSONL handler. Add custom handler only if needed for file operations, git commands, or complex validation:

/**
 * Handler for your_new_type safe output
 * @param {Object} args - Arguments passed to the tool
 * @returns {Object} MCP tool response
 */
const yourNewTypeHandler = args => {
  // Perform any custom validation
  if (!args.required_field || typeof args.required_field !== "string") {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            error: "required_field is required and must be a string",
          }),
        },
      ],
      isError: true,
    };
  }