鎒j:.dZddlmZddlZddlZddlZddlmZmZm Z ddl m Z ddl m Z ddl mZddl mZdd lmZGd d ejZGd d eZGddeZGddeZe dZe dZGddejeeZGddejeeZGddejeeefZeezezZGddedZGddedZ Gddee j!Z"Gd d!ee#Z$Gd"d#ee j%Z&Gd$d%ee j'Z(Gd&d'ee)efZ*Gd(d)ee efZ+Gd*d+ee j,Z-daOBase definitions for Antigravity SDK Hooks v2. This module defines the interface for Hooks and the standard result types returned by their lifecycle callbacks. Hooks can be defined as classes or by using decorators (e.g. `@pre_turn`). Decorators automatically wrap functions into Hook instances. Wrapped functions can optionally accept the hook's context: - By naming the parameter `context` (e.g. `async def my_hook(context, data)`) - By type-hinting it as `HookContext` (e.g. `async def my_hook(ctx: HookContext, data)`) The context can be placed in any position (first or second). ) annotationsN)AnyGenericTypeVar)types)AskQuestionInteractionSpec) HookResult)QuestionHookResult)statec&eZdZdZddfd ZxZS) HookContextz&Base context for hooks to share state.NparentHookContext | NonecLt|dSN)rsuper__init__)selfr __class__s LC:\Projects\DSCons\.venv\Lib\site-packages\google\antigravity\hooks\hooks.pyrzHookContext.__init__3s$ GGF#####N)rr__name__ __module__ __qualname____doc__r __classcell__rs@rr r 0sH..$$$$$$$$$$$rr c"eZdZdZfdZxZS)SessionContextz$Context scoped to an entire session.cLtddSrr)rrs rrzSessionContext.__init__:s$ GGD!!!!!rrr s@rr"r"7s>,,"""""""""rr"c$eZdZdZdfd ZxZS) TurnContextz Context scoped to a single turn.session_contextr"cLt|dSrr)rr&rs rrzTurnContext.__init__As$ GGO,,,,,r)r&r"rr s@rr%r%>sC((----------rr%c$eZdZdZdfd ZxZS)OperationContextz8Context scoped to a specific operation (e.g. tool call). turn_contextr%cLt|dSrr)rr*rs rrzOperationContext.__init__Hs$ GGL)))))r)r*r%rr s@rr)r)EsC@@**********rr)TRc4eZdZdZejd dZd S) InspectHookz/Read-only, non-blocking hook for observability.contextr datar,returnNonec KdS)zwRuns the inspection hook. Args: context: The hook context. data: The data to inspect (read-only). Nrr0r1s rrunzInspectHook.runVs  DrN)r0r r1r,r2r3rrrrabcabstractmethodr7r5rrr/r/Ss<77      rr/c4eZdZdZejd dZd S) DecideHookz.Read-only, blocking hook for policy decisions.r0r r1r,r2r c KdS)zRuns the decision hook. Args: context: The hook context. data: The data to make a decision on. Returns: A HookResult indicating allow/deny. Nr5r6s rr7zDecideHook.rund  DrN)r0r r1r,r2r r8r5rrr<r<as<66        rr<c4eZdZdZejd dZd S) TransformHookz1Modifying, blocking hook for data transformation.r0r r1r,r2r-c KdS)zRuns the transformation hook. Args: context: The hook context. data: The data to transform. Returns: The transformed data. Nr5r6s rr7zTransformHook.runur>rN)r0r r1r,r2r-r8r5rrr@r@rs<99        rr@ceZdZdZdS)OnSessionStartHookz Invoked when the session starts.Nrrrrr5rrrCrCs(($rrCceZdZdZdS)OnSessionEndHookzInvoked when the session ends.NrDr5rrrFrFs&&$rrFceZdZdZdS) PreTurnHookzInvoked before a turn starts. The `data` parameter receives the user's prompt (types.Content), which can be a single string/media object or a list of multimodal primitives. NrDr5rrrHrH $rrHceZdZdZdS) PostTurnHookzrInvoked after a turn ends. The `data` parameter receives the model's response text for the completed turn. NrDr5rrrKrKrIrrKceZdZdZdS)PreToolCallDecideHookazInvoked before a tool call to decide if it should proceed. The `data` parameter receives the `types.ToolCall` object. Hooks can return: - `HookResult(allow=True)` to allow execution with original arguments. - `HookResult(allow=True, modified_args={...})` to allow execution with modified arguments. - `HookResult(allow=False, message="...")` to deny execution. NrDr5rrrMrMs$rrMceZdZdZdS)PostToolCallHookzInvoked after a tool call completes. The `data` parameter receives the `types.ToolResult` object containing the tool execution details. NrDr5rrrOrOrIrrOceZdZdZdS)OnToolErrorHookaInvoked when a tool fails, allowing authors to shape the failure message. Receives the raised exception and returns an optional custom error string. If a non-empty string is returned, it replaces the default stacktrace or error message delivered to the model. If None is returned, default error formatting is used. Works symmetrically across built-in and custom tools. The hook cannot fix or retry the tool call on its own, but it can guide the agent toward a specific resolution. To customize failure messages or provide recovery fallbacks for your tool, you can either return a custom error string from this hook or do so directly within your tool implementation. NrDr5rrrQrQs  $rrQceZdZdZdS)OnInteractionHookzHook invoked when the agent needs user interaction. This is a superset of QuestionHook and handles all user interactions. NrDr5rrrSrSs $rrSceZdZdZdS)OnCompactionHookzInvoked when a context compaction event occurs. Compaction is triggered by the harness when the context window exceeds the configured token threshold. This hook provides an observability point for logging, metrics, or UI notifications. NrDr5rrrUrUs$rrUparaminspect.Parameterr2boolc|jdkrdS|j}|tjjurdS|t krdSt |tr#|dd}|dkrdSdS)z1Checks if a parameter represents the HookContext.r0TF.r ) name annotationinspect Parameteremptyr isinstancestrsplit)rVr] simple_names r_is_context_parameterres Z9 4*7$*** 5; 4 C  ""3''+Km## T rT) pass_datahook_cls type[Any]rfcRGdd|Gdd|fd}|S)aCreates a decorator that wraps a function as a Hook subclass. Each decorator-created hook delegates its ``run()`` to the wrapped function and remains directly callable for convenience. Both synchronous and asynchronous functions are supported. If the wrapped function accepts `context` (either by name 'context' or by type hint matching HookContext), the HookContext will be passed to it. Args: hook_cls: The concrete Hook class to subclass. pass_data: If True, the wrapped function receives the hook's ``data`` argument. If False (e.g. session start/end), it is called with no arguments by default. Returns: A decorator that converts a function into a Hook instance. c&eZdZdZdZd dZd Zd S) 3_make_hook_decorator.._FunctionHookWithData;Internal hook implementation wrapping a decorated function.cL||_||_tj||dSrf_call_fn functoolsupdate_wrapperrrocall_fns rrz<_make_hook_decorator.._FunctionHookWithData.__init__)dfdmtQ'''''rr0r r1rr2cnK|||}tj|r|d{VS|Srrpr^ isawaitablerr0r1ress rr7z7_make_hook_decorator.._FunctionHookWithData.run!sC MM'4 ( (c  S ! !yyyyyy jrc\K|j|i|}tj|r|d{VS|Srror^rxrargskwargsrzs r__call__z<_make_hook_decorator.._FunctionHookWithData.__call__'F DFD #F # #c  S ! !yyyyyy jrNr0r r1rr2rrrrrrr7rr5rr_FunctionHookWithDatarkLEE(((  rrc&eZdZdZdZd dZd Zd S) 1_make_hook_decorator.._FunctionHookNoDatarlcL||_||_tj||dSrrnrss rrz:_make_hook_decorator.._FunctionHookNoData.__init__0rurr0r r1rr2clK||}tj|r|d{VS|Srrwrys rr7z5_make_hook_decorator.._FunctionHookNoData.run5sA MM' " "c  S ! !yyyyyy jrc\K|j|i|}tj|r|d{VS|Srr|r}s rrz:_make_hook_decorator.._FunctionHookNoData.__call__;rrNrrr5rr_FunctionHookNoDatar-rrrc tj}t|j}t |}d}t |D]\}}t|r|}n|dk} r|r|dkri|dkr/|ttn|jtfi||j tin||tnZ|tn8|r"|tn|n-#t$r }tdj d||d}~wwxYwr<|r)|dkr|dkr} n||j fd} n fd} nfd}  | S|r} nfd }  | S) Nr[rzInvalid signature for hook 'z': c|fi|iSrr5)ctxd context_namefuncs rz9_make_hook_decorator..decorator..ns$$q*H*H\34G*H*Hrc|Srr5rrrs rrz9_make_hook_decorator..decorator..qsS rc|Srr5rs rrz9_make_hook_decorator..decorator..tsdd1ggrcSrr5)rrs rrz9_make_hook_decorator..decorator..|s TTVVr) r^ signaturelist parametersvalueslen enumeraterebindobjectr\ TypeErrorr)rsigparams num_params context_idxip is_statefule call_fn_datacall_fn_nodatarrrrfs` @r decoratorz'_make_hook_decorator..decoratorAsb  D ! !C #.'')) * *FVJK&!!1 q ! !  #K    1__ahhvxx****chvxxHHF;$7$ > >1 > >    7  . ?? A  LL"+.3LHHHHHLL2111,,.--- " "4 6 66 ,++++ ~ 6 66s>C/E.. F8FFr5)rgrfrrrs ` @@r_make_hook_decoratorrs(h(H(=7=7=7=7=7=7=7~ rFceZdZdZdS) _PreStepHookz;Invoked when a step is first seen in the stream (internal).NrDr5rrrrsCCCCrrceZdZdZdS) _PostStepHookz)Invoked when a step completes (internal).NrDr5rrrrs1111rr)rVrWr2rX)rgrhrfrX)=r __future__rr9rqr^typingrrrgoogle.antigravityrgoogle.antigravity.typesrr r google.antigravity.utilsr state_module StateStorer r"r%r)r,r-ABCr/r<r@HookrCrFContentrHrbrKToolCallrM ToolResultrO ExceptionrQrSSteprUrerpre_turnpre_tool_call_decideon_interaction on_compactionon_session_starton_session_end post_turnpost_tool_call on_tool_errorrr _pre_step _post_stepr5rrrs[ #""""" (((((((((($$$$$$??????//////777777:::::: $$$$$,)$$$"""""["""-----+---*****{*** GCLL GCLL      #'71:         '!*   "     CGWQT]   "Z-/T* {4(*U]+;s#     Ju~6   {5#34mIsN3(,.@@A{5:.&DH{{{{{{@  , ,++,ABB%%&788$$%566 ''(:eLLL%%&6%HHH  . . %%&677$$_55 DDDDD;uz*DDD22222K +222 !  . . ! !- 0 0 r