hermes_state_terminal.py 9.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170
  1. """Private terminal-only tombstone queries; never reconstruct executable history.
  2. The authenticated edge supplies the original principal/target/request and frozen
  3. payload. A retired target permits only that exact digest, never fresh admission.
  4. Worker receipt reads additionally require the original private adoption proof.
  5. """
  6. import hmac
  7. import json
  8. from hermes_state_runtime import ADMITTED_REQUEST_CONFLICT, RuntimeStoreError, _epoch, _json, _row, _secret_digest, _text, admission_fingerprint
  9. RESULT_PREFIX = 'gateway.admission.result.v1.'
  10. ADMISSION_PREFIX = 'gateway.terminal_admission.v1.'
  11. IDENTITY_PREFIX = 'gateway.terminal_identity.v1.'
  12. WORKER_PREFIX = 'gateway.terminal_worker.v1.'
  13. def compact_result(result, *, user_message=None):
  14. """Retain replay/accounting and current-turn API output, never cumulative history."""
  15. result = dict(result)
  16. value = result.get('result')
  17. if not isinstance(value, dict):
  18. return result
  19. value = dict(value)
  20. # The tool schema list rides every turn result for in-process transcript logging; it is the
  21. # same session-wide copy each turn (tens of KB, more with MCP) and no stored-result reader uses it.
  22. value.pop('tools', None)
  23. messages = value.get('messages')
  24. if isinstance(messages, list):
  25. # Agent results include all previous turns. APIs only project this turn's
  26. # assistant/tool suffix; previous_response_id stores its own history. Compression
  27. # is the exception: its replacement snapshot is the only immutable record of the
  28. # rewritten prefix for this turn. A later live transcript may include a successor.
  29. if not value.get('_compressed') and not value.get('_messages_are_turn_suffix'):
  30. from agent.turn_context import reanchor_current_turn_user_idx
  31. anchor = value.get('current_turn_user_idx')
  32. if not (type(anchor) is int and 0 <= anchor < len(messages)
  33. and isinstance(messages[anchor], dict) and messages[anchor].get('role') == 'user'):
  34. anchor = reanchor_current_turn_user_idx(messages, user_message)
  35. value['messages'] = messages[anchor + 1:]
  36. if anchor >= 0 and isinstance(messages[anchor], dict) and messages[anchor].get('api_content'):
  37. # The user row as the model saw it (memory prefetch, plugin context): a chained
  38. # Responses turn replays it instead of a row rebuilt from the raw request text.
  39. value['_turn_user_row'] = {k: messages[anchor][k] for k in ('role', 'content', 'api_content')}
  40. # Recovery/verification nudges are later user-role rows within this same turn.
  41. # Consumers must not infer a new boundary from them after the real anchor is gone.
  42. value['_messages_are_turn_suffix'] = True
  43. value.pop('current_turn_user_idx', None)
  44. result['result'] = value
  45. return result
  46. # Top-level row key only ``encode_result`` writes. The row's top level is built by the gateway
  47. # (``result``/``usage``), never by the agent or a message, so message fields can't collide with it.
  48. _STORED = '_stored'
  49. def encode_result(result):
  50. """The stored row keeps the reply once. When the turn's closing assistant message carries
  51. exactly ``final_response``, its ``content`` is stored as null and the row gets
  52. ``_stored: {v: 1, reply_ref: <that message's index>}``. Retirement drops ``messages`` and
  53. keeps ``final_response``, so a deleted session's exact retry still has its reply. A result
  54. that already has ``_stored`` is stored whole with that value escaped as ``{v: 1, raw: ...}``."""
  55. if not isinstance(result, dict):
  56. return result
  57. if _STORED in result:
  58. return {**result, _STORED: {'v': 1, 'raw': result[_STORED]}}
  59. value = result.get('result')
  60. if not isinstance(value, dict) or not isinstance(value.get('messages'), list):
  61. return result
  62. reply, messages = value.get('final_response'), list(value['messages'])
  63. last = next((i for i in range(len(messages) - 1, -1, -1) if isinstance(messages[i], dict)
  64. and messages[i].get('role') == 'assistant'), None)
  65. if not (isinstance(reply, str) and reply and last is not None and messages[last].get('content') == reply):
  66. return result
  67. messages[last] = {**messages[last], 'content': None}
  68. return {**result, 'result': {**value, 'messages': messages}, _STORED: {'v': 1, 'reply_ref': last}}
  69. def load_result(text):
  70. """Decode a stored result row. Only a row carrying ``encode_result``'s exact envelope is
  71. decoded (to the dict it encoded, key order included); every other row, including all rows
  72. written before it, is returned as stored."""
  73. # Decodes in place: safe only because each call parses its own copy. A cache in front of this
  74. # must hand out copies, never the decoded dict itself.
  75. result = json.loads(text)
  76. if not isinstance(result, dict) or not isinstance(envelope := result.get(_STORED), dict):
  77. return result
  78. if envelope.keys() == {'v', 'raw'} and type(envelope['v']) is int and envelope['v'] == 1:
  79. result[_STORED] = envelope['raw']
  80. return result
  81. value, ref = result.get('result'), envelope.get('reply_ref')
  82. messages = value.get('messages') if isinstance(value, dict) else None
  83. if not (envelope.keys() == {'v', 'reply_ref'} and type(envelope['v']) is int and envelope['v'] == 1
  84. and type(ref) is int and isinstance(messages, list) and 0 <= ref < len(messages)
  85. and isinstance(value.get('final_response'), str) and isinstance(messages[ref], dict)
  86. and messages[ref].get('role') == 'assistant' and messages[ref].get('content', 0) is None):
  87. return result
  88. messages[ref] = {k: value['final_response'] if k == 'content' else v for k, v in messages[ref].items()}
  89. del result[_STORED]
  90. return result
  91. def identity_key(principal_id, session_id, request_id):
  92. return IDENTITY_PREFIX + admission_fingerprint(canonical_target=session_id,
  93. payload={'principal': principal_id, 'request': request_id})
  94. def terminal_api_admissions(conn, request_id):
  95. """Retired API admissions that carried *request_id*: a deleted session's tombstones, kept for
  96. the exact-retry horizon, still spend its Idempotency-Key for every other target."""
  97. return [json.loads(row[0]) for row in conn.execute(
  98. "SELECT value FROM state_meta WHERE key GLOB ? "
  99. "AND json_extract(value, '$.principal_id')='api' AND json_extract(value, '$.request_id')=?",
  100. (ADMISSION_PREFIX + '*', request_id))]
  101. def terminal_admission(conn, admission_id):
  102. saved = conn.execute('SELECT value FROM state_meta WHERE key=?',
  103. (ADMISSION_PREFIX + admission_id,)).fetchone()
  104. return json.loads(saved[0]) if saved else None
  105. def retry_terminal_admission(db, *, epoch, principal_id, session_id, request_id, payload, intent='queue'):
  106. """None means a live target; a retired miss/conflict is a definitive refusal.
  107. This is a read-only identity lookup, not authorization to attach, restore a
  108. route, or write. HTTP authentication/grant checks must precede this query.
  109. """
  110. for value in (principal_id, session_id, request_id):
  111. _text(value)
  112. digest = admission_fingerprint(canonical_target=session_id,
  113. payload={'input': json.loads(_json(payload)), 'intent': intent})
  114. with db._read_ctx() as conn:
  115. _epoch(conn, epoch)
  116. from hermes_state_mutation_retirement import RETIRED_PREFIX
  117. if not conn.execute('SELECT 1 FROM state_meta WHERE key=?', (RETIRED_PREFIX + session_id,)).fetchone():
  118. return None
  119. saved = conn.execute('SELECT value FROM state_meta WHERE key=?',
  120. (identity_key(principal_id, session_id, request_id),)).fetchone()
  121. if saved is None:
  122. raise RuntimeStoreError('not_found')
  123. row = terminal_admission(conn, json.loads(saved[0]))
  124. if row['payload_digest'] != digest:
  125. raise RuntimeStoreError('admission_conflict', **ADMITTED_REQUEST_CONFLICT)
  126. return _row(row)
  127. def terminal_worker_receipt(db, *, execution_id, session_id, generation, sequence,
  128. adoption_secret, payload_digest):
  129. """Exact retired producer evidence; possession never reactivates the worker."""
  130. proof = _secret_digest(adoption_secret)
  131. with db._read_ctx() as conn:
  132. saved = conn.execute('SELECT value FROM state_meta WHERE key=?',
  133. (WORKER_PREFIX + execution_id,)).fetchone()
  134. if saved is None:
  135. raise RuntimeStoreError('not_found')
  136. worker = json.loads(saved[0])
  137. if worker['session_id'] != session_id or not hmac.compare_digest(worker['adoption_digest'], proof):
  138. raise RuntimeStoreError('permission_denied')
  139. if type(generation) is not int or generation != worker['generation']:
  140. raise RuntimeStoreError('stale_generation')
  141. receipt = next((r for r in worker['receipts'] if r['sequence'] == sequence), None)
  142. if receipt is None:
  143. raise RuntimeStoreError('stale_generation')
  144. if receipt['payload_digest'] != payload_digest:
  145. raise RuntimeStoreError('admission_conflict')
  146. if receipt['result_json'] is None:
  147. raise RuntimeStoreError('stale_generation')
  148. return json.loads(receipt['result_json'])