piqrypt_stamp_event

Instructions

Implementation Reference

• src/python/bridge.py:88-120 (handler)

  Core handler - Python function that creates the cryptographic stamp via aiss.stamp_event(), storing the signed event and returning it with chain metadata.

  def stamp_event(params: Dict[str, Any]) -> Dict[str, Any]:
      """
      Stamp an event with a real AISS v2.0 signature.
  
      Args:
          params: dict with agent_name (or agent_id), payload,
                  optional previous_hash, identity_file
  
      Returns:
          dict with event, chain_length, vigil_url, hint
      """
      agent_name  = params.get("agent_name", params.get("agent_id", "default"))
      payload     = params.get("payload", {})
      prev_hash   = params.get("previous_hash")
  
      private_key, agent_id = _get_or_create_identity(agent_name)
  
      event = aiss.stamp_event(private_key, agent_id, payload,
                               previous_hash=prev_hash)
      aiss.store_event(event, agent_name=agent_name)
  
      try:
          events = aiss.load_events(agent_name=agent_name)
          chain_length = len(events)
      except Exception:
          chain_length = 1
  
      return {
          "event": event,
          "chain_length": chain_length,
          "vigil_url": VIGIL_URL,
          "hint": VIGIL_HINT,
      }

• src/index.ts:195-201 (handler)

  MCP call handler - dispatches 'piqrypt_stamp_event' to callPythonBridge('stamp', ...) which invokes the Python bridge with agent_id, payload, and previous_hash.

  case 'piqrypt_stamp_event':
    result = callPythonBridge('stamp', {
      agent_id: args.agent_id,
      payload: args.payload,
      previous_hash: args.previous_hash,
    });
    break;

• src/index.ts:69-90 (registration)

  Tool registration - defines tool name 'piqrypt_stamp_event', description, and inputSchema specifying agent_id, payload (object), and optional previous_hash.

  {
    name: 'piqrypt_stamp_event',
    description: 'Create a tamper-proof cryptographic record of an agent decision. Signs the event with Ed25519, links it to the previous event in a hash chain (AISS v2.0). Call this after every significant agent action. Required for GDPR Art.22, EU AI Act Art.13, HIPAA audit trail, SEC/FINRA trading compliance.',
    inputSchema: {
      type: 'object',
      properties: {
        agent_id: {
          type: 'string',
          description: 'Agent identifier (e.g., "trading_bot_v1", "hr_decision_engine")',
        },
        payload: {
          type: 'object',
          description: 'Event payload containing decision data (JSON object)',
        },
        previous_hash: {
          type: 'string',
          description: 'Optional hash of previous event for chain integrity',
        },
      },
      required: ['agent_id', 'payload'],
    },
  },

• src/index.ts:46-63 (helper)

  Helper function - callPythonBridge() spawns the Python bridge as a subprocess and parses JSON stdout, used by all tool handlers including piqrypt_stamp_event.

  function callPythonBridge(command: string, params: any): any {
    const pythonCmd = process.env.PIQRYPT_PYTHON
      || (process.platform === 'win32' ? 'python' : 'python3');
  
    const result = spawnSync(
      pythonCmd,
      [PYTHON_BRIDGE, command, JSON.stringify(params)],
      { encoding: 'utf-8', timeout: 30000 }
    );
  
    if (result.error) throw new Error(`PiQrypt bridge spawn error: ${result.error.message}`);
    if (result.status !== 0) throw new Error(`PiQrypt bridge error: ${result.stderr}`);
  
    const stdout = result.stdout;
    const jsonStart = stdout.indexOf('{');
    if (jsonStart === -1) throw new Error(`No JSON in bridge output: ${stdout}`);
    return JSON.parse(stdout.slice(jsonStart));
  }

• src/index.ts:72-89 (schema)

  Input schema for piqrypt_stamp_event - defines agent_id (string), payload (object), previous_hash (string, optional). Required: agent_id and payload.

  inputSchema: {
    type: 'object',
    properties: {
      agent_id: {
        type: 'string',
        description: 'Agent identifier (e.g., "trading_bot_v1", "hr_decision_engine")',
      },
      payload: {
        type: 'object',
        description: 'Event payload containing decision data (JSON object)',
      },
      previous_hash: {
        type: 'string',
        description: 'Optional hash of previous event for chain integrity',
      },
    },
    required: ['agent_id', 'payload'],
  },